YouTube Data API 字幕: captions.downloadが失敗する理由

YouTube Data API のcaptions.downloadエンドポイントから403 Forbiddenレスポンスを表示するターミナル

YouTube Data APIを通じて文字起こしを取得しようとしている場合、おそらくすでに壁にぶつかっているでしょう: captions.listは任意のビデオに対して字幕トラックIDを問題なく返しますが、その瞬間にcaptions.downloadを呼び出すと403エラーが返されます。APIキーを確認したり、youtube.force-sslスコープを追加したり、OAuthを試したり、相変わらず403が返ってきます。これはバグではなく、クォーターの問題でもありません。仕様です。ドキュメントがその要点を埋めています。

制限、正確には

captions.downloadは、ビデオの所有者のアカウントからのOAuthトークンが必要です。認証されたどのアカウントではなく、チャネルの所有者（またはそれへの権利を持つコンテンツマネージャー）です。字幕エンドポイントは、クリエイターが自分のアップロードに字幕トラックを管理できるように存在しています: .srtをアップロードしたり、タイプミスを修正したり、悪い自動翻訳を削除したりします。任意の第三者のビデオから字幕をダウンロードすることは、これまで契約の一部ではありませんでした。

エラーメッセージはそれを注意深く読むと明確に述べています:

The permissions associated with the request are not sufficient
to download the caption track.

つまり、通常のエスカレーションパス―APIキー→自分としてのOAuth→より広いスコープ→サービスアカウント―は行き止まりになります。各段階が同じ所有権チェックに失敗します。これを受け入れる前に私は午後を費やしました。Stack Overflowのトラフィックを見ると、インターネットの半分も同様に苦労しています。

captions.listがまだ良い点

Data APIを擁護するなら: captions.listは素のAPIキーで動作し、約50クォーターユニットがかかります。それはどのトラックが存在するか、その言語、そして自動生成されたものか（trackKind: "asr"）、またはユーザーがアップロードしたものかを示します。ビデオにトラックがまったくない場合、事前に字幕抽出ではなく音声テキスト化が必要であることがわかるため、これは本当に有用な事前チェックです。Data APIは検索、プレイリスト列挙、メタデータにとって正しいツールでもあります。ただし、トランスクリプトテキストをあなたに渡すことはしません。

オプション1: プレイヤーが行う方法で字幕を取得する

ビデオプレイヤーは明らかに所有者のOAuthトークンなしで字幕データを受け取ります。youtube-transcript-api（Python）のようなライブラリは同じ方法でそれを取得します。ラップトップではこれはうまく機能し、3行で済みます。

注意点は本番環境で現れます: YouTubeはデータセンターIPレンジからのリクエストに積極的に異議を唱えます。AWS、GCP、またはHerokuに同じ3行をデプロイすると、「ボットではないことを確認するためにサインインしてください」とIpBlockedエラーが表示され始めます。そのエラーモードと回避策を別の記事「youtube-transcript-apiがクラウドでブロックされる理由」に書きました―短いバージョン: 住宅用プロキシで修正可能ですが、それ自体が1つのプロジェクトです。

オプション2: ホストされた文字起こしAPI

URLからテキストを取得したいだけなら、ホストされたエンドポイントは両方の問題をスキップします―所有権要件がなく、プロキシの監視もありません。youtube2text.orgは字幕の取得をサーバー側で回転する住宅用プロキシの後ろで実行するため、あなたのリクエストはそこから来ます:

# grab a free demo key (shared, 5 videos/month per IP)
curl -s https://youtube2text.org/api/demo-key

# fetch a transcript
curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID" \
  -H "x-api-key: yt_YOUR_KEY"

レスポンスは素のJSON:

{"result": {"videoId": "...", "title": "...", "pubDate": "...",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

ビデオに単に字幕がない場合、404でTRANSCRIPT_UNAVAILABLEが得られます―captions.listが空のトラックリストとして示すのと同じ状況ですが、2つの呼び出しの代わりに1つで検出されます。

curlでYouTube文字起こしを抽出するにはエラーハンドリングを含む長めのチュートリアル、requestsベースのコードがより速い場合はyoutube-transcript-api移行ガイドのPythonバージョンがあります。

理に適った統合セットアップ

両端からこれを戦ってきた今日、実際に構築するなら:

Data APIは検出用―検索、チャネルアップロード、プレイリスト、公開日。これはメタデータのために信頼性があり、寛容にクォーターされています。
トランスクリプトエンドポイント（ホストされた、またはプロキシを楽しむなら自分でスクレイピング）実際のテキスト用。
音声テキスト化はフォールバックのみ―字幕がまったくないビデオの場合。

所有していないビデオに対してcaptions.downloadをこの中段の仕事を強制的にさせようとするのは、唯一のカテゴリー的に機能しないパスです―スコープ、キー、またはコンソール設定の変更がそれを変わることはありません。

共有されたデモキーではなく独自のキーが必要な場合、youtube2text.org/app/keysではサインインはGoogleのみです―電話番号もカードも必要ありません。無料ティアは月5ビデオ; 有料プランは50で$5.99から始まります。