YouTube 字幕 API

認証付き GET リクエストひとつで、公開動画の既存字幕を全文、言語、タイムスタンプ付き JSON セグメントとしてアプリケーションに取得できます。

単一 REST エンドポイント
構造化 JSON 出力
時刻付き字幕セグメント
希望言語を指定
冪等な安全リトライ
字幕可用性を明示

リクエスト例

curl "https://api.agentbody.io/v1/youtube/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&language=en" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>"

レスポンス例

OpenAPI 仕様に記載されたレスポンス。

Existing captions or explicitly requested audio transcription.

{
  "caption_type": "manual",
  "language": "example_value",
  "segments": [],
  "text": "example_value",
  "video_id": "example_value"
}

機能特徴

YouTube 字幕 API で公開動画の既存字幕を構造化 JSON として取得し、調査パイプライン、動画内検索、RAG、コンテンツ分析プロダクトに組み込めます。

単一 REST エンドポイント

Bearer API key と公開動画 URL を指定して GET /v1/youtube/transcript を呼び出します。YouTube 字幕 API は文書化された HTTP リクエストで既存の字幕トラックを返すため、ブラウザ自動化フローや追加のクライアント SDK を維持せずに字幕取得機能をアプリケーションに追加できます。

構造化 JSON 出力

レスポンスには caption_type、language、video_id、完全な字幕テキスト、タイムスタンプ付き segments が含まれます。この JSON 構造は、字幕の保存、テキストのインデックス化、動画内検索、調査やコンテンツ分析パイプラインへの字幕データ投入に適しています。

時刻付き字幕セグメント

各字幕セグメントにはテキスト、開始時刻、終了時刻が含まれます。タイムスタンプを使うことで、検索結果、引用、メモ、生成した参照を公開動画内の該当箇所へ正確に関連付けられ、字幕を位置情報のない長文テキストとして扱わずに済みます。

希望言語を指定

省略可能な language パラメータを渡すと、en や zh など希望する公開字幕言語をリクエストできます。API が読み取るのはその動画で利用可能な字幕トラックだけで、翻訳を行ったり、動画が公開していない言語トラックを作成したりすることはありません。

冪等な安全リトライ

アプリケーションでリトライ保護が必要な場合は冪等キーを送信します。同じキーでの繰り返しリクエストは保存済みレスポンスを再生し、新しい課金実行を作成しないため、バックグラウンドジョブや Webhook はネットワーク結果が不確かな場合でも重複処理を避けて復旧できます。

字幕可用性を明示

公開動画に利用可能な字幕トラックがない場合、YouTube 字幕取得 API はテキストを作り出さずに 422 を返します。変更していない URL に対する最終的な可用性シグナルとして扱い、別のリソースを選ぶか、承認済みの別課金文字起こしフローを使用してください。

使い方

次の 6 ステップで YouTube 字幕 API を呼び出し、公開字幕の言語を選択して、タイムスタンプ付きセグメントを含む JSON を自分のアプリケーションで処理できます。

API キーを作成

AgentBody アカウントを作成し、コンソールで API key を発行します。キーはサーバー環境変数または承認済みのシークレットストアに保存し、リクエストでは Bearer token として使います。有効なキーをブラウザコード、公開リポジトリ、クライアント側のビルド成果物に入れないでください。

公開動画を選択

既存字幕を読み取りたい対象の公開 YouTube 動画を選び、完全な URL をコピーしてアクセス可能か確認します。非公開、利用不可、字幕なしの動画からは転記テキストを返せません。こうした字幕トラック未提供のケースを扱う必要がある場合は、代替の公開リソースを準備してください。

GET リクエストを組み立てる

url クエリパラメータを指定し、認証付き GET リクエストを /v1/youtube/transcript に送信します。このページには curl、JavaScript、Python、Java、Go の例があるため、サービスで使う言語と HTTP クライアントに合わせて取り入れられます。

字幕言語を選択

希望する字幕言語がある場合は、en や zh などの BCP 47 タグを使って省略可能な language パラメータを渡します。リクエストが返せるのは公開動画に既にある字幕トラックだけで、新しい翻訳トラックや利用できない言語は返せません。

JSON レスポンスを解析

アプリケーションで返された language、完全な text、segments を読み取ります。検証可能な引用、時刻付き検索結果、学習メモ、RAG コンテキストが必要な場合は、セグメントの時刻情報を保持してください。保存するのは製品に必要なフィールドだけにします。

422 を正しく処理

API が 422 を返した場合、その動画には利用可能な公開字幕トラックがありません。一時的な失敗ではないため、変更していない URL を再試行しないでください。別の公開リソースを選ぶか、別課金の文字起こしワークフローを実行する前に明確な承認を得てください。

よくある質問

YouTube 字幕 API とは何ですか？

YouTube 字幕 API は、YouTube 動画から既存の公開字幕トラックを取得する認証付き GET エンドポイントです。公開動画 URL と、必要に応じて希望言語を渡します。成功時には字幕メタデータ、完全なテキスト、タイムスタンプ付きセグメントが JSON で返り、検索、調査、メモ、動画理解ワークフローに利用できます。

API で YouTube 動画の字幕を取得する方法はありますか？

はい。公開 YouTube 動画 URL を指定して、Bearer 認証付きで GET /v1/youtube/transcript を呼び出します。利用可能な公開字幕トラックがあれば API は構造化 JSON を返します。公開字幕がない動画のテキストを生成するものではないため、422 を受け取ったら同じ URL を変えずに再試行せず、別のリソースを選んでください。

YouTube 字幕 API で別言語の字幕を取得できますか？

はい。en や zh など BCP 47 の値を含む省略可能な language クエリパラメータを追加すると、希望する字幕言語をリクエストできます。YouTube 字幕 API が返せるのはその動画に実際に公開されているトラックだけで、字幕を翻訳したり、元動画にない言語版を生成したりすることはありません。

youtube-transcript-api はどのようなデータを返しますか？

成功した youtube-transcript-api レスポンスには、caption_type、language、video_id、完全な字幕テキスト、タイムスタンプ付き segments が含まれます。セグメント時刻により、抽出したテキストを元動画の具体的な位置に対応付けられます。ブラウザで表示された字幕ページに依存せず、JSON フィールドを保存、検索、調査、分析ワークフローに直接利用できます。

youtube_transcript_api のエラーはどう処理しますか？

400 はリクエストの修正、401 は有効な API key の設定が必要であることを示します。422 は提出した動画に利用可能な公開字幕トラックがないことを意味するため、同じ URL をそのまま再試行しません。一時的な 502、503、504 はバックオフで再試行し、成功しない場合は一時的な利用不可を報告してください。

冪等リトライで二重課金されますか？

されません。ネットワーク中断後にアプリケーションがリトライする可能性がある場合は、冪等キーを含めてください。同じキーでは保存済みレスポンスが再生され、同じリクエストが再実行されることはありません。これにより、youtubetranscriptapi 統合では元の結果を維持しつつ、重複課金処理を避けた制御可能なリトライ経路が得られます。