YouTube サムネイルダウンローダー API

認証付き POST 1 回で公開 YouTube 動画サムネイルの直接 CDN 画像リンクを返します——自動フォールバック付き画質セレクター、きれいな JSON。

単一 REST エンドポイント
フォールバック付き画質
すべてのリンク形式
安定したレスポンスフィールド
冪等な課金書き込み
予測可能なエラーコード

リクエスト例

curl -X POST "https://api.agentbody.io/v1/youtube/thumbnail/download" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"quality":"maxresdefault","url":"YOUR_URL"}'

レスポンス例

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

Direct thumbnail image link and normalized public video metadata.

{
  "quality": "maxresdefault",
  "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_id": "dQw4w9WgXcQ"
}

機能特徴

YouTube サムネイル API をコンテンツ調査パイプライン、デザインツール、メディアライブラリに使う——動画 URL を入れ、CDN 画像リンクを得る。

単一 REST エンドポイント

bearer API キーと動画 URL を付けて POST /v1/youtube/thumbnail/download を呼びます。API が動画を解決し、サムネイルの直接 CDN リンクを返します。スクリーンショットツールもページスクレイピングも不要です。

フォールバック付き画質

quality に maxresdefault、sddefault、hqdefault、mqdefault を渡します。要求ティアが存在しない場合、操作は自動的に利用可能な最良のものにフォールバックし、提供したものを報告します。

すべてのリンク形式

watch URL、Shorts リンク、ライブ URL、embed リンク、youtu.be リンクがすべて解決します。統合側はユーザーが貼るものをそのまま受け付けます。

安定したレスポンスフィールド

毎回のレスポンスは thumbnail_url、quality、video_id、正規の動画 url を運びます。リクエストごとのパースなしでパイプラインが保存・結合できるフィールドです。

冪等な課金書き込み

サムネイル取得は従量課金です。再試行時に Idempotency-Key ヘッダーを送ると、中断されたレスポンスが同じ動画の二重課金になりません。同一キーの同一リクエストは元の結果を返します。

予測可能なエラーコード

ドキュメント化されたステータスコード：400 は無効なリクエスト、401 はキーの不足または誤り、409 は冪等性の競合、502/503/504 は一時的な上流の問題。各クラスは明確な修正または再試行アクションに対応します。

使い方

次のステップで YouTube サムネイル API を呼び出します。キーを作成し、POST リクエストを構築し、返された CDN リンクを処理します。

API キーを作成

AgentBody アカウントを作成し、コンソールで API キーを生成します。キーはサーバー側に保管し bearer トークンとして送信します。

リクエストを構築

必須の url と任意の quality を付けて /v1/youtube/thumbnail/download に POST を送信します。生成例は 5 つの言語での正確なリクエストを示します。

冪等キーを追加

再試行する可能性のあるすべての取得に Idempotency-Key ヘッダーを付けます。同一キーの同一リクエストは元のレスポンスを返し、再課金しません。

キーはサーバー側に

バックエンド、サーバーレス関数、定期ジョブからエンドポイントを呼びます。エンドユーザーが取得をトリガーする場合は独自エンドポイントでプロキシしてください。

JSON レスポンスをパース

返された thumbnail_url、quality、video_id、url を読み取ります。CDN リンクを所属する動画と一緒に保存します。フィールドはリクエスト間で安定です。

エラーを正しく処理

400 はリクエストを修正し、401 は有効なキーを設定し、409 はドキュメント化された冪等キーの動作に従います。502/503/504 は同じキーの下でバックオフ付きで再試行します。

よくある質問

YouTube サムネイルダウンローダー API とは何ですか？

認証付き POST エンドポイント /v1/youtube/thumbnail/download です。任意のリンク形式から公開 YouTube 動画を解決し、サムネイルを直接 CDN 画像 URL として返します。画質セレクター（maxresdefault から mqdefault）と、ティアが利用不可の際の自動フォールバックを備えます。

サムネイル API はどの解像度に対応していますか？

maxresdefault、sddefault、hqdefault、mqdefault です。デフォルトは max を要求し、そのティアが存在しない場合、API は利用可能な最良の画質にフォールバックし、提供したものを報告します。

料金はどうなっていますか？

各サムネイル取得はアカウントのクレジットで実行される従量課金の操作です。価格はゲートウェイが管理します。コンソールで確認し、冪等キーで再試行の二重課金を防いでください。

API はどの URL 形式を受け付けますか？

watch URL、Shorts リンク、ライブ URL、embed リンク、youtu.be 短縮リンク——エンドポイントはどのリンク形式からでも動画を検出します。

API でリンクから YouTube サムネイルをダウンロードできますか？

はい——動画リンク（watch、Shorts、ライブ、embed、youtu.be）を POST すると、レスポンスが thumbnail_url、quality、video_id、正規の動画 URL を JSON で返します。1 リンク 1 リクエストで、バッチパイプラインは反復するだけです。

サムネイル API の料金は？

各取得はアカウントのクレジットで実行される従量課金の操作です。価格はゲートウェイが管理し、コンソールで現在の費用を確認できます。冪等キーで再試行の二重課金を防げます。

非公開の動画に対応していますか？

いいえ。エンドポイントは公開動画のみを読み取ります。非公開、限定公開、削除済みのコンテンツは解決せず、YouTube 認証情報も要求されません。

API エラーの処理方法は？

400 はリクエストを修正し、401 は bearer キーを修正し、409 はドキュメント化された冪等キーの動作に従います。502、503、504 は一時的な上流の障害として、同じキーの下でバックオフ付きで再試行してください。