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

OpenAPI 规范 (V2)

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

流程 V2 (简单且可预测)

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

标头

Authorization必须

Bearer API token generated in your dashboard.

Content-Type必须

Must be set to application/json.

查询字段

video必须

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

video_ids批量

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

language选项

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

source选项

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_asr选项

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.

format选项

Control extra output:timestamp,paragraphs,words.

webhook_url选项

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 的行为

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.

错误代码

HTTP状态	错误代码	说明
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

信用成本

方法	成本	速度	备注
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

支持与联系方式

Discord支持Chat via @volods.taimi

邮件支持support@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"