YouTube文字起こしAPIが動かない？診断チェックリスト

診断チェックリスト

エラーコード（またはレスポンスの形）を以下の表と照らし合わせてください。

AWS、GCP、Azure、またはVPSでブロックされていますか？

スクリプトがノートPCでは完璧に動くのに、クラウドサーバーにデプロイした途端に失敗する場合、ほぼ常にこれが理由です：YouTubeの字幕取得エンドポイントは、個々の不正なIPだけでなく、データセンターのIP範囲全体をブロックします。何千もの無関係なスクリプトが同じアドレス範囲を共有しているため、大手クラウドプロバイダーのIP空間はいずれこれに当たります。

Could not retrieve a transcript for the video https://www.youtube.com/watch?v=...!
This is most likely caused by:
YouTube is blocking requests from your IP.

現実的な回避策を、おおよそ手間の順に挙げると：

• レジデンシャルまたはモバイルのプロキシプール経由でリクエストする - 時々は機能しますが、有料のローテーション型レジデンシャル設定でも失敗するという報告が増えています。恒久的な解決策ではありません。
• 複数のクラウドプロバイダーやリージョンをローテーションする - それらの範囲もいずれフラグ付けされるまでの時間稼ぎになります。
• 同じ動画を再取得しないよう積極的にキャッシュする - ブロックに当たる頻度は減りますが、なくなりはしません。
• このインフラをすでに運用しているホスト型APIを使う - 問題が「あなたのプロジェクト」から「それを機能させ続けるのが本当の仕事である誰か」に移ります。

それこそが、私たち自身のYouTube文字起こしAPIが埋めている本当のギャップです - 別のライブラリではなく、まさにこの問題のためにすでに構築されたインフラです。

PoTokenRequiredが出ますか？

より新しい障害モード：YouTubeの字幕エンドポイントは、実行時に自身のプレーヤーJavaScriptによって生成される証明トークンをますます要求するようになっています - クッキーでも、IPレピュテーションチェックでもなく、暗号学的な値です。単純なHTTPリクエストにはそれを生成する方法がありません。

実際の技術的詳細はjdepoix/youtube-transcript-api#592をご覧ください - その報告の時点では、オープンソースライブラリに文書化された回避策はありません。

これはまさにホスト型APIが吸収すべき種類の問題です - エンドポイントを1回呼び出すだけで、自分でトークン生成を解決する必要なく、文字起こしか明確なエラーが返ってきます。

各失敗に対して私たち自身のAPIが返すもの

すでに私たちのAPIを使っていて、HTTPステータスだけから推測するのではなく正確な失敗で分岐したい場合、すべてのエラーは安定した`code`フィールドとともに返ってきます：

curl "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
  -H "Authorization: Bearer sk_live_..."

# A failure looks like:
# { "success": false, "code": "TRANSCRIPT_DISABLED", "message": "Transcripts are disabled for this video." }

完全なパラメータリファレンスとすべてのステータスコードはAPIドキュメントにあります。