Prices and charging

Quote

POST …/quotes prices the operation and returns a quote:

• quoteId — passed to the create call together with the unchanged quote body;
• credits — the approximate forecast (expectedCredits, or 0 when unknown), not spending authority;
• maximumCredits — a separate operation limit, or null without an episode cap;
• expectedCredits — the approximate Podcast or News cost;
• expiresAt — when the quote expires.

A Podcast quote also shows its mode and expected stages. Podcast and News use billing version 4 and show a range and forecast confidence. Low confidence means there is not enough comparable data. maximumCredits is optional for Podcast: omitted or null means balance-funded work without an episode cap. An explicit positive safe integer is not reduced by duration, quality or forecast. The estimate may exceed that limit; it does not authorize spending. Developer News does not accept maximumCredits in its input and returns null; the API key’s separate quota still limits its spending.

Create and charge

A quote retains the agreed tariffs from the published pricing-policy and execution-catalog pair. Later price changes do not rewrite an accepted operation.

The create call takes the quote body plus quoteId. A new Podcast or News episode does not reserve the full limit. Before each paid request, it holds only that request’s maximum against the owner’s available balance and the key’s quota. After a confirmed result, it charges the increase in accumulated cost, rounded to credits, and releases the unused part of the hold. If the balance cannot fund the next request, the same taskId waits for a top-up and resumes automatically. Failure and cancellation keep confirmed costs on the receipt; an uncertain provider result keeps its hold until reconciliation: a deadline alone neither proves zero cost nor permits replay. A proved unsent model request releases its hold without a charge; an observed zero-cost actual call retains the agreed minimum-price rule. Reaching the episode limit or key quota with sufficient balance produces the corresponding reason instead of a balance pause. The owner of an admissible failed Podcast can separately confirm a higher limit or its removal through Continue in the Mini App: the task, operation, tariffs and paid results remain the same. The creating API key can confirm admissible Podcast or narration continuation through a separate quote; it grants no authority to attest that an external request was not sent. Ordinary News resume does not increase an explicit numeric limit.

Historical Podcast and News receipts retain their original reservation and settlement amounts; tasks with unsupported saved plans cannot resume. The receipt (…/receipt) shows the billing version, amount held, charged and released; reconciliation can remain pending after the generation reaches a final status. For V4, maximumCredits shows the effective limit, originalMaximumCredits the original one; optional budgetAuthorization links a change to a successful Continue confirmation. null means no episode cap, not zero expense.

Current heldCredits includes unresolved holds, including uncertain provider outcomes. Cumulative reservedCredits is not the current hold. Independently confirmed provider evidence can establish the original call’s expense, but cannot restore lost text or audio. A missing call identifier or a 404 response does not prove zero expense. Reconciliation also applies to a completed model call whose monetary expense remains unknown. It refines only the original monetary facts under the accepted agreement; completed content is not reopened and the model call is not purchased again.

Provider funding waits differ from an owner’s low credit balance. A temporary funding-read outage or measured insufficient provider funds retains the same operation without another model call. The owner need not top up their wallet for this; work resumes automatically when a fresh funding check permits spending. See Operation status.

A body that differs from the quote gets 409 QUOTE_FINGERPRINT_MISMATCH; another key’s quote gets 409 API_KEY_QUOTE_MISMATCH; an expired or already used quote gets 409 QUOTE_EXPIRED or 409 QUOTE_ALREADY_CONSUMED.

Idempotency

The Idempotency-Key header is required on create (8–128 characters of A-Za-z0-9._:-). A repeat with the same key and body returns the same operation; with a different body it gets 409 IDEMPOTENCY_CONFLICT. Idempotency is scoped to one API key: the same client key on two API keys creates two operations.

Save the body together with its quoteId and key before dispatch. Repeating an accepted creation requires the same quote, input and creating API key; a new quote with the previous Idempotency-Key is not a repeat of the original command. After an uncertain response, keep checking or repeating the original command. Only explicit acceptance: "rejected" certifies refusal before acceptance.

What is never returned

Responses contain credits, provider units, IDs and statuses — never internal USD cost, markup, payout or margin.