Status, receipt, cancel and audio

A created operation has an ID: podcastId for podcasts and narration, taskId for News. Every operation endpoint answers only to the key that created it; another key of the same owner gets 404.

Status

GET …/:id returns the current status, a stageCode and progress. The stageCode set depends on the resource:

Resource	stageCode	Finished
Podcasts and narration	queued, researching, drafting, preparing, synthesizing, paused_insufficient_credits, completed, failed, cancelled	completed
News	queued, researching, drafting, synthesizing, paused_insufficient_credits, ready, failed, cancelled	ready

paused_insufficient_credits waits for a top-up and is not final; the same episode resumes automatically. failed ends the current execution and does not trigger an automatic retry. Admissible retained work resumes on the same task and financial operation without repurchasing completed actions. For a failed Podcast or narration, the creating API key calls POST …/:podcastId/continuation-quote, then POST …/:podcastId/continue with the returned quoteId and an Idempotency-Key header. The quote accepts {} to retain the limit or {"maximumCredits": 100} to increase it; {"maximumCredits": null} removes the limit. Reducing the limit is refused. Repeating Continue retains its original quote and request key. Another API key of the same owner gets 404; inadmissible continuation gets 409 PODCAST_CONTINUATION_UNAVAILABLE. News can continue through the Mini App or an authorized operator without changing a numeric limit. An unknown external outcome requires separate proof: an API key grants no authority to attest no dispatch. If the provider acknowledged a failed Podcast request but the stream broke, an authorized operator may separately approve a new paid inference from retained evidence; the original unknown expense remains. cancelled remains final. A verified SpeechKit internal HTTP 500 is recorded as an unpaid refusal. The system retains a wait and automatically retries only the same audio chunk after a pause. A relay failure or unknown outcome gives no such permission. For an older unknown voice request, an authorized operator may separately approve a new paid attempt for that same chunk; the original hold remains pending reconciliation. If that attempt also has an unknown outcome, another physical attempt needs its own decision bound to that exact request. Earlier unknown expenses and holds remain; replaying a decision sends nothing again. An API key cannot approve that decision. Poll at a reasonable interval: each key has a per-minute request limit (see Limits).

A failed status request means observation is unavailable, not that generation failed. Keep the last confirmed status and retry the read. Check the original operation before creating another episode; recovery uses the retained input and completed actions.

Podcast, narration and News status may include optional recovery with the safe reason for a retained wait with state: "waiting" and a reasonCode:

• PROVIDER_FUNDING_READ_UNAVAILABLE or PROVIDER_FUNDING_INSUFFICIENT: waiting for model-service funding availability;
• VOICE_PROVIDER_WAITING: temporary voice-service unavailability after a confirmed safe refusal;
• VOICE_LOCAL_COMPLETION_WAITING: finishing retained audio or local result accounting.

This is not a new status or a request to top up the owner’s wallet. The same task and financial operation resume automatically after the saved retry time and an eligibility check. Retained audio is reused; a local assembly or accounting failure does not purchase synthesis again. Do not create another operation or send Continue for this wait. An unknown external outcome does not authorize an automatic repeat of a paid call. Optional accounting contains observed capturedCredits and heldCredits from the receipt; absent data does not mean zero. A hold may include an uncertain outcome of an earlier call.

Receipt

GET …/:id/receipt shows the billing version, cumulative reservation, actual charge and amount released. The current heldCredits is the reservation remaining after capture and release; it may remain for an unknown external outcome until confirming evidence is available. A version 4 Podcast or News episode updates its charge after each confirmed paid action; completed work remains charged after failure or cancellation. An uncertain provider outcome can leave the receipt pending reconciliation even after generation finishes. Historical Podcast and News receipts retain their original reservation and settlement amounts; tasks with unsupported saved plans cannot resume. When support refunded the charge, refundedCredits shows the refunded credits: they are back on the balance and in the key’s quota, and what remains charged is the final charge minus the refund. For V4, maximumCredits is the effective limit, or null without an episode cap; originalMaximumCredits is the original one. Optional budgetAuthorization links a change to a successful Continue confirmation. Prior amounts and paid results are not rewritten.

Cancel

POST …/:id/cancel stops an unfinished operation, including a Podcast or News episode waiting for a top-up; proved unused holds are released while confirmed costs stay on the receipt. Holds for uncertain provider outcomes remain until confirming evidence is available. A finished operation cannot be cancelled.

Audio

GET …/:id/audio serves the finished audio with Accept-Ranges: bytes and private no-store caching. A single valid range returns 206 with Content-Range; a malformed, multiple or unsatisfiable range returns 416 RANGE_NOT_SATISFIABLE.

The response streams a verified retained audio file after checking the creating API key, without loading the complete file into memory. Use the response Content-Type to identify the format: audio may be MP3, WAV or Ogg, so do not assign an .mp3 extension to every response. The Mini App’s browser player uses a separate HttpOnly media session and the same file stream; API clients continue to send their key in the Authorization header.