Skip to main content
The one-episode path, in full: POST /v1/transcripts names one pointer and either returns the cached transcript at once, or accepts one job and returns it to poll. No quote comes first. The Quickstart is the short version; Price a selection is the path for many episodes at once.

​
Submit

Exactly one of url, feed_url + guid, episode_id, or upload_id (a file you uploaded and PUT). Optional fields: Three answers are possible:
  • 200 with is_cached: true and the transcript inline: the episode was already transcribed. A cached read is charged, at the price on Credits, and the response carries X-Credits-Charged.
  • 202 with a job_id, its group_id, and the reservation: fresh work was accepted. The job holds reserved_credits until it settles.
  • 200 with dry_run: true: the price, and nothing else.

​
Idempotency

Idempotency-Key is any printable string up to 255 characters. Audivo keeps it for 24 hours with a hash of the body: the same key with the same body returns the original answer, the same job and no second reservation; the same key with a different body is refused as idempotency_conflict. Generate a fresh key per intended submission and reuse it on every retry of that one.

​
Poll

A job moves through these states, in this order, and never backwards:
Any state can end in failed; validating and queued can end in cancelled. While transcribing, progress reports chunks_done, chunks_total and percent; chunks are fifteen-minute pieces of the audio transcribed in parallel, so a long episode does not take proportionally longer. estimated_seconds on the accepted job is a processing estimate for choosing a poll interval, not audio length; every ten seconds is reasonable, and a finished hour of audio is typically minutes away. A terminal job reports what happened to the money: settled_credits and released_credits on completion, reservation_released: true on failure or cancellation. The sum is always the reservation.

​
Read

Once completed, the same URL with format returns the transcript:
Reading a job you paid for costs nothing, as often as you like. The shapes and the size limit are on Output formats.

​
Cancel

There is no single-job cancel; jobs live in groups, and POST /v1/groups/{group_id}/cancel cancels every member that has not started, releasing each reservation exactly once. A job the worker has already claimed runs to its end and settles normally.