Skip to main content
The Quickstart prices a selection and confirms it as a group. For a single episode there is a shorter path: POST /v1/transcripts names one pointer and either returns the cached transcript at once, or accepts one job in a group of one.

​
Submit

Exactly one of url, feed_url + guid, or episode_id. 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.