API-ключи

Транскрипты V2

V2: упрощённая модель транскриптов, принадлежащих пользователю. В приоритете быстрые попадания в кэш, единообразные ответы и никаких неожиданных переводов, если вы сами не запросили язык.

POSThttps://www.youtubetranscript.dev/api/v2/transcribe
POSThttps://www.youtubetranscript.dev/api/v2/batch
GEThttps://www.youtubetranscript.dev/api/v2/jobs/{job_id}
GEThttps://www.youtubetranscript.dev/api/v2/batch/{batch_id}
POSThttps://www.youtubetranscript.dev/api/v2/channels/resolve
GEThttps://www.youtubetranscript.dev/api/v2/channels/{channel_id}
GEThttps://www.youtubetranscript.dev/api/v2/channels/history

Спецификация OpenAPI

Скачайте YAML, чтобы импортировать его в Postman или Insomnia, сгенерировать клиенты или вставить в ChatGPT / Claude.

OpenAPI 3.0: V2 (рекомендуется)

Транскрибация одного видео

Самый быстрый способ обработать одно видео. Транскрипты по субтитрам возвращаются за несколько секунд; 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.

POST/api/v2/transcribe
Параметры
videostringобязательный

YouTube URL or 11-character video ID. Required unless upload_id is set.

upload_idstring

Transcribe 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-1

Preferred transcript language (e.g. en). If unavailable, captions in another language may be returned: transcript.language reports the actual language.

sourceauto | manual | asr

Preferred transcript source. Default: auto. Use asr for audio transcription (async, requires webhook_url).

allow_asrboolean

Fall back to ASR if captions fail. Required for ASR-only videos.

formatobject

{ timestamp, paragraphs, words }: include extra structure in the transcript.

webhook_urluri

When set, the response returns processing and the result is delivered to your URL. Required for ASR.

asr_optionsobject

Rich 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.

POST/api/v2/transcribe/estimate
Параметры
videostringобязательный

YouTube URL or 11-character video ID.

sourceauto | manual | asr

Defaults to asr for cost preview.

asr_optionsobject

Same 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.

GET/api/v2/jobs/{job_id}
Параметры
job_idpathобязательный

Identifier returned in the original transcribe response.

include_segmentsboolean

Include segment-level timestamps in the transcript payload.

include_paragraphsboolean

Include paragraph groupings.

include_wordsboolean

Include 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.

POST/api/v2/uploads
Параметры
filenamestringобязательный

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).

POST/api/v2/uploads/{upload_id}/complete
Параметры
upload_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.

POST/api/v2/batch
Параметры
video_idsstring[]обязательный

Up to 3,000 IDs depending on plan. Free = 10, Basic = 500, Pro = 1,500, Business = 3,000.

languageISO 639-1

Preferred language for every video.

sourceauto | manual | asr

Preferred transcript source. Default: auto. source=asr requires webhook_url.

allow_asrboolean

Fall back to ASR when captions fail. webhook_url is required.

formatobject

{ timestamp, paragraphs, words }: applied to every result.

webhook_urluri

Delivers the completed batch payload. Required when allow_asr=true or source=asr.

asr_optionsobject

Rich 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.

GET/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.

GET/api/v2/jobs
Параметры
pagequery

Page number (default 1).

limitquery

Items per page (default 50, max 100).

statusquery

completed | processing | failed | requires_asr_confirmation.

List stored transcripts with search, status, language, and date filters. Metadata only (no full text) unless include_segments=true.

GET/api/v2/transcripts
Параметры
pagequery

Page number (default 1).

limitquery

Items per page (default 50, max 100).

searchquery

Match video id, title, or transcript text.

statusquery

Filter by status; omit for succeeded.

languagequery

Filter by language code.

date_fromquery

ISO date-time lower bound.

date_toquery

ISO date-time upper bound.

include_segmentsquery

Include 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.

GET/api/v2/transcripts/{video_id}
Параметры
video_idpathобязательный

YouTube 11-character video ID.

idquery

Specific transcript/job id.

languagequery

Preferred language version.

sourcequery

auto | manual | asr.

include_timestampsquery

Include 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.

POST/api/v2/transcripts/{video_id}/translate
Параметры
video_idpathобязательный

YouTube 11-character video ID.

target_languageISO 639-1обязательный

Language to translate into.

source_languageISO 639-1

Source transcript language to translate from.

providerai | youtube

Translation provider.

allow_ai_fallbackboolean

Fall 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.

GET/api/v2/transcripts/{video_id}/languages
Параметры
video_idpathобязательный

YouTube 11-character video ID.

include_youtube_defaultquery

Include 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.

DELETE/api/v2/transcripts/{video_id}
Параметры
video_idpathобязательный

YouTube 11-character video ID.

languagequery

Only delete this language.

sourcequery

Only 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.

POST/api/v2/playlists/resolveПлатные тарифы
Параметры
playlist_urlstring

Playlist URL. One of playlist_url or playlist_id is required.

playlist_idstring

Playlist ID (the list= value).

limitinteger

Max 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}.

GET/api/v2/playlists/{playlist_id}
Параметры
playlist_idpathобязательный

Batch ID returned from /playlists/resolve.

List recent playlist batches for the authenticated user.

GET/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.

POST/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).

limitinteger

Maximum 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.

GET/api/v2/channels/{channel_id}
Параметры
channel_idpathобязательный

Batch ID returned from /channels/resolve.

List recent channel batches for the authenticated user.

GET/api/v2/channels/history
Параметры
limitquery

Max items (default 50, max 100).

Интеграции

Официальные SDK, MCP-сервер для Claude и Cursor, собственный GPT и готовые шаблоны для Make и n8n.

MCP serverClaude · Cursor
Репозиторий

Добавьте MCP-сервер YouTube Transcript в Claude Desktop, Cursor или любой MCP-совместимый клиент. Он добавляет инструменты для транскрибации видео, получения готовых транскриптов и проверки использования.

Установка и настройка
claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"
Node SDKnpm
npm

Полноценные типы TypeScript, повторные попытки, хелперы для пагинации и проверка подписи вебхуков.

Установка и использование
npm install youtube-transcript-api
Python SDKPyPI
PyPI

Синхронный и асинхронный клиенты, type stubs и хелперы для пакетных сценариев и вебхуков.

Установка и использование
pip install youtubetranscriptdevapi
Custom GPTChatGPT
Открыть в ChatGPT

Подключите наш GPT в ChatGPT, чтобы кратко пересказывать, цитировать, переводить любое видео на YouTube или задавать по нему вопросы на естественном языке. Под капотом: /api/v2/gpt/*.

  • · Вход через OAuth: без API-ключа в чате
  • · ASR как запасной вариант при отсутствии субтитров
  • · Цитаты с таймкодами и ссылками на источник
  • · Бесплатный пробный период для каждого аккаунта
Make.com & n8nБез кода
Смотреть шаблоны

Импортируйте шаблон (или скопируйте сниппет), чтобы добавить транскрибацию в существующие автоматизации: Notion, Sheets, Slack, Airtable, сценарии в стиле Zapier.

Модуль Make.com
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 }
    }
HTTP-нода n8n
{
  "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 }"
  }
}
Postman / OpenAPIВ один клик
Коллекция Postman

Импортируйте спецификацию OpenAPI в Postman, Insomnia или любой инструмент с поддержкой OpenAPI 3.

Ошибки

Ошибки возвращают JSON-тело с полями code и message. HTTP-статус отражает категорию.

Статус HTTPКод ошибкиОписание
400invalid_requestInvalid JSON or missing required fields
401invalid_api_keyMissing or invalid API key
402payment_requiredInsufficient credits
404no_captionsNo captions available and ASR not used
429rate_limit_exceededToo many requests, check Retry-After
500internal_errorServer error, retry with backoff

Лимиты и квоты

Ограничения для каждого тарифа на постоянную нагрузку и размер пакетов. При превышении лимита возвращается 429 с заголовком Retry-After.

ТарифЗапросыРазмер пакета
Free1 req/s10 videos
Basic25 req/s500 videos
Pro50 req/s1,500 videos
Business100 req/s3,000 videos

Поддержка

Нужна помощь с запуском? Напишите нам: обычно мы отвечаем в течение нескольких часов.

Документация API: YouTube Transcript API