> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube API reference

> YouTube API: one public video's captions as text and timed segments, by video id or link.

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](https://clair.im/apis/youtube-transcripts).

## Transcript

`GET /v1/youtube/transcript` · **1 request**

```sh theme={null}
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.

```json theme={null}
{
  "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](https://clair.im/docs/authentication.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.