subtitles

字幕

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=text&include_timestamp=false&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

パラメーター	値	用途
video_url	YouTube URL または動画 ID	必須
format	json、text	タイミング付きの同期字幕には json を指定します
include_timestamp	true、false	読み取りや翻訳用の整形済みテキストには false を指定します
send_metadata	true、false	タイトル、チャンネル、説明を含めます

語学学習向け — タイムスタンプなしの整形済みテキスト：

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=false
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

翻訳向け — 構造化されたセグメント：

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

レスポンス（format=json）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "We're no strangers to love", "start": 18.0, "duration": 3.5 }
  ]
}

レスポンス（format=text、include_timestamp=false）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "We're no strangers to love\nYou know the rules and so do I..."
}

ヒント

• 多くの動画には、複数の言語で自動生成された字幕があります。
• 各行のタイミングを取得するには format=json を使用してください（同期しながら読むのに便利です）。
• 翻訳アプリに適した整形済みテキストを取得するには include_timestamp=false を使用してください。

エラー

コード	意味	対処法
401	API キーが無効です	キーを確認してください
402	クレジットがありません	transcriptapi.com/billing
403/1010	Cloudflare によるブロック	User-Agent ヘッダーを追加または修正してください
404	字幕がありません	字幕を利用できません
408	タイムアウト	2 秒後に一度再試行してください

リクエスト 1 件につき 1 クレジットです。無料プラン：100 クレジット、300 リクエスト/分。

コピーして貼り付けられる例

このファイルの各リクエストを、そのまま実行できる 1 行のコマンドとして掲載しています：references/curl-examples.md