YouTubeの文字起こしを1本だけ手作業でダウンロードするのは簡単です。しかし、数百〜数千本の公開動画を安定して処理するワークフローを作るとなると話は別です。字幕のない動画があり、希望した言語が存在しないこともあり、自動生成されたテキストには誤りが含まれることもあります。そのうえ、すべての結果は元の動画と紐づけたままにしておく必要があります。
このガイドでは、SocQ YouTube Transcripts APIを使って取得可能な公開YouTubeの文字起こしテキストを取得し、複数の動画URLを非同期タスクで処理して、正規化された結果を検索、要約、リサーチ、検索拡張生成(RAG)向けに整える方法を紹介します。
結論(クイックアンサー): 公開YouTube動画のURLと、任意のBCP-47言語を
POST /v1/youtube/transcriptsに送信します。返されたtask_idを保存し、タスクのエンドポイントをポーリングして、完了したレコードをdata.results.itemsから読み取ります。使える公開字幕がある場合、SocQはプレーンテキストの文字起こしと動画のコンテキストを返します。字幕がない場合に、新たな音声認識(speech-to-text)を生成することはありません。
公式のYouTube APIで公開動画の文字起こしをダウンロードできますか?
できません。公式のYouTube Data APIにはキャプションのリソースがありますが、そのダウンロードメソッドは、認証済みユーザーが管理を許可されている字幕トラック向けに設計されています。Googleの現在のドキュメントによると、captions.downloadにはOAuth認可が必要で、ユーザーにその動画の編集権限がなければなりません。このメソッドは、1回の呼び出しにつき200クォータユニットも消費します。
自分が所有または管理しているチャンネルであれば、この方法で問題ありません。しかし、任意の公開動画から字幕テキストをダウンロードする汎用的な手段にはなりません。認可の要件については、Google公式の字幕ダウンロードのドキュメントを参照してください。
ユースケースは次の3つに分けて考えると整理しやすくなります。
| 要件 | 適したアプローチ |
|---|---|
| 自分が所有する動画の字幕を管理する | OAuthを使ったYouTube Data API |
| 選んだ公開動画から、すでに利用可能な字幕テキストを取得する | SocQのようなマネージドな文字起こしエンドポイント |
| 字幕がない場合に音声を文字起こしする | 別途用意する音声認識(ASR)パイプライン |
SocQが対応するのは2つ目のケースです。利用可能な文字起こしテキストを取得するもので、すべての公開動画に文字起こしがあるとは主張しませんし、新たに生成したASRテキストを黙って代わりに返すこともありません。
YouTube文字起こしのリクエストを送信する
エンドポイントは、1件以上の公開動画のURLを受け付けます。enやzh-CNのような優先言語も指定できます。
curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.youtube.com/watch?v=arj7oStGLkU"
],
"language": "en"
}'
送信すると非同期タスクが開始されます。返されたtask_idを保存してください。処理がすぐに終わらないからといって、同じバッチを再送信してはいけません。
タスクが終了状態になるまでポーリングします。
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queuedとrunningは、途中の正常な状態です。タスクが成功したら、data.results.itemsを読み取ります。結果ページがhas_more: trueを返した場合は、返されたnext_cursorで次のページをリクエストします。
文字起こしのレスポンスを理解する
正規化された文字起こしレコードは形式が安定しているため、YouTubeのページを解析せずにそのまま保存できます。
{
"id": "arj7oStGLkU",
"platform": "youtube",
"resource": "transcripts",
"type": "transcript",
"url": "https://www.youtube.com/watch?v=arj7oStGLkU",
"title": "Inside the Mind of a Master Procrastinator",
"text": "A plain-text transcript snapshot.",
"language": "en",
"available_languages": ["en"],
"format": "plaintext",
"transcript_source": "auto_generated",
"author": {
"id": "UCAuUUnT6oDeKwE6v1NGQxug",
"username": "TED",
"name": "TED",
"url": "https://www.youtube.com/@TED"
},
"created_at": "2016-04-06T00:00:00",
"collected_at": "2026-07-16T08:00:00Z",
"extra": {
"duration_seconds": 843
}
}
後続の処理で特に重要なフィールドは次のとおりです。
text:選択されたプレーンテキストの文字起こし。language:実際に返された言語。希望した言語と異なる場合があります。available_languages:その動画で見つかった、空ではない文字起こしの言語。transcript_source:判明している場合の、字幕のソース分類。id、url、title、author:トレーサビリティのための出典コンテキスト。created_atとcollected_at:公開時刻と収集時刻。extra.duration_seconds:品質チェックや作業量の見積もりに役立ちます。
レスポンスは意図的にプレーンテキストにしています。信頼できるセグメントのタイムスタンプや話者ラベルは含まれません。正確な引用時刻を作り出したり、タイムスタンプのデータがあるかのようにレスポンスをSRTへ変換したりしないでください。
適切な言語で文字起こしを取得する
リクエストの言語はあくまで希望であり、保証ではありません。本番のワークフローでは、常に返されたlanguageに基づいて振り分けてください。
たとえばenをリクエストした場合は、次のようになります。
- 英語のトラックが選択される場合があります。
- 互換性のある基本言語のトラックが選択される場合があります。
- フォールバックとして、利用可能な別のトラックが返される場合があります。
- 使える公開文字起こしがなければ、レコードが生成されない場合があります。
すべての文字起こしにlanguageとavailable_languagesを一緒に保存してください。言語のカバレッジが厳密に必要な場合は、フォールバックの結果を翻訳、検索、LLMにそのまま渡さず、除外するか確認してください。
transcript_sourceも保持してください。自動生成字幕は大規模な処理では価値がありますが、YouTubeは、音質が悪い、非対応の言語、長い無音、話者の重なり、複数言語の混在があると、自動字幕が生成されない、または品質が下がることがあると説明しています。YouTubeの自動字幕のトラブルシューティングのガイダンスを参照してください。
YouTubeの文字起こしを一括処理する
一括処理は、すべてのURLが成功する前提のループではなく、データパイプラインとして設計してください。
Video URLs
↓
Validate and deduplicate
↓
Submit transcript batches
↓
Persist task IDs
↓
Poll with backoff
↓
Read every result page
↓
Validate language and source
↓
Store, chunk, index, or export
次のプラクティスを取り入れてください。
- 送信前にURLを正規化する。 重複するwatch、共有、埋め込みのURLを、同じ動画IDに集約します。
- バッチを復旧可能に保つ。 各バッチについて、入力URL、タスクID、送信時刻、終了ステータスを保存します。
- バックオフを入れてポーリングする。 間隔の短いポーリングループは避け、タスクがqueuedやrunningのままの間は待ち時間を延ばします。
- 部分的な出力を想定内として扱う。 使える字幕がない動画があるため、成功したタスクでも、送信したURLより少ないレコードしか含まれないことがあります。
- 最後までページネーションする。
has_moreがfalseになるまで続けます。 - 書き込みを冪等にする。 動画IDと文字起こしの言語でupsertし、リトライで重複が生じないようにします。
- 収集時刻を記録する。 文字起こしはスナップショットであり、字幕は後から編集または削除されることがあります。
次は、最小限のNode.jsによるポーリングのパターンです。
const headers = {
Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
"Content-Type": "application/json"
};
const submitted = await fetch(
"https://api.socq.ai/v1/youtube/transcripts",
{
method: "POST",
headers,
body: JSON.stringify({
urls: [
"https://www.youtube.com/watch?v=arj7oStGLkU",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
],
language: "en"
})
}
).then(response => response.json());
let task;
do {
await new Promise(resolve => setTimeout(resolve, 3000));
task = await fetch(
`https://api.socq.ai/v1/tasks/${submitted.task_id}?limit=50`,
{ headers }
).then(response => response.json());
} while (["queued", "running"].includes(task.data.status));
if (task.data.status !== "succeeded") {
throw new Error(`Transcript task ended with ${task.data.status}`);
}
const transcripts = task.data.results.items;
本番で使う前に、HTTPステータスのチェック、上限付きのリトライ、カーソルによるページネーション、構造化ログ、キャンセル処理を追加してください。
字幕がない場合と部分的な結果への対処
結果がないからといって、バッチ全体が失敗したとは限りません。よくある原因は次のとおりです。
- 投稿者が字幕を提供しておらず、自動字幕も利用できない。
- 公開されたばかりの動画で、字幕がまだ処理中である。
- 話されている言語が非対応、または認識されなかった。
- 音質が悪い、音声が重なっている、または動画に複数の言語が含まれている。
- 動画が非公開、削除済み、制限付き、または収集環境から利用できない。
- 希望した言語がなく、使えるフォールバックもない。
失敗は、延々とリトライするのではなく分類してください。
| 失敗の種類 | 推奨される対応 |
|---|---|
| 使える字幕がない | 利用不可としてマークする。必要に応じて別のASRワークフローに回す |
| 希望した言語がない | available_languagesを確認するか、管理されたフォールバックを受け入れる |
| 一時的なタスクまたはネットワークのエラー | 指数バックオフと上限を設けてリトライする |
| 非公開、削除済み、または制限付きの動画 | リトライをやめて理由を記録する |
| 空または疑わしい文字起こし | 検証のために隔離する |
ASRの出力を、出典を明示せずにYouTubeの字幕として提示しないでください。この区別は、正確性のレビューや引用で重要になります。
文字起こしデータを安全にエクスポートする
プレーンテキストの結果は、TXT、JSON、CSVにエクスポートできます。
TXTの場合は、textフィールドを書き出し、メタデータのレコードを別ファイルで保持します。JSONの場合は、正規化されたオブジェクト全体を保存します。CSVの場合は、id、url、title、language、transcript_source、text、collected_atなどのフィールドで、動画1本につき1行にします。
SRTとVTTにはタイミング付きのセグメントが必要です。SocQの文字起こしエンドポイントはセグメントではなくプレーンテキストを返すため、このレスポンスだけでは、忠実なタイミング付き字幕のエクスポートは作成できません。
検索可能なアーカイブでは、文字起こしの本文だけを保存しないでください。派生するすべてのレコードに、動画ID、正規のURL、タイトル、チャンネル、言語、ソース、公開時刻、収集時刻を保持します。
検索とRAG向けに文字起こしを整える
生の文字起こしは通常、大きすぎてノイズも多いため、1つのブロックとしてモデルに送るには向きません。より良いワークフローは次のとおりです。
- 元のテキストを書き換えずに、空白を正規化する。
- 極端に短いテキストや空のテキストを検出する。
- テキストを、重なりを持たせた意味的なチャンクに分割する。
- すべてのチャンクに出典のメタデータを付ける。
- 埋め込みを作成する。
- チャンクを検索インデックスまたはベクトルインデックスに保存する。
- 回答のたびに、動画のURLと文字起こしのメタデータを返す。
実用的なチャンクのレコードは、次のようになります。
{
"video_id": "arj7oStGLkU",
"video_url": "https://www.youtube.com/watch?v=arj7oStGLkU",
"title": "Inside the Mind of a Master Procrastinator",
"language": "en",
"transcript_source": "auto_generated",
"chunk_index": 12,
"text": "The transcript text for this chunk...",
"collected_at": "2026-07-16T08:00:00Z"
}
元のレスポンスにはセグメントのタイムスタンプがないため、正確な時間範囲を示すのではなく、動画を引用してください。時間単位の引用が不可欠な場合は、検証済みのセグメントを提供するソースを選ぶか、別途アライメントの工程を追加してください。
文字起こしを取得する前に、適切なYouTube APIを選ぶ
文字起こしの収集は、多くの場合、より大きなディスカバリーのワークフローの最終ステップです。
- 関連する公開動画を見つけ、字幕の有無で絞り込むには、YouTube Search APIを使います。
- 正規化された動画のメタデータには、YouTube Videos APIを使います。
- 選んだチャンネルの動画一覧を作るには、YouTube Channel Videos APIを使います。
- 実際にテキストが必要な動画に限って、YouTube Transcripts APIを使います。
これにより、不要な文字起こしのリクエストを減らし、最終的なデータセットを明確なディスカバリー条件に結びつけたままにできます。
文字起こしデータセットを最新に保つ
文字起こしのアーカイブには、明確な更新ポリシーが必要です。字幕は公開後に修正されることがあり、新しい言語のトラックが追加されることも、以前は利用できた動画が削除または制限されることもあります。毎日すべてを再取得するのは無駄ですが、最初のレスポンスを永続的なものとして扱うと、検索インデックスに古いテキストや出典を追跡できないテキストが残るおそれがあります。
更新の間隔は、ユースケースに応じて選んでください。
- 1回限りのリサーチ用データセットでは、収集時刻を保存し、分析で必要にならない限り自動更新は避けます。
- 検索可能なチャンネルのアーカイブでは、字幕が公開直後に編集されることが多いため、最近の動画をより頻繁に再確認します。
- コンプライアンスや引用のワークフローでは、引用を公開したり重要な判断を下したりする前に、出典を再検証します。
- 長期間運用するRAGシステムでは、コンテンツのハッシュを保持し、変更のない文字起こしで不要なチャンクの再分割や埋め込みの作業が発生しないようにします。
更新した文字起こしが変わった場合は、唯一のコピーを黙って上書きせず、新しいバージョンを作成するか、監査用の記録を残してください。最低限、動画ID、文字起こしの言語、字幕のソース、収集時刻、テキストのハッシュ、パイプラインのバージョンを保存します。ある動画が結果を返さなくなった場合は、既存のレコードを「最新のチェック時点で利用不可」とマークし、過去の文字起こしが最初から無効だったと決めつけないでください。
本番運用チェックリスト
大量のジョブを実行する前に、次の点を確認してください。
- 入力が公開YouTube動画のURLである。
- URLが正規化され、重複が除かれている。
- タスクIDと元の入力が保存されている。
- ポーリングに待ち時間と上限付きのリトライを使っている。
- カーソルによるページネーションが、
has_moreがfalseになるまで続く。 - 結果がないケースを、タスクの失敗とは別に扱っている。
- 返された言語を検証している。
- 自動生成字幕にラベルを付けている。
- すべてのチャンクやエクスポートに出典のメタデータが残っている。
- コンテンツの利用が、適用される権利、プライバシーへの期待、プラットフォームの規約を尊重している。
よくある質問(FAQ)
公式のYouTube Transcript APIはありますか?
YouTubeには公式のCaptions APIがありますが、字幕トラックのダウンロードにはOAuthと動画の編集権限が必要です。任意の公開動画向けの汎用的な文字起こしAPIではありません。
OAuthなしでYouTubeの文字起こしをダウンロードできますか?
SocQ YouTube Transcripts APIは、YouTubeのOAuth認可ではなく、SocQのAPIキーを使用します。選んだ公開動画のURLから、利用可能な文字起こしテキストを取得します。
字幕のない動画でも、SocQは文字起こしを生成できますか?
できません。このエンドポイントが返すのは、利用可能な公開の文字起こしテキストです。使える字幕のない動画は、結果が返らない場合があります。ASRによるフォールバックが必要な場合は、その旨を明示したうえで、別途speech-to-textのワークフローを使ってください。
言語を指定してリクエストできますか?
はい。enやzh-CNのような任意のBCP-47言語を送信できますが、実際に返される言語は異なる場合があります。必ずlanguageとavailable_languagesを確認してください。
レスポンスにタイムスタンプや話者ラベルは含まれますか?
いいえ。レスポンスの形式は正規化されたプレーンテキストで、セグメントのタイムスタンプや、保証された話者ラベルは含まれません。
1回のリクエストで複数の文字起こしを取得できますか?
はい。urlsに複数の公開動画のURLを指定して送信し、タスクIDを保存して、非同期タスクの成功後にすべての完了した結果ページを読み取ります。
YouTube Transcripts APIの料金はいくらですか?
現在のエンドポイントのドキュメントでは、正規化された文字起こしの結果1件あたり0.5クレジットと記載されています。料金は変わる可能性があるため、本番のワークロードを見積もる前に、最新のエンドポイントページを確認してください。