APIでYouTubeの文字起こしを取得する方法(curl、Python、JavaScript)

APIでYouTubeの文字起こしを取得するには、動画のURLまたはIDとAPIキーを付けてHTTPリクエストを1回送り、レスポンスから文字起こしを読み取ります。このガイドでは、sum.videoの文字起こしAPIを使ったリクエストをcurl、Python、JavaScriptで示し、そのあと形式、エラー、料金を説明します。

APIが返すもの

このエンドポイントは、公開されているYouTube動画の既存の字幕を返します。制作者が書いた字幕でも、YouTubeが自動生成した字幕でも構いません。音声の文字起こしはしません。動画に字幕がない場合は、推測ではなくエラーが返ります(詳しくは後述)。

基本は次のとおりです。

• エンドポイント: POST https://sum.video/api/v1/transcript(GETも使えます)
• 認証: キーをX-API-Keyヘッダー、またはAuthorization: Bearer <key>で渡す
• 入力: urlまたはvideo_id
• 任意のlang(既定はen)
• 任意のformat: json、text、srt

レスポンスには、字幕トラックの実際の言語と自動生成かどうかも含まれるので、どの程度の品質か判断できます。

ステップ1: APIキーを作成する

ログインして、APIダッシュボード(sum.videoの/dashboard/api)でキーを作成します。有効なキーは最大5つ持てるので、ステージング用と本番用を分けるのに便利です。最初のキーには10クレジット(5件分の文字起こし)が無料で付くので、以下のすべてを無料で試せます。

ステップ2: 最初のリクエストを送る

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

GETも使えるので、URLを組み立てるだけのスクリプトからでも試せます。キーはログに残らないよう、ヘッダーで渡すのがおすすめです。

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript(Node 18以降またはブラウザ)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

キーはサーバー上で管理してください。ブラウザのコードに置いたキーは、開発者ツールを開けば誰でもコピーできます。

ステップ3: 適切な形式を選ぶ

動画の特定の場面にリンクしたいときはjsonを使い、セグメントのoffsetからリンクを作ります。LLMに渡すなら、textのほうが小さくて扱いやすくなります。あとで文字起こしの中を手作業で検索したい場合は、YouTube動画の文字起こし内を検索する方法を参照してください。

ステップ4: 言語を選ぶ

langの既定値はenです。deやesなど、ほしい言語を指定します。レスポンスには実際に返されたトラックの言語が入るので、思い込まずに確認してください。動画には字幕トラックが1つしかないことも多く、APIは実際の字幕を返すため、翻訳はしません。

ステップ5: エラーを処理する

最初から次のケースを想定しておきましょう。

• 404 no_transcript: 動画に字幕がない、またはライブ配信、非公開動画、削除済み動画です。再試行しても意味がありません。スキップするか、ユーザーに別の動画を尋ねてください。
• 402 budget_exceeded: 設定した月間クレジット上限に達しました。次のセクションを参照してください。
• レート制限: キー1つにつき1分あたり60リクエストまでです。バッチ処理は間隔をあけ、制限されたら待ち時間を延ばしてください。
• こちら側の障害: 少し待ってから再試行してください。料金はかかりません。

サーバーエラーでは再試行し、404ではスキップする単純なループで、本番で必要なことのほとんどをカバーできます。

料金

文字起こし1件につき2クレジットです。文字起こしを返さなかったリクエストや、sum.video側で失敗したリクエストは無料なので、404で残高が減ることはありません。残高はGET /api/v1/creditsで確認できます。

クレジットは買い切りのパックで販売され、有効期限はありません。

Proの購読者には、毎月100クレジットのボーナスも付きます。チャンネル全体を取り込むなどの大きな処理については、自動チャージと予算を扱うシナリオ大規模なRAGアプリのためのYouTube文字起こしを読んでください。料金ページも参照してください。

作り始める前に知っておきたい制限

• 字幕のある動画だけが対象です。404 no_transcriptの主な原因はこれです。
• 自動生成の字幕には、特に名前、アクセント、専門用語で誤りが含まれることがあります。
• APIが返すのは文字起こしだけで、要約はしません。文字起こしの上に要約、タイムスタンプ、チャットがほしい場合はYouTube要約ツールが担当します。1本の動画向けにコード不要で使えるのは文字起こしツールです。
• 公式のYouTube Data APIは代わりになりません。字幕のダウンロードメソッドには動画の編集権限が必要なので、自分の動画向けです(Googleのドキュメント)。

出典

• YouTube Data API: Captions.download
• sum.videoの文字起こしAPI