YouTube API reference

One endpoint, one key. Send a video id or link and get one caption track as plain text plus timed segments. The uploader’s captions come before YouTube’s automatic ones. See the YouTube API: overview, pricing, and free tier.

Transcript

GET /v1/youtube/transcript · 1 request

curl -G https://api.clair.im/v1/youtube/transcript \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "video_id=jNQXAC9IVRw"

Parameter	Required	Contract
`video_id`	yes	The 11-character id, such as `dQw4w9WgXcQ`, or a watch, shorts, embed, live, or youtu.be link.
`language`	no	Caption language code, such as `en`, `de`, or `pt-BR`. `pt` also matches `pt-BR`. Default: English, else the first uploaded track.

The body is transcript: language (the track’s code), kind (manual for the uploader’s captions, auto for YouTube’s), text (every segment joined by spaces), and segments[] with start_ms, duration_ms, and text. query.video_id is the id, even when you sent a link.

{
  "engine": "youtube",
  "family": "video",
  "query": { "video_id": "jNQXAC9IVRw", "language": null },
  "transcript": {
    "language": "en",
    "kind": "manual",
    "text": "All right, so here we are, in front of the elephants ...",
    "segments": [
      { "start_ms": 1200, "duration_ms": 2160, "text": "All right, so here we are, in front of the elephants" }
    ]
  }
}

Clair reads the captions a video offers to any signed-out viewer. It does not transcribe audio.

Errors

A video that does not exist or is unavailable returns 404 not_found. So does a video with no captions, and a language the video lacks; that message lists the languages it has. A video_id that is not an id or a YouTube link, or a malformed language, is 400. Private and age-restricted videos need a signed-in viewer, so Clair cannot read them; they fail with 502. Auth, plans, rate limits, and error codes: Authentication.

​Transcript

​Errors

Transcript

Errors