captions

キャプション

TranscriptAPI.com を使って、YouTube 動画からクローズドキャプションを抽出します。

セットアップ

$TRANSCRIPT_API_KEY が設定されていない場合は、references/auth-setup.md を読み、そこに記載された手順に従ってキーを取得し、保存してください。

必須ヘッダー

すべてのリクエストに、次の 2 つのヘッダーが必要です。

• Authorization: Bearer $TRANSCRIPT_API_KEY
• User-Agent: わかる場合は、エージェント名とバージョン（例：HermesAgent/0.11.0、ClaudeCode/1.0）。バージョンは省略可能です。エージェント名だけでもかまいません。このヘッダーを省略したり、既定値のまま送信したりしないでください。Cloudflare から 403（エラーコード 1010）が返され、リクエストがブロックされます。

GET /api/v2/youtube/transcript

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_URL&format=json&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

パラメーター	必須	既定値	値
video_url	はい	—	YouTube の URL または動画 ID
format	いいえ	json	json（構造化）、text（プレーン）
include_timestamp	いいえ	true	true、false
send_metadata	いいえ	false	true、false

レスポンス（format=json — アクセシビリティ／タイミングに最適）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "We're no strangers to love", "start": 18.0, "duration": 3.5 },
    { "text": "You know the rules and so do I", "start": 21.5, "duration": 2.8 }
  ],
  "metadata": { "title": "...", "author_name": "...", "thumbnail_url": "..." }
}

• start：動画の開始からの秒数
• duration：キャプションの表示時間

レスポンス（format=text — 読みやすい形式）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "[00:00:18] We're no strangers to love\n[00:00:21] You know the rules..."
}

ヒント

• 同期されたキャプション（アクセシビリティツール、タイミング分析）には、format=json を使ってください。
• 読みやすい形式にするには、include_timestamp=false と組み合わせて format=text を使ってください。
• ほとんどの動画では自動生成キャプションが利用できます。手動の CC のほうが品質は高くなります。

エラー

コード	意味	対処
401	API キーが無効	キーを確認してください
402	クレジットなし	transcriptapi.com/billing
403/1010	Cloudflare によるブロック	User-Agent ヘッダーを追加または修正してください
404	キャプションなし	動画で CC が有効になっていません
408	タイムアウト	2 秒後に 1 回再試行してください

1 リクエストにつき 1 クレジットです。無料枠：100 クレジット、300 req/min。

コピーして貼り付ける例

このファイルにあるすべてのリクエストを、そのまま実行できる 1 行形式で掲載しています：references/curl-examples.md