Using the API

AI transcription: jobs, polling and webhooks

What happens when a video has no captions, and how to collect the transcript when it does not arrive immediately.

Most short-form video and every podcast has no caption track to read. When there is nothing to read, the audio is transcribed instead. Transcription takes real time, so it returns a job rather than a transcript.

The 202 response

json

{
  "ok": true,
  "status": "processing",
  "job_id": "asr_…",
  "poll_url": "/api/v1/transcripts/jobs/asr_…"
}

Polling

Poll poll_url until status is no longer processing. Terminal states are completed and failed.

A running job returns 200, not 202. Branch on the status field, never on the HTTP status code.

Webhooks instead

Pass callback_url (https only) and the finished transcript is POSTed to you. The body is the same envelope the poll URL returns, signed with HMAC-SHA256 over the exact bytes in an X-TranscriptFetch-Signature: sha256= header. The job stays pollable either way, so a missed delivery is never a lost transcript.

Controlling it

Use mode: "captions" reads an existing track and fails if there is none, which is the only way to guarantee a synchronous answer. "audio" skips captions entirely. "auto" is the default.

Transcription is charged on delivery, so an enqueued job costs nothing until the transcript arrives.

Captions and AI transcription run behind a single request, so nothing in your code changes when a video has no caption track. See how transcription works.

Still stuck?

Open the chat launcher, bottom right, and include your request_id if you have one. Or email [email protected].