V2: упрощённая модель транскриптов, принадлежащих пользователю. В приоритете быстрые попадания в кэш, единообразные ответы и никаких неожиданных переводов, если вы сами не запросили язык.
https://www.youtubetranscript.dev/api/v2/transcribehttps://www.youtubetranscript.dev/api/v2/batchhttps://www.youtubetranscript.dev/api/v2/jobs/{job_id}https://www.youtubetranscript.dev/api/v2/batch/{batch_id}https://www.youtubetranscript.dev/api/v2/channels/resolvehttps://www.youtubetranscript.dev/api/v2/channels/{channel_id}https://www.youtubetranscript.dev/api/v2/channels/historyСкачайте YAML, чтобы импортировать его в Postman или Insomnia, сгенерировать клиенты или вставить в ChatGPT / Claude.
Самый быстрый способ обработать одно видео. Транскрипты по субтитрам возвращаются за несколько секунд; ASR работает асинхронно, статус опрашивается через /api/v2/jobs/{job_id}.
Transcribe a single YouTube video. Returns immediately for caption-based videos; falls back to ASR (async) when allow_asr is true and captions are unavailable.
/api/v2/transcribevideostringобязательныйYouTube URL or 11-character video ID. Required unless upload_id is set.
upload_idstringTranscribe an uploaded media file instead of a YouTube video (see /uploads). Forces the ASR path; webhook_url required. The upload id is returned as video_id in results.
languageISO 639-1Preferred transcript language (e.g. en). If unavailable, captions in another language may be returned: transcript.language reports the actual language.
sourceauto | manual | asrPreferred transcript source. Default: auto. Use asr for audio transcription (async, requires webhook_url).
allow_asrbooleanFall back to ASR if captions fail. Required for ASR-only videos.
formatobject{ timestamp, paragraphs, words }: include extra structure in the transcript.
webhook_urluriWhen set, the response returns processing and the result is delivered to your URL. Required for ASR.
asr_optionsobjectRich ASR config: language (+ codeSwitching, medicalMode, keyTerms), translateTo, speaker diarization (speakerLabels, speakerId + type/known values, multichannel, exact or min/max expected speakers), speech understanding (topics, summary, moderation, PII, profanity, sentiment), and formatting (punctuation, text formatting, filler words, custom date/phone/email patterns). Billable add-ons increase cost: preview with /transcribe/estimate. See the AsrOptions schema in the OpenAPI spec.
Dry-run credit estimate. Returns the ASR base cost plus any add-on surcharge for the requested asr_options without creating a job or charging credits.
/api/v2/transcribe/estimatevideostringобязательныйYouTube URL or 11-character video ID.
sourceauto | manual | asrDefaults to asr for cost preview.
asr_optionsobjectSame shape as /transcribe. Add-on charges are prorated by duration.
Poll a single transcription job. Use this for ASR jobs returned from /transcribe. Returns 202 while running and 200 when complete. Completed ASR jobs include asr_intelligence (summary, topics, sentiment, etc.) when those options were enabled.
/api/v2/jobs/{job_id}job_idpathобязательныйIdentifier returned in the original transcribe response.
include_segmentsbooleanInclude segment-level timestamps in the transcript payload.
include_paragraphsbooleanInclude paragraph groupings.
include_wordsbooleanInclude word-level timestamps (ASR only).
Транскрибируйте собственные аудио- и видеофайлы через ASR-конвейер. Три шага: зарегистрируйте загрузку, отправьте байты методом PUT на подписанный URL, завершите загрузку. Затем вызовите /transcribe с upload_id. Результаты приходят на ваш вебхук, а статус опрашивается как у любой ASR-задачи.
Register an audio/video file upload and get a signed URL. PUT the raw file bytes to signed_url (with the file's Content-Type), finalize via /uploads/{upload_id}/complete, then transcribe with upload_id on /transcribe. Max 2GB and 8 hours per file.
/api/v2/uploadsfilenamestringобязательныйOriginal filename. The extension is preserved for content sniffing.
mime_typestringобязательныйMust start with audio/ or video/ (e.g. audio/mpeg, video/mp4).
size_bytesintegerобязательныйFile size in bytes. Max 2147483648 (2GB).
duration_secintegerобязательныйMedia duration in seconds. Max 28800 (8 hours). Used for the ASR credit estimate.
Finalize an upload after the PUT to signed_url succeeds. Verifies the file exists in storage and marks it ready. The upload can then be transcribed by passing upload_id to /transcribe (source="asr", webhook_url required).
/api/v2/uploads/{upload_id}/completeupload_idpathобязательныйUpload id returned by POST /uploads.
Транскрибируйте много видео одним запросом, затем опрашивайте статус или получайте результаты через вебхук.
Submit up to 3,000 videos in one request. Returns within 2 seconds; poll the returned poll_url or wait for the webhook.
/api/v2/batchvideo_idsstring[]обязательныйUp to 3,000 IDs depending on plan. Free = 10, Basic = 500, Pro = 1,500, Business = 3,000.
languageISO 639-1Preferred language for every video.
sourceauto | manual | asrPreferred transcript source. Default: auto. source=asr requires webhook_url.
allow_asrbooleanFall back to ASR when captions fail. webhook_url is required.
formatobject{ timestamp, paragraphs, words }: applied to every result.
webhook_urluriDelivers the completed batch payload. Required when allow_asr=true or source=asr.
asr_optionsobjectRich ASR config applied to every video transcribed via ASR (same shape as /transcribe). Billable add-ons apply per video.
Check the status of a batch. Returns 202 while processing and 200 when results are ready. Stop polling once status is "completed", "partial", or "failed": finished batches never change, and re-fetching one more than 60 times in 24h returns 429 with a Retry-After header.
/api/v2/batch/{batch_id}batch_idpathобязательныйBatch identifier returned from POST /batch.
Получайте список, загружайте, переводите и удаляйте сохранённые транскрипты, а также просматривайте асинхронные задачи. Все эндпоинты используют одну и ту же аутентификацию по API-ключу.
List your transcription jobs, newest first. Filter by status and paginate. Use the returned job_id with GET /api/v2/jobs/{job_id} to fetch a transcript.
/api/v2/jobspagequeryPage number (default 1).
limitqueryItems per page (default 50, max 100).
statusquerycompleted | processing | failed | requires_asr_confirmation.
List stored transcripts with search, status, language, and date filters. Metadata only (no full text) unless include_segments=true.
/api/v2/transcriptspagequeryPage number (default 1).
limitqueryItems per page (default 50, max 100).
searchqueryMatch video id, title, or transcript text.
statusqueryFilter by status; omit for succeeded.
languagequeryFilter by language code.
date_fromqueryISO date-time lower bound.
date_toqueryISO date-time upper bound.
include_segmentsqueryInclude segments in each item.
Fetch the best owned transcript for a video, including asr_intelligence (summary, topics, sentiment, etc.), plus summary and mind_map when generated.
/api/v2/transcripts/{video_id}video_idpathобязательныйYouTube 11-character video ID.
idquerySpecific transcript/job id.
languagequeryPreferred language version.
sourcequeryauto | manual | asr.
include_timestampsqueryInclude segments (default true).
Translate an owned transcript into a target language using YouTube captions or the AI provider. Returns free if you already own the translation.
/api/v2/transcripts/{video_id}/translatevideo_idpathобязательныйYouTube 11-character video ID.
target_languageISO 639-1обязательныйLanguage to translate into.
source_languageISO 639-1Source transcript language to translate from.
providerai | youtubeTranslation provider.
allow_ai_fallbackbooleanFall back to AI when YouTube has no translation.
List the languages you already own for a video plus the YouTube translation targets available for it.
/api/v2/transcripts/{video_id}/languagesvideo_idpathобязательныйYouTube 11-character video ID.
include_youtube_defaultqueryInclude YouTube translation targets (default true).
Delete owned transcript(s) for a video. Optional language/source query params narrow the deletion; otherwise every language/source is removed. Also deletes bulk by id via POST /api/v2/transcripts/bulk-delete.
/api/v2/transcripts/{video_id}video_idpathобязательныйYouTube 11-character video ID.
languagequeryOnly delete this language.
sourcequeryOnly delete this source (auto | manual | asr).
Получите ID видео из плейлиста, транскрибируйте их через /api/v2/batch, затем просматривайте пакет плейлиста и историю.
Resolve a YouTube playlist by URL or ID into its video list (metadata only). Pair the returned video_id values with /api/v2/batch to transcribe them.
/api/v2/playlists/resolveПлатные тарифыplaylist_urlstringPlaylist URL. One of playlist_url or playlist_id is required.
playlist_idstringPlaylist ID (the list= value).
limitintegerMax videos returned (1-100).
Fetch a playlist batch and per-video transcription job status. For overall batch progress, poll GET /api/v2/batch/{batch_id}.
/api/v2/playlists/{playlist_id}playlist_idpathобязательныйBatch ID returned from /playlists/resolve.
List recent playlist batches for the authenticated user.
/api/v2/playlists/historyПроцесс транскрибации канала:1. POST /api/v2/channels/resolve: получить загруженные видео канала (только метаданные).2. POST /api/v2/batch: отправить полученные значения video_id, чтобы начать транскрибацию. Укажите webhook_url, чтобы получить результаты по завершении.3. GET /api/v2/batch/{batch_id}: опрашивать пакет для отслеживания общего прогресса и сводных результатов.4. GET /api/v2/channels/{channel_id}: получить пакет канала со статусом задачи для каждого видео; /channels/history возвращает список прошлых пакетов каналов.
Fetch the uploads of a YouTube channel by URL, channel ID, or @handle. Returns video metadata only: pair the returned video_id values with /api/v2/batch to transcribe them.
/api/v2/channels/resolveПлатные тарифыchannel_urlstringобязательныйYouTube channel URL, channel ID, or @handle. One of channel_url, channel_id, or handle must be provided. Handles are the public ID without the @ (for https://www.youtube.com/@jawed, the ID is jawed).
limitintegerMaximum uploads returned. Defaults to the plan maximum.
Per-request cap: Basic 500 videos · Pro 1,500 videos · Business 3,000 videos. Monthly job cap: Basic 3 · Pro 8 · Business unlimited.
Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.
Fetch a channel batch and the per-video transcription job status. For overall batch status (counts + progress), poll GET /api/v2/batch/{batch_id} instead: use this endpoint when you also need each video's individual job state.
/api/v2/channels/{channel_id}channel_idpathобязательныйBatch ID returned from /channels/resolve.
List recent channel batches for the authenticated user.
/api/v2/channels/historylimitqueryMax items (default 50, max 100).
Официальные SDK, MCP-сервер для Claude и Cursor, собственный GPT и готовые шаблоны для Make и n8n.
Добавьте MCP-сервер YouTube Transcript в Claude Desktop, Cursor или любой MCP-совместимый клиент. Он добавляет инструменты для транскрибации видео, получения готовых транскриптов и проверки использования.
claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"Полноценные типы TypeScript, повторные попытки, хелперы для пагинации и проверка подписи вебхуков.
npm install youtube-transcript-apiСинхронный и асинхронный клиенты, type stubs и хелперы для пакетных сценариев и вебхуков.
pip install youtubetranscriptdevapiПодключите наш GPT в ChatGPT, чтобы кратко пересказывать, цитировать, переводить любое видео на YouTube или задавать по нему вопросы на естественном языке. Под капотом: /api/v2/gpt/*.
Импортируйте шаблон (или скопируйте сниппет), чтобы добавить транскрибацию в существующие автоматизации: Notion, Sheets, Slack, Airtable, сценарии в стиле Zapier.
Module: HTTP > Make a request
- URL: https://www.youtubetranscript.dev/api/v2/transcribe
- Method: POST
- Headers:
Authorization: Bearer {{connection.api_key}}
Content-Type: application/json
- Body type: Raw / JSON
- Request content:
{
"video": "{{1.video_url}}",
"format": { "timestamp": true }
}{
"name": "Transcribe Video",
"type": "n8n-nodes-base.httpRequest",
"parameters": {
"method": "POST",
"url": "https://www.youtubetranscript.dev/api/v2/transcribe",
"authentication": "genericCredentialType",
"genericAuthType": "httpHeaderAuth",
"sendBody": true,
"specifyBody": "json",
"jsonBody": "={ \"video\": $json.video_url }"
}
}Импортируйте спецификацию OpenAPI в Postman, Insomnia или любой инструмент с поддержкой OpenAPI 3.
Ошибки возвращают JSON-тело с полями code и message. HTTP-статус отражает категорию.
| Статус HTTP | Код ошибки | Описание |
|---|---|---|
| 400 | invalid_request | Invalid JSON or missing required fields |
| 401 | invalid_api_key | Missing or invalid API key |
| 402 | payment_required | Insufficient credits |
| 404 | no_captions | No captions available and ASR not used |
| 429 | rate_limit_exceeded | Too many requests, check Retry-After |
| 500 | internal_error | Server error, retry with backoff |
Ограничения для каждого тарифа на постоянную нагрузку и размер пакетов. При превышении лимита возвращается 429 с заголовком Retry-After.
| Тариф | Запросы | Размер пакета |
|---|---|---|
| Free | 1 req/s | 10 videos |
| Basic | 25 req/s | 500 videos |
| Pro | 50 req/s | 1,500 videos |
| Business | 100 req/s | 3,000 videos |
Нужна помощь с запуском? Напишите нам: обычно мы отвечаем в течение нескольких часов.