How it works
How your transcript is made
Four layers, tried in order. Most requests are answered by the first two. The others exist so the API keeps working when the easy path doesn't.
Human captions
LiveCaptions the video's creator uploaded themselves. When these exist, you get them — they're the most accurate source. Marked source_type: "human" when you request ?meta=true.
Auto-generated captions
LiveIf there are no human captions, we fall back to YouTube's auto-generated track. Quality varies with audio clarity, but it covers the vast majority of spoken-word videos. Marked source_type: "auto".
Rotating residential proxy fetching
LiveYouTube periodically blocks requests from datacenter IP ranges — the reason most transcript scripts silently die one day. When that happens, we route the fetch through rotating residential proxies so your request still comes back. You don't see this layer; you just don't get the outage.
AI transcription
Rolling out with ProSome videos have no captions at all. For those, a Whisper-class speech-to-text model transcribes the audio directly. Today the API tells you when this would work — canTranscribeWithAI: true in the response — and the transcription itself is rolling out with the Pro tier.
What this means for you
Honest expectations, so you can build on them:
- Most videos just work. If a video has any captions — human or auto — you get a transcript from layer 1 or 2.
- Blocks are handled for you. Layer 3 exists precisely because YouTube blocks datacenter IPs from time to time. That resilience is the main thing you're outsourcing by using this API instead of a library.
- Caption-less videos aren't silently dropped. You get a structured
200response witherror,reason, andcanTranscribeWithAI: true— so your code can decide what to do, and can pick up AI transcription when Pro opens. - Slow videos time out honestly. If processing takes longer than 25 seconds you get a
408, not a hung connection. Retrying usually succeeds.