Create or attach to a transcription job, or get an instant result

The default way to transcribe one episode: one call, no quote first. Accepts exactly one of four input shapes (url, feed_url + guid, episode_id, or upload_id); supplying more than one, or fields from more than one shape, fails schema validation. Returns a synchronous result on a cache hit or publisher-transcript passthrough, or 202 with a job to poll on a miss. dry_run: true returns a quote and creates neither a job nor a reservation.

Spend cap. max_credits is the most this call may take. It is compared with the job’s reservation ceiling (the estimate plus 25%, the most a job can settle at) or, for a cached episode, with the cached-read price for this caller, before anything is reserved; a call that could take more is refused 422 max_credits_exceeded with the figure in the message. The cap never lowers the reservation. A dry run with max_credits refuses exactly when the call would.

Every job belongs to a group. A single-episode submission is a job group of one: the same submission sequence a quote’s confirm fans out over N members, run once, so the two can never disagree. The accepted job carries its group_id, which GET /v1/groups/{group_id} and POST /v1/groups/{group_id}/cancel accept. An Idempotency-Key, when sent, is honoured at the group: a repeat returns the original job — or the original cached read — and charges nothing further; its status is then the job’s current state. A repeat that arrives while the original is still running — its group begun, its member not yet landed — is 409 request_in_progress: retry with the same key shortly, never a new one, which would start a second job for the same episode.

Uploads. upload_id names a file the caller announced with POST /v1/uploads and PUT. It is verified exactly as a quote verifies one — this account’s and unexpired, arrived, and matching the announced size and SHA-256 — and refused with its own code when it is not: 404 upload_not_found, 409 upload_not_received (retryable once the PUT lands), or 422 upload_mismatch. It is priced from the declared duration.

Upload episodes. episode_id may name an episode created from the caller’s own upload; it resolves against the upload’s stored revision, and an episode that resolves to another account’s upload answers 404 before dry-run pricing or cache access runs. A cache miss still prices and reserves at the upload’s declared-duration ceiling, and may subsequently fail upload_missing if the underlying object has since expired. A cached transcript stays readable after the source upload’s retained_until passes.

Not yet served on this path (0.4.0). format other than json is refused with invalid_request here — the read operations deliver the raw formats — and a cache hit above the inline limit is delivered by reference as TranscriptRead.transcript_url; language is accepted and recorded nowhere.

Delivery format. format: json (or omitted) returns application/json. format: text|srt|vtt|md returns the raw artifact under its own media type (text/plain, application/x-subrip, text/vtt, text/markdown) — never a JSON wrapper around a string. Because a raw body has nowhere to put provenance, those responses carry it in headers instead: X-Transcript-Episode-Id, X-Transcript-Source, X-Transcript-Timing-Precision, and X-Credits-Charged. The single content-type switch: a payload over the ~5 MB inline limit returns 200 application/json with { transcript_url, expires_at } in every format — including the raw ones, whose declared media type therefore does not apply to that one case. A 202, a dry-run quote, and every error are always application/json regardless of format.