Transcripts V2

V2 is the streamlined, user-owned transcript model. It prioritizes fast cache hits, consistent responses, and no surprise translations unless you request a language.

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 specification

Download the YAML to import into Postman, Insomnia, generate clients, or paste into ChatGPT / Claude.

OpenAPI 3.0 — V2 (recommended)

Transcribe a single video

The fastest path for one video at a time. Caption-based transcripts return within a few seconds; ASR runs asynchronously and is polled via /api/v2/jobs/{job_id}.

POST/api/v2/transcribe

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.

Parameters

videostring

Required

YouTube URL or 11-character video ID.

languageISO 639-1

Optional

Translate to this language. Omit to keep the source language.

sourceauto | manual | asr

Optional

Preferred transcript source. Default: auto.

allow_asrboolean

Optional

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

formatobject

Optional

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

webhook_urluri

Optional

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

GET/api/v2/jobs/{job_id}

Poll a single transcription job. Use this for ASR jobs returned from /transcribe. Returns 202 while running and 200 when complete.

Parameters

job_idpath

Required

Identifier returned in the original transcribe response.

include_segmentsboolean

Optional

Include segment-level timestamps in the transcript payload.

include_paragraphsboolean

Optional

Include paragraph groupings.

include_wordsboolean

Optional

Include word-level timestamps (ASR only).

Batch transcription

Transcribe many videos in a single request, then poll or receive results via webhook.

POST/api/v2/batch

Submit up to 3,000 videos in one request. Returns within 2 seconds; poll the returned poll_url or wait for the webhook.

Parameters

video_idsstring[]

Required

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

sourceauto | manual | asr

Optional

Preferred transcript source. Default: auto.

allow_asrboolean

Optional

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

formatobject

Optional

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

webhook_urluri

Optional

Delivers the completed batch payload. Required when allow_asr is true.

GET/api/v2/batch/{batch_id}

Check the status of a batch. Returns 202 while processing and 200 when results are ready.

Parameters

batch_idpath

Required

Batch identifier returned from POST /batch.

Channels

Channel transcription flow:1. POST /api/v2/channels/resolve — fetch the channel uploads (video metadata only).2. POST /api/v2/batch — send the returned video_id values to start transcription. Use a webhook_url to receive results when done.3. GET /api/v2/batch/{batch_id} — poll the batch for overall progress and aggregated results.4. GET /api/v2/channels/{channel_id} — fetch a channel batch with per-video job status; /channels/history lists past channel batches.

POST/api/v2/channels/resolvePaid plans

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.

Parameters

channel_urlstring

Required

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

Optional

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.

Rate limit

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.

GET/api/v2/channels/{channel_id}

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.

Parameters

channel_idpath

Required

Batch ID returned from /channels/resolve.

GET/api/v2/channels/history

List recent channel batches for the authenticated user.

Parameters

limitquery

Optional

Max items (default 50, max 100).

Integrations

Official SDKs, an MCP server for Claude and Cursor, a custom GPT, and ready-made templates for Make and n8n.

MCP serverClaude · Cursor

Repo

Add the YouTube Transcript MCP server to Claude Desktop, Cursor, or any MCP-compatible client. Adds tools to transcribe videos, fetch existing transcripts, and check usage.

Install & Configure

claude mcp add --transport http ytscribe https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"

Node SDKnpm

npm

First-class TypeScript types, retries, pagination helpers, and webhook signature verification.

Install & use

npm install youtube-transcript-api

Python SDKPyPI

PyPI

Sync + async clients, type stubs, and helpers for batch and webhook flows.

Install & use

pip install youtubetranscriptdevapi

Custom GPTChatGPT

Open in ChatGPT

Drop our custom GPT into ChatGPT to summarize, quote, translate, or query any YouTube video using natural language. Backed by /api/v2/gpt/* under the hood.

· OAuth sign-in — no API key in chat
· ASR fallback for missing captions
· Quote with timestamps and source links
· Free trial on every account

Make.com & n8nNo-code

Browse templates

Import the template (or copy the snippet) to add transcription to existing automations — Notion, Sheets, Slack, Airtable, Zapier-style flows.

Make.com module

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

n8n HTTP node

{
  "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 / OpenAPIOne-click

Postman collection

Import the OpenAPI spec into Postman, Insomnia, or any tool that speaks OpenAPI 3.

Download V2 YAML Download V1 YAML

Errors

Errors return a JSON body with code and message. HTTP status reflects the category.

HTTP Status	Error Code	Description
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

Rate limits & quotas

Per-plan caps for sustained requests and batch sizes. Bursting above the limit returns 429 with a Retry-After header.

Plan	Requests	Batch size
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

Support

Need help shipping? Reach out — we usually reply within a few hours.

Discord

@volods.taimi

support@youtubetranscript.dev

Status

Uptime & incidents

POST/api/v2/transcribe

curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "dQw4w9WgXcQ",
    "language": "en",
    "format": { "timestamp": true, "paragraphs": true }
  }'

Response (200)

{
  "request_id": "req_abc123",
  "status": "completed",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "video_title": "Example video",
    "transcript": {
      "text": "Welcome to this tutorial...",
      "language": "en",
      "source": "auto",
      "segments": [
        { "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }
      ]
    }
  },
  "credits_used": 1
}

GET/api/v2/jobs/{job_id}

curl -X GET https://www.youtubetranscript.dev/api/v2/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

{
  "request_id": "req_abc123",
  "status": "completed",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "transcript": {
      "text": "Welcome to this tutorial...",
      "language": "en",
      "source": "asr",
      "segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }]
    }
  },
  "credits_used": 6
}

POST/api/v2/batch

curl -X POST https://www.youtubetranscript.dev/api/v2/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
    "source": "auto",
    "allow_asr": true,
    "webhook_url": "https://your-domain.com/webhook",
    "format": { "timestamp": true }
  }'

Response (202)

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "results": [],
  "summary": { "total": 2, "succeeded": 0, "failed": 0, "processing": 2 },
  "poll_url": "https://www.youtubetranscript.dev/api/v2/batch/550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-05-15T10:00:00Z"
}

GET/api/v2/batch/{batch_id}

curl -X GET https://www.youtubetranscript.dev/api/v2/batch/BATCH_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "summary": { "total": 2, "succeeded": 2, "failed": 0, "processing": 0 },
  "results": [
    { "request_id": "req_1", "status": "completed", "data": { "video_id": "dQw4w9WgXcQ" } },
    { "request_id": "req_2", "status": "completed", "data": { "video_id": "jNQXAC9IVRw" } }
  ],
  "credits_used": 2,
  "webhook_delivered": true,
  "completed_at": "2026-05-15T10:04:00Z"
}

POST/api/v2/channels/resolve

curl -X POST https://www.youtubetranscript.dev/api/v2/channels/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "@youtube",
    "limit": 50
  }'

Response (200)

{
  "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
  "channel_title": "YouTube",
  "subscriber_count": 42000000,
  "video_count": 1200,
  "total": 1,
  "truncated": false,
  "items": [
    {
      "video_id": "dQw4w9WgXcQ",
      "title": "Latest upload",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "published_at": "2026-05-01T12:00:00Z",
      "duration_seconds": 420
    }
  ]
}

GET/api/v2/channels/{channel_id}

curl -X GET https://www.youtubetranscript.dev/api/v2/channels/CHANNEL_BATCH_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

{
  "channel": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "channel_title": "YouTube",
    "total_videos": 2,
    "completed_count": 1,
    "failed_count": 0,
    "status": "processing",
    "created_at": "2026-05-15T10:00:00Z"
  },
  "videos": [
    {
      "id": "job_123",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "Latest upload",
      "status": "succeeded",
      "created_at": "2026-05-15T10:00:00Z",
      "finished_at": "2026-05-15T10:00:10Z"
    }
  ]
}

GET/api/v2/channels/history

curl -X GET "https://www.youtubetranscript.dev/api/v2/channels/history?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

{
  "history": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
      "channel_title": "YouTube",
      "total_videos": 25,
      "completed_count": 25,
      "failed_count": 0,
      "status": "completed",
      "created_at": "2026-05-15T10:00:00Z",
      "completed_at": "2026-05-15T10:12:00Z"
    }
  ],
  "count": 1
}

Transcripts V2

相关资源