Test the video before writing an adapter
Use the YouTube Transcript Inspector without an account to see the available native track and a real preview. Continue with the same video in a free workspace to retrieve the complete result. The Playground follows generated jobs and offers a copyable response.
For a repeatable first integration, use a Sheets-to-transcript or Markdown workflow, the MCP first-call example or the Python result-saving example.
Handle an immediate transcript or an accepted job
An HTTP 200 result includes content, lang, availableLangs, source, cached and requestId. With the default text=false, content is an array of segments. This illustrative segment starts 8.15 seconds into the video and covers 1.2 seconds.
{
"content": [{ "text": "Example segment", "offset": 8150, "duration": 1200, "lang": "en" }],
"lang": "en", "availableLangs": ["en"],
"source": "native", "cached": false, "requestId": "req_example"
}An HTTP 202 response contains a jobId. Save that identifier and poll GET /v1/transcript/{jobId} with the same workspace key. Stop on completed content, failed or cancelled. Polling does not consume another transcript request. The Python and Node.js guides include downloadable clients with a total waiting deadline.
Choose extraction and output independently
Use native when discovery must never generate audio, auto when the application needs generated fallback after confirmed caption absence, and generate to select audio transcription. A compatible cached result can complete immediately. A temporary upstream failure is an error, not evidence that the video has no captions.
Use text=true for a summary pipeline and retain segments for search, playback or clip selection. chunkSize groups text by characters, from 50 to 10,000; it is not a duration setting. lang expresses a preference and does not translate a transcript. Always inspect the language returned.
Check scope, quotas and observed reliability
Capslane v1 accepts YouTube URLs and video IDs. It does not accept arbitrary media uploads or promise access to private, removed, age-restricted or region-restricted videos. YouTube caption availability and audio transcription quality vary. Consult the error guide before adding retries.
The Free plan includes 50 transcript requests and 15 generated minutes per month, with one active generation. Accepted requests use the request allowance even when cached. Generated audio also uses the separate minute allowance; review current plan limits before a batch import.
The published benchmark method and corpus document a dated transport test with cache enabled. The Gems migration case describes a real internal product using both native extraction and generated jobs. These observations help evaluate the integration; they do not guarantee every future video.
For channels you manage, the official YouTube captions download API is another option: it requires OAuth authorization and permission to edit the video. Our official API guide explains that distinction.