Transcripts V2

NEW

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}

OpenAPI Specification (V2)

V2 OpenAPI 3.0 specification for tooling, SDK generation, and testing.

V2 Flow (Simple & Predictable)

1. Check your owned transcripts (0 credits).

2. If not owned, fetch captions (1 credit).

3. If you requested a language and captions are different, return ASR confirmation (or fall back to ASR if allowed).

4. If captions fail and allow_asr=true, process with ASR (async).

5. If source="asr", always process with ASR (async).

Headers

Authorizationrequired

Bearer API token generated in your dashboard.

Content-Typerequired

Must be set to application/json.

Request Fields

videorequired

YouTube URL or 11-character video ID (single video endpoint).

video_idsbatch

Array of IDs or URLs (batch endpoint). Limit: up to 100 videos per request.

languageoptional

ISO 639-1 language code (e.g., "es", "fr"). If omitted, V2 returns the best available captions without translation.

sourceoptional

auto (default), manual, or asr.
auto uses captions (manual + auto). If allow_asr=true, it will fall back to ASR when captions fail.manual requires manual captions only.asr forces audio transcription (async).

allow_asroptional

When true and source="auto", V2 will automatically fall back to ASR if captions fail (no captions, language mismatch, or transient fetch errors).Required with webhook_url for batch requests.

formatoptional

Control extra output:timestamp,paragraphs,words.

webhook_urloptional

When provided, V2 responds with status: "processing" and delivers results to your webhook once finished.Required for source="asr" and batch requests with allow_asr=true.

Webhook Behavior

1. Requests with webhook_url return immediately with status: "processing".

2. Batch requests return cached results immediately and queue only the missing items.

3. Your webhook receives the final results when processing completes.

Error Codes

HTTP Status	Error Code	Description
400	`invalid_request`	Invalid JSON or missing required fields
400	`invalid_parameter`	Invalid video ID or parameter value
401	`invalid_api_key`	Missing or invalid API key
402	`payment_required`	Insufficient credits for requested operation
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

Credit Costs

Method	Cost	Speed	Notes
Native Captions	1 credit	5-10 seconds	Best quality, exact language
Translation	1 credit per 2,500 chars	5-10 seconds	Only when language is requested
ASR (Audio)	1 credit per 90 seconds	2-20 minutes	Async via webhook

Support & Contact

Discord SupportChat via @volods.taimi

Email Supportsupport@youtubetranscript.dev

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": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "video_title": "Example Title",
    "transcript": {
      "text": "Welcome to this tutorial...",
      "language": "en",
      "source": "manual",
      "segments": [
        { "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }
      ]
    }
  },
  "credits_used": 1
}

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": "7b9b86a4-7b14-4b5a-8b1b-8b7de7b52003",
  "status": "processing",
  "results": [
    {
      "request_id": "req-1",
      "status": "completed",
      "data": {
        "video_id": "dQw4w9WgXcQ",
        "transcript": {
          "text": "Welcome to this tutorial...",
          "language": "en",
          "source": "manual"
        },
        "video_title": "Example Title"
      },
      "credits_used": 0
    },
    {
      "request_id": "req-2",
      "status": "processing",
      "data": {
        "video_id": "jNQXAC9IVRw",
        "transcript": {
          "text": "",
          "language": "en",
          "source": "asr"
        }
      },
      "credits_used": 0,
      "job_id": "job_123"
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 0,
    "processing": 1
  },
  "credits_used": 1,
  "poll_url": "https://www.youtubetranscript.dev/api/v2/batch/7b9b86a4-7b14-4b5a-8b1b-8b7de7b52003"
}

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 (202 Processing)

{
  "job_id": "2c7c2d18-3a8f-4f3d-9d1b-7a1c3f5d2c90",
  "status": "processing",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "transcript": {
      "text": "",
      "language": "en",
      "source": "asr"
    },
    "video_title": "Example Title"
  },
  "created_at": "2026-02-03T23:40:00Z",
  "started_at": "2026-02-03T23:40:12Z"
}

Response (200 Completed)

{
  "job_id": "2c7c2d18-3a8f-4f3d-9d1b-7a1c3f5d2c90",
  "status": "completed",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "transcript": {
      "text": "Welcome to this tutorial...",
      "language": "en",
      "source": "manual",
      "segments": [
        { "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }
      ]
    },
    "video_title": "Example Title"
  },
  "created_at": "2026-02-03T23:40:00Z",
  "started_at": "2026-02-03T23:40:12Z",
  "completed_at": "2026-02-03T23:40:20Z"
}

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 (202 Processing)

{
  "batch_id": "7b9b86a4-7b14-4b5a-8b1b-8b7de7b52003",
  "status": "processing",
  "results": [
    { "video_id": "dQw4w9WgXcQ", "status": "completed" },
    { "video_id": "jNQXAC9IVRw", "status": "processing" }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 0,
    "processing": 1
  },
  "credits_used": 1,
  "poll_url": "https://www.youtubetranscript.dev/api/v2/batch/7b9b86a4-7b14-4b5a-8b1b-8b7de7b52003",
  "webhook_delivered": false,
  "webhook_failed": false,
  "webhook_attempts": 0,
  "created_at": "2026-02-03T23:41:00Z",
  "started_at": "2026-02-03T23:41:05Z",
  "completed_at": null
}

Response (200 Completed)

{
  "batch_id": "7b9b86a4-7b14-4b5a-8b1b-8b7de7b52003",
  "status": "completed",
  "results": [
    { "video_id": "dQw4w9WgXcQ", "status": "completed" },
    { "video_id": "jNQXAC9IVRw", "status": "completed" }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0,
    "processing": 0
  },
  "credits_used": 2,
  "poll_url": "https://www.youtubetranscript.dev/api/v2/batch/7b9b86a4-7b14-4b5a-8b1b-8b7de7b52003",
  "webhook_delivered": true,
  "webhook_failed": false,
  "webhook_attempts": 1,
  "created_at": "2026-02-03T23:41:00Z",
  "started_at": "2026-02-03T23:41:05Z",
  "completed_at": "2026-02-03T23:41:30Z"
}

RELATED RESOURCES

API Pricing & Rate LimitsView rate limits and pricing for all API plans How to Extract TranscriptsStep-by-step guide to extracting YouTube transcripts Bulk Transcript ProcessingProcess playlists and channels via the API