# YTAPI

> Transcript API for YouTube videos, plus video metadata, playlists, channels and search. One HTTPS call returns a video's captions as segments, word timings, Markdown, SRT or VTT.
> Docs: https://docs.ytapi.dev
> Full Specs: https://ytapi.dev/llms-full.txt
> OpenAPI: https://ytapi.dev/openapi.json
> Base URL: https://api.ytapi.dev/v1
> MCP server: https://api.ytapi.dev/mcp (Streamable HTTP; OAuth sign-in or Authorization: Bearer <API_KEY>; setup: https://docs.ytapi.dev/agent-setup/#mcp)
> SDKs: Python `pip install ytapi-sdk`, JavaScript/TypeScript `npm install @ytapi/sdk` (https://docs.ytapi.dev/sdks)

## When to use YTAPI
- You need the captions of a public YouTube video (including Shorts) as text or timed segments, for example to summarize, search, translate, quote or index it.
- You need word-level timestamps from auto-generated captions (`word_level=true`).
- You are calling from a server or cloud function where direct requests to YouTube get blocked.
- The video is new, from a small channel or has few views. Nothing has to be cached first: a video YTAPI hasn't fetched before is fetched from YouTube on request. In early October 2026, over 99% of customers' transcript requests were for videos YTAPI had never fetched before, with a median of under 300 ms on YTAPI's servers (644 ms measured from clients in four regions, network included).
- You want to list a channel's or playlist's videos, or search YouTube, without a Google Cloud project or quota.

## When not to use it
- The video has no captions. YTAPI returns the caption tracks YouTube has (404 `captions_disabled` otherwise) and does not run speech-to-text.
- Private, members-only or deleted videos. These return an error and cost nothing.
- Downloading video or audio files. YTAPI returns text and metadata only.

## Errors and billing
- Errors are JSON: `{"error": {"code": "...", "message": "...", "retryable": false}}`.
- Only HTTP 200 responses cost a credit. 404s, 429s and 5xx are free.
- 429 means your key is over its rate limit; wait and retry. Slow or refused fetches from YouTube are retried server-side before responding, so clients rarely need their own retry loop.

## Free tools (no key)
- YouTube transcript generator: https://ytapi.dev/tools/youtube-transcript (copy or download TXT, Markdown, SRT)
- YouTube subtitle downloader: https://ytapi.dev/tools/youtube-subtitle-downloader (SRT, VTT, TXT in any caption language the video has)
- The tools are for people, one video at a time and rate limited. Agents and code should use the API below.
- Chrome extension: https://chromewebstore.google.com/detail/jiilbclplkkniekajhmocbnibcdpnmng (the open video's transcript in a side panel: copy, download, or summarize with ChatGPT, Claude or Grok; bulk download a channel's or playlist's transcripts with a free account)

## Get an API key
- Sign up at https://ytapi.dev/auth/login?utm_source=llms (Google, GitHub or an email code). New accounts get 200 free credits; no card.
- Create a key at https://ytapi.dev/app/api-keys?utm_source=llms (keys start with `sk_`).
- An agent can create the account for its user without a browser: the user gives an email address and reads back a 6-digit code (see https://docs.ytapi.dev/agent-signup/).
- Until a credit pack is bought, a key can make 1 request per second and 100 requests per day (UTC). Credit packs: https://ytapi.dev/?utm_source=llms#pricing

## Authentication
Pass your API key as a Bearer token:
```http
Authorization: Bearer <API_KEY>
```

## Key Endpoints

### 1. Transcripts
- `POST /v1/transcripts` or `GET /v1/transcripts?video_id={id}&format={format}`
- Formats: `markdown` (paragraphs with timestamps), `word_timestamps`, `segments`, `sentences`, `srt`, `vtt`, `text`, `json3`
- Parameter `word_level=true`: Includes millisecond start/end word offsets.
- Cost: 1 Credit

### 2. Video Metadata
- `GET /v1/videos/{id}/basic-info`: Free. Video title, duration, channel, and subtitle languages.
- `GET /v1/videos/{id}/video-info`: Full metadata: description, view, like and comment counts, chapters, keywords, live and upcoming status, YouTube's AI summary when shown, description links and hashtags, music, and related videos.
- `GET /v1/videos/{id}/heatmap`: YouTube's "most replayed" graph, condensed: most replayed moment, up to five peaks and a 20-part curve. 404 heatmap_unavailable (free) when a video has none.
- `GET /v1/videos/{id}/comments?sort=top|newest&cursor={token}`: Comments, about 20 per page, with likes and reply counts; `/comments/replies?cursor={replies_cursor}` for replies.
- Cost: 1 Credit each (comments: per page); basic-info is free

### 3. Playlists
- `GET /v1/playlists/{id}?cursor={token}`: Playlist title, author, video count and videos; pass next_cursor as cursor for the next page (1 Credit per page).

### 4. Channels
- `GET /v1/channels/{id}`: Channel profile, subscriber count, avatar, banner, and verified status (1 Credit).
- `GET /v1/channels/{id}/latest`: The channel's most recent uploads (1 Credit).
- `GET /v1/channels/{id}/videos?sort_by=newest|popular|oldest&cursor={token}`: All uploads with pagination (1 Credit per page).
- `GET /v1/channels/{id}/playlists?cursor={token}`: Channel playlists with pagination (1 Credit).

### 5. Search & Suggestions
- `GET /v1/search?q={query}&type=video|channel|playlist&limit=20` (1 Credit)
- `GET /v1/search/suggestions?q={query}` (0 Credits / Free)

### 6. Batch Processing
- `POST /v1/batch`: Concurrent extraction of up to 100 tasks with isolated error handling.
- Cost: 1 Credit per successful task.