AI transcription

Most YouTube videos have a caption track to read. Short-form video and podcasts usually do not. When there are no captions, the audio is transcribed instead — asynchronously, because it takes real time.

1. A fetch with no captions tells you so

A transcript request for a source with no caption track fails with a reason code, and the failure carries an ai_fallback block saying whether transcription could serve it instead. Failed requests are not charged.

{
  "ok": false,
  "error": { "code": "no_captions" },
  "ai_fallback": {
    "available": true,          // we can transcribe this
    "cost_credits": 1,
    "balance": 97
  }
}

When available is false, an unavailable_reason says why — the input is not something we can transcribe, for instance — and retrying will not help.

2. Ask for transcription

Repeat the request with ai_fallback: true. This skips the caption lookup entirely and goes straight to the audio.

POST /api/v1/transcripts/video

{ "url": "https://www.tiktok.com/@user/video/7137723462233555205", "ai_fallback": true }

You get 202 Accepted with a job to poll, not a transcript. Nothing is charged at this point — the credit is taken when the transcript is delivered.

{
  "ok": true,
  "status": "processing",
  "job_id": "asr_01HZY4T7Q2",
  "poll_url": "/api/v1/transcripts/jobs/asr_01HZY4T7Q2",
  "data": { "kind": "transcript_job" }
}

3. Poll the job

Poll poll_url until status is no longer processing. Note that a still-running job returns 200, not 202 — branch on status, never on the HTTP code.

GET /api/v1/transcripts/jobs/asr_01HZY4T7Q2

# still working
{ "ok": true, "status": "processing", "data": null }

# done — 1 credit charged
{ "ok": true, "status": "completed", "data": { … }, "credits_spent": 1 }

# gave up
{ "ok": false, "status": "failed", "error": { "code": "asr_failed" } }

Jobs are scoped to the key that created them: polling someone else's job id returns 404, not the transcript.

Webhook instead of polling

Pass callback_url (https only) with the transcription request and the finished transcript is POSTed to it, so you can skip polling entirely.

{ "url": "…", "ai_fallback": true, "callback_url": "https://example.com/hooks/transcript" }