Transcribe a single YouTube video. Returns immediately for caption-based videos. With mode=auto it falls back to ASR (async) when captions are unavailable: you get status processing and a job_id to poll at /api/v2/jobs/{job_id}, or the result is POSTed to webhook_url if you set one. Responses include the mode the request ran with.

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 (mode must be omitted or speech_to_text_only); webhook_url required. The upload id is returned as video_id in results.

modeauto | captions_only | human_captions_only | speech_to_text_only

Where the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). When omitted, your account default from the API Dashboard applies: auto for accounts created from October 2026, captions_only for older accounts unless changed. ASR modes work without webhook_url: poll the returned job_id.

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

Legacy, still supported: use mode instead. Default: auto. asr transcribes the audio (async, requires webhook_url).

allow_asrboolean

Legacy, still supported: use mode=auto instead. Falls back to ASR if captions fail.

formatobject

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

webhook_urluri

When set, ASR results are POSTed to your URL. Optional with mode (poll the job_id instead); required for legacy source=asr. Ignored by captions_only and human_captions_only, which never use 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.

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

レスポンス (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,
  "mode": "auto"
}

コストを見積もる

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.

modeauto | captions_only | human_captions_only | speech_to_text_only

Same values as /transcribe. Use speech_to_text_only (or auto) to preview the ASR cost.

sourceauto | manual | asr

Legacy, still supported: use mode instead. Defaults to asr for cost preview.

asr_optionsobject

Same shape as /transcribe. Add-on charges are prorated by duration.

curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "dQw4w9WgXcQ",
    "mode": "speech_to_text_only",
    "asr_options": {
      "speakerLabels": true,
      "summarization": true,
      "translateTo": "es"
    }
  }'

レスポンス (200)

{
  "request_id": "req_abc123",
  "video_id": "dQw4w9WgXcQ",
  "source": "asr",
  "mode": "speech_to_text_only",
  "duration_seconds": 213,
  "duration_minutes": 4,
  "max_duration_minutes": 480,
  "exceeds_max_duration": false,
  "base_credits": 3,
  "addon_credits": 2,
  "estimated_credits": 5
}

ジョブの状態を確認

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

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

レスポンス (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
}

独自メディアのアップロード

手持ちの音声・動画ファイルを ASR パイプラインで文字起こしします。手順は 3 つ：アップロードを登録し、署名付き URL にバイトを PUT し、確定します。その後 upload_id を指定して /transcribe を呼び出します。結果は Webhook で届き、通常の 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.

curl -X POST https://www.youtubetranscript.dev/api/v2/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "interview.mp3",
    "mime_type": "audio/mpeg",
    "size_bytes": 48211234,
    "duration_sec": 1820
  }'

# Then PUT the raw file bytes to the returned signed_url:
curl -X PUT "SIGNED_URL_FROM_RESPONSE" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @interview.mp3

# Then finalize:
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/UPLOAD_ID/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "upload_id": "up_a1B2c3D4",
  "bucket": "asr-media",
  "path": "user-uuid/up_a1B2c3D4/interview.mp3",
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "signed_url": "https://api.youtubetranscript.dev/storage/v1/object/upload/sign/asr-media/...?token=..."
}

アップロードを完了

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.

curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/up_a1B2c3D4/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "upload_id": "up_a1B2c3D4",
  "status": "uploaded",
  "filename": "interview.mp3",
  "duration_sec": 1820
}

バッチ文字起こし

1 回のリクエストで複数の動画を文字起こしし、ポーリングまたは Webhook で結果を受け取ります。

複数の動画を文字起こし

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.

modeauto | captions_only | human_captions_only | speech_to_text_only

Where the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). For batch, auto and speech_to_text_only require webhook_url. When omitted, your API Dashboard default applies (an ASR default only when webhook_url is set).

sourceauto | manual | asr

Legacy, still supported: use mode instead. Default: auto. source=asr requires webhook_url.

allow_asrboolean

Legacy, still supported: use mode=auto instead. webhook_url is required.

formatobject

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

webhook_urluri

Delivers the completed batch payload. Required for mode=auto or speech_to_text_only (legacy: 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.

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"],
    "mode": "auto",
    "webhook_url": "https://your-domain.com/webhook",
    "format": { "timestamp": true }
  }'

レスポンス (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"
}

バッチの状態を確認

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.

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

レスポンス (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"
}

文字起こしとジョブ

保存済みの文字起こしの一覧取得・取得・翻訳・削除、および非同期ジョブの一覧取得を行います。すべてのエンドポイントで同じ 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.

curl "https://www.youtubetranscript.dev/api/v2/jobs?status=processing&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "jobs": [
    {
      "job_id": "9c2...",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "Example video",
      "language": "en",
      "source": "asr",
      "status": "processing",
      "error": null,
      "credits_used": 0,
      "created_at": "2026-07-06T12:00:00Z",
      "started_at": "2026-07-06T12:00:01Z",
      "completed_at": null
    }
  ],
  "count": 1,
  "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasMore": false }
}

文字起こし一覧

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.

curl "https://www.youtubetranscript.dev/api/v2/transcripts?page=1&limit=50&status=succeeded" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "history": [
    {
      "id": "b1f...",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "Example video",
      "language": "en",
      "source_kind": "auto",
      "status": "succeeded",
      "created_at": "2026-07-06T12:00:00Z",
      "word_count": 1234,
      "segment_count": 88,
      "credits_used": 1
    }
  ],
  "count": 1,
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1, "hasMore": false }
}

文字起こしを取得

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

curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ?language=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "id": "b1f...",
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "text": "Welcome to this tutorial...",
  "segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }],
  "has_timestamps": true,
  "source_kind": "asr",
  "video_title": "Example video",
  "summary": null,
  "mind_map": null,
  "asr_intelligence": {
    "summary": "A short overview of the video...",
    "topics": [{ "text": "Technology", "relevance": 0.92 }],
    "sentiment": [{ "text": "Great tutorial", "sentiment": "POSITIVE" }]
  }
}

テーマとキーワードを取得

AI key moments, themes & keywords for a stored transcript: a short TL;DR, the key moments worth finding again (each a short label plus the exact quote, with where it starts and ends), its main themes, and each keyword with the timestamps where it's said. 1 credit per transcript, charged once: calling it again (or GET) is free. Waits up to ~25s; a 202 "processing" means it's paid for and still running, so poll GET. If detection fails the credit is refunded. Transcripts too short to analyse return empty themes for 0 credits. 402 without enough credits.

POST/api/v2/transcripts/{video_id}/themes

パラメーター

video_idpath必須

YouTube 11-character video ID of a transcript you own.

idquery

Specific transcript/job id.

languagequery

Which language version to analyse.

sourcequery

auto | manual | asr.

curl -X POST "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/themes?language=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "status": "completed",
  "credits_used": 1,
  "credits_remaining": 41,
  "tldr": "A promise of lifelong loyalty, sung as a list of things he'll never do.",
  "moments": [
    {
      "id": "m1",
      "theme_id": "t1",
      "label": "The six promises of the chorus",
      "quote": "Never gonna give you up, never gonna let you down",
      "color_hex": "#0d9488",
      "start": 43000,
      "end": 47500,
      "segment_start": 4,
      "segment_end": 5
    }
  ],
  "themes": [
    {
      "id": "t1",
      "name": "Commitment",
      "summary": "Promises never to leave or let the listener down.",
      "color": "teal",
      "color_hex": "#0d9488",
      "share": 0.62,
      "mention_count": 18,
      "moment_count": 3,
      "keywords": [
        {
          "id": "k1",
          "term": "never gonna give you up",
          "aliases": [],
          "definition": "The song's central promise.",
          "mention_count": 6,
          "mentions": [{ "segment_index": 4, "start": 43000 }]
        }
      ]
    }
  ]
}

解除済みのテーマを読む

Read key moments, themes & keywords you've already unlocked. Never charges and never starts the AI: returns status "locked" (with credits_required) until you POST, then "completed" with the same body as POST, or 202 "processing" while detection is still running.

GET/api/v2/transcripts/{video_id}/themes

パラメーター

video_idpath必須

YouTube 11-character video ID of a transcript you own.

idquery

Specific transcript/job id.

languagequery

Which language version to analyse.

sourcequery

auto | manual | asr.

curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/themes?language=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200, not unlocked yet)

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "status": "locked",
  "credits_required": 1
}

文字起こしを翻訳

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.

curl -X POST "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/translate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_language": "es", "provider": "ai" }'

レスポンス (200)

{
  "success": true,
  "message": "Translation completed",
  "language": "es",
  "credits_used": 4,
  "provider_used": "ai"
}

利用可能な言語

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

curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/languages" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "video_id": "dQw4w9WgXcQ",
  "languages": ["en", "es"],
  "youtube_translation_languages": ["fr", "de", "ja"]
}

文字起こしを削除

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

curl -X DELETE "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "success": true,
  "deleted": 2,
  "message": "Successfully deleted 2 transcripts"
}

プレイリスト

プレイリストを動画 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).

curl -X POST https://www.youtubetranscript.dev/api/v2/playlists/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "playlist_url": "https://www.youtube.com/playlist?list=PLxxxx", "limit": 100 }'

レスポンス (200)

{
  "playlist_id": "PLxxxx",
  "title": "My playlist",
  "total": 42,
  "truncated": false,
  "items": [
    { "video_id": "dQw4w9WgXcQ", "title": "Example video" }
  ]
}

プレイリストのジョブ状態

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.

curl "https://www.youtubetranscript.dev/api/v2/playlists/{playlist_batch_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "playlist": { "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist" },
  "videos": [
    { "video_id": "dQw4w9WgXcQ", "video_title": "Example video", "status": "succeeded" }
  ]
}

最近のプレイリストジョブ

List recent playlist batches for the authenticated user.

GET/api/v2/playlists/history

curl "https://www.youtubetranscript.dev/api/v2/playlists/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "history": [
    { "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist", "total_videos": 42 }
  ],
  "count": 1
}

チャンネル

チャンネル文字起こしの流れ：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.

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

レスポンス (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
    }
  ]
}

チャンネルのジョブ状態

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.

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

レスポンス (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"
    }
  ]
}

最近のチャンネルジョブ

List recent channel batches for the authenticated user.

GET/api/v2/channels/history

パラメーター

limitquery

Max items (default 50, max 100).

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

レスポンス (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
}

api-docs.docs.nav.endpoints.recommendations-videos

Newest uploads from the channels you transcribe most, excluding videos you have already transcribed. Results are interleaved across channels, newest first. Free: no credits are charged. Pass the returned url or video_id to /api/v2/transcribe or /api/v2/batch.

GET/api/v2/recommendations/videos

パラメーター

limitquery

Max videos returned (default 6, max 30).

channelsquery

How many of your top channels to draw from (default 3, max 10).

curl -X GET "https://www.youtubetranscript.dev/api/v2/recommendations/videos?limit=6" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "recommendations": [
    {
      "video_id": "dQw4w9WgXcQ",
      "title": "Latest upload",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
      "published_at": "2026-10-17T15:00:00Z",
      "duration_seconds": 1089,
      "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
      "channel_title": "YouTube"
    }
  ],
  "channels": [
    {
      "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
      "channel_title": "YouTube",
      "transcribed_count": 12
    }
  ],
  "count": 1
}

検索

検索してから文字起こし：1. GET /api/v2/search/videos (/shorts, /channels, /playlists)：キーワードでコンテンツを検索します。1リクエストにつき1クレジット。2. 動画の url を POST /api/v2/transcribe に、チャンネルまたは再生リストの url を /api/v2/channels/resolve または /api/v2/playlists/resolve に送信します。3. next_page_token を page_token として渡すと、さらに結果を取得できます（1ページにつき1クレジット）。

動画を検索

Search YouTube videos by keyword. Live streams are included with type "live". Pass a result's url to /api/v2/transcribe to get its transcript. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/videos

パラメーター

qquery必須

Search text, up to 200 characters.

durationquery

Video length: under_3_min, 3_to_20_min or over_20_min.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

レート制限

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.

curl "https://www.youtubetranscript.dev/api/v2/search/videos?q=python%20tutorial&duration=over_20_min" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "request_id": "6f1c2a9e-4b7d-4f2a-9c1e-2d3b4a5c6d7e",
  "type": "videos",
  "query": "python tutorial",
  "results": [
    {
      "type": "video",
      "video_id": "kqtD5dpn9C8",
      "url": "https://www.youtube.com/watch?v=kqtD5dpn9C8",
      "title": "Python for Beginners - Learn Coding with Python in 1 Hour",
      "thumbnail": "https://i.ytimg.com/vi/kqtD5dpn9C8/hq720.jpg",
      "channel": {
        "channel_id": "UCWv7vMbMWH4-V0ZXdmDpPBA",
        "title": "Programming with Mosh",
        "handle": "programmingwithmosh",
        "url": "https://www.youtube.com/@programmingwithmosh",
        "thumbnail": "https://yt3.ggpht.com/..."
      },
      "view_count": 25574982,
      "view_count_text": "25,574,982 views",
      "published_at": null,
      "published_text": "6 years ago",
      "duration_seconds": 3606,
      "duration_text": "1:00:06",
      "badges": []
    }
  ],
  "next_page_token": "cDA6RWdJUUFV...",
  "credits_used": 1,
  "credits_remaining": 4602
}

ショートを検索

Search YouTube Shorts by keyword. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/shorts

パラメーター

qquery必須

Search text, up to 200 characters.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

レート制限

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.

curl "https://www.youtubetranscript.dev/api/v2/search/shorts?q=python%20tips" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "request_id": "0b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "type": "shorts",
  "query": "python tips",
  "results": [
    {
      "type": "short",
      "video_id": "gbYLsUngzLc",
      "url": "https://www.youtube.com/watch?v=gbYLsUngzLc",
      "title": "Top 10 Most Important Python Functions You Must Know!",
      "thumbnail": "https://i.ytimg.com/vi/gbYLsUngzLc/oar2.jpg",
      "channel": null,
      "view_count": 1200000,
      "view_count_text": "1.2M views",
      "published_at": null,
      "published_text": null,
      "duration_seconds": null,
      "duration_text": null,
      "badges": []
    }
  ],
  "next_page_token": "cDA6RWdJUUNR...",
  "credits_used": 1,
  "credits_remaining": 4601
}

チャンネルを検索

Search YouTube channels by keyword. Pass a result's url to /api/v2/channels/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/channels

パラメーター

qquery必須

Search text, up to 200 characters.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

レート制限

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.

curl "https://www.youtubetranscript.dev/api/v2/search/channels?q=python" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "request_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "type": "channels",
  "query": "python",
  "results": [
    {
      "type": "channel",
      "channel_id": "UCKQdc0-Targ4nDIAUrlfKiA",
      "url": "https://www.youtube.com/@PythonSimplified",
      "title": "Python Simplified",
      "handle": "PythonSimplified",
      "description": "Hi everyone! My name is Mariya and I'm a software developer...",
      "thumbnail": "https://yt3.googleusercontent.com/...",
      "subscriber_count": 286000,
      "subscriber_count_text": "286K",
      "badges": ["Verified"]
    }
  ],
  "next_page_token": "cDA6RWdJUUFn...",
  "credits_used": 1,
  "credits_remaining": 4600
}

再生リストを検索

Search YouTube playlists by keyword. Pass a result's url to /api/v2/playlists/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/playlists

パラメーター

qquery必須

Search text, up to 200 characters.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

レート制限

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.

curl "https://www.youtubetranscript.dev/api/v2/search/playlists?q=python%20course" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス (200)

{
  "request_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "playlists",
  "query": "python course",
  "results": [
    {
      "type": "playlist",
      "playlist_id": "PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
      "url": "https://www.youtube.com/playlist?list=PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
      "title": "Python Tutorial | Complete Python Course (Beginner to Advanced)",
      "thumbnail": "https://i.ytimg.com/vi/YZkyL-f-YXY/hq720.jpg",
      "video_count": 54,
      "first_video_id": "YZkyL-f-YXY",
      "channel": {
        "channel_id": "UC59K-uG2A5ogwIrHw4bmlEg",
        "title": "Telusko",
        "handle": "Telusko",
        "url": "https://www.youtube.com/@Telusko",
        "thumbnail": null
      }
    }
  ],
  "next_page_token": "cDA6RWdJUUF3...",
  "credits_used": 1,
  "credits_remaining": 4599
}

連携

公式 SDK、Claude と Cursor 向けの MCP サーバー、カスタム GPT、そして Make と n8n 向けのすぐに使えるテンプレートを用意しています。

MCP serverClaude · Cursor

リポジトリ

YouTube Transcript MCP サーバーを 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 型、リトライ、ページネーションヘルパー、Webhook 署名検証。

インストールと使用

npm install youtube-transcript-api

Python SDKPyPI

PyPI

同期・非同期クライアント、型スタブ、バッチと Webhook フロー用のヘルパー。

インストールと使用

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

n8n HTTP ノード

{
  "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 対応の任意のツールにインポートします。

V2 YAML をダウンロード V2 JSON をダウンロード

エラー

エラー時は code と message を含む JSON ボディが返されます。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

レート制限とクォータ

プランごとの継続リクエスト数とバッチサイズの上限です。上限を超えるバーストには Retry-After ヘッダー付きの 429 が返されます。

プラン	リクエスト数	バッチサイズ
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@youtubetranscript.dev

Status

稼働状況とインシデント

できること

動画を文字起こし

コストを見積もる

ジョブの状態を確認

ファイルをアップロード

アップロードを完了

複数の動画を文字起こし

バッチの状態を確認

ジョブ一覧

文字起こし一覧

文字起こしを取得

テーマとキーワードを取得

解除済みのテーマを読む

文字起こしを翻訳

利用可能な言語

文字起こしを削除

プレイリストの動画一覧

プレイリストのジョブ状態

最近のプレイリストジョブ

チャンネルの動画一覧

チャンネルのジョブ状態

最近のチャンネルジョブ

api-docs.docs.nav.endpoints.recommendations-videos

動画を検索

ショートを検索

チャンネルを検索

再生リストを検索

関連リソース