YouTube 動画ダウンロード API

認証付き POST 1 回で公開 YouTube URL を保存済み MP4 に——144p〜720p の画質セレクター、直接動画リンク、正規化メタデータをきれいな JSON で。

単一 REST エンドポイント
画質セレクター
正規化メタデータ
冪等な課金書き込み
予測可能なエラーコード
5 言語のサンプル

リクエスト例

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

レスポンス例

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

Downloaded YouTube media link and normalized public video metadata.

{
  "duration_seconds": 180,
  "format": "mp4",
  "quality": "720p",
  "size_mb": 15.2,
  "title": "Example Video",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_content_type": "video/mp4",
  "video_id": "dQw4w9WgXcQ",
  "video_url": "https://api.apify.com/v2/key-value-stores/example/records/dQw4w9WgXcQ.mp4"
}

機能特徴

YouTube 動画ダウンロード API を保存パイプライン、オフラインコンテンツシステム、メディア業務に使う——URL を入れ、MP4 リンクを得る。

単一 REST エンドポイント

bearer API キーと公開動画 URL を付けて POST /v1/youtube/video/download を呼びます。API は MP4 を保存し直接動画リンクを返します。ヘッドレスブラウザも yt-dlp の維持もプロキシのローテーションも不要です。

画質セレクター

quality フィールドに 144p、240p、360p、480p、720p のいずれかを渡します。毎回のリクエストが望む出力を固定し、レスポンスは実際に配送された画質、フォーマット、サイズを確認します。

正規化メタデータ

毎回のレスポンスは video_url に video_id、title、duration_seconds、format、quality、size_mb、video_content_type を組み合わせます。リクエストごとのパースなしで保存できる安定フィールドです。

冪等な課金書き込み

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

予測可能なエラーコード

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

5 言語のサンプル

このページはエンドポイントの OpenAPI 定義から curl、JavaScript、Python、Java、Go のリクエスト例を直接生成します。スタックが使っている HTTP クライアントをそのまま採用できます。

使い方

次のステップで YouTube 動画ダウンロード API を呼び出します。キーを作成し、POST リクエストを構築し、返された MP4 リンクを処理します。

API キーを作成

AgentBody アカウントを作成し、コンソールで API キーを生成します。キーはサーバー環境または承認されたシークレットストアに保管し bearer トークンとして送信します。ブラウザコードには決して入れないでください。

リクエストを構築

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

冪等キーを追加

再試行する可能性のあるすべてのダウンロードに Idempotency-Key ヘッダーを付けます。タイムアウト、接続切断、ワーカー再起動。同一キーの同一リクエストは元のレスポンスを返し、再課金しません。

キーはサーバー側に

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

JSON レスポンスをパース

返された video_url、video_id、title、duration_seconds、format、quality、size_mb を読み取ります。リンクとメタデータを一緒に保存するか、URL をそのままストレージ層に渡します。フィールドはリクエスト間で安定です。

エラーを正しく処理

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

よくある質問

YouTube 動画ダウンロード API とは何ですか？

認証付き POST エンドポイント /v1/youtube/video/download です。公開 YouTube 動画 1 本を MP4 として保存し、直接動画リンクと正規化メタデータ——video_id、タイトル、再生時間、フォーマット、画質、サイズ——を構造化 JSON で返します。

YouTube ダウンロード API の料金はどうなっていますか？

各動画保存はアカウントのクレジットで実行される従量課金の操作です。価格はこのページの固定数値ではなくゲートウェイが管理します。コンソールで現在の費用を確認し、冪等キーで再試行の二重課金を防いでください。

YouTube ダウンロード API はどの画質に対応していますか？

quality フィールドは 144p、240p、360p、480p、720p を受け付けます。この API の上限は 720p で、1080p や 4K の設定はありません。レスポンスは実際に配送された画質を報告します。

yt-dlp や自作スクレイパーの代替になりますか？

720p までの公開動画についてはイエス。yt-dlp の更新、フォーマット交渉、プロキシ処理を維持する代わりに、ドキュメント化された 1 つの REST エンドポイントを呼び、ファイルリンク付きの安定した JSON を受け取ります。

非公開やメンバー限定の動画をダウンロードできますか？

いいえ。エンドポイントは公開動画のみを読み取ります。非公開、メンバー限定、削除済みの動画は解決せず、制限を回避するための YouTube 認証情報も要求されません。

API エラーの処理方法は？

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