YouTube MP3 変換 API

1 回の POST で公開 YouTube 動画を MP3、M4A、WAV、FLAC など 8 形式に変換。レスポンスは永久音声ダウンロード URL と正規化されたトラックメタデータを返します。

1 POST、1 音声ファイル
永久ダウンロード URL
8 形式、7 段階のビットレート
上限のある予測可能なコスト
冪等性を設計に組み込み
正直なエラー契約

リクエスト例

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

レスポンス例

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

Retained audio file URL and normalized public track metadata.

{
  "audio_url": "https://example.com/audio-dQw4w9WgXcQ.mp3",
  "bitrate": "192k",
  "channel": "Example Channel",
  "duration_seconds": 212,
  "file_size_bytes": 3407872,
  "format": "mp3",
  "thumbnail_url": "https://example.com/thumbnail-dQw4w9WgXcQ",
  "title": "Example Track",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_id": "dQw4w9WgXcQ"
}

機能特徴

youtube.audio_download オペレーションは公開 YouTube 動画 1 本を保存済み音声ファイルに変換します。API キーはサーバー側に置き、エンドポイントは 1 回の呼び出しで永久ダウンロード URL と正規化メタデータを返します。

1 POST、1 音声ファイル

POST /v1/youtube/audio/download に公開 YouTube URL と任意の format、bitrate を送信します。200 成功時は video_id、url、title、channel、duration_seconds、audio_url、thumbnail_url、format、bitrate、file_size_bytes を返却——ダウンロードパイプラインに必要なフィールドが 1 レスポンスに揃います。

永久ダウンロード URL

audio_url は期限切れになる CDN リダイレクトではなく、完全に保存されたファイルを指します。どのサーバー、どの IP からでも、いつでもダウンロードできるため、キューワーカー、メディアサーバー、エンドユーザーにそのまま渡せます。再変換は不要です。

8 形式、7 段階のビットレート

format パラメータは mp3（デフォルト）、m4a、wav、aac、flac、opus、vorbis、alac を受け付けます。bitrate は source、auto（デフォルト）、320k、256k、192k、128k、64k。ロスレス形式はビットレートを無視し、指定ビットレートがソースストリームを超えることはありません。

上限のある予測可能なコスト

各呼び出しは 1 本の動画のみを固定価格で変換します——プレイリスト URL は拒否され、上流のコストガードが約 25 分を超える動画を拒否します。統合側が際限のない課金に直面することはなく、失敗した変換は課金されません。

冪等性を設計に組み込み

すべてのリクエストに Idempotency-Key ヘッダーを付けます。同じキーでのリトライは二重課金なしで元の結果を返すため、不安定なネットワーク上でも安全に再試行できます。409 は 2 回目の変換ではなくキー競合を意味します。

正直なエラー契約

400 は URL・形式・ビットレートの不正、401 はキーの欠落・誤り、502/503/504 は上流の変換失敗でバックオフリトライが適切です。非公開・年齢制限の動画はプラットフォーム自体が拒否するため、上流エラーとして表面化します。

使い方

curl または任意の HTTP クライアントで、6 ステップで YouTube MP3 変換 API を統合できます。

API キーを作成

無料の AgentBody アカウントに登録し、コンソールで API キーを作成します。キーはサーバーに置いてください——ブラウザやモバイルクライアントのバンドルに含めてはいけません。

公開動画を選ぶ

公開 YouTube 動画を選び、watch ページ、youtu.be 短縮リンク、Shorts、embed URL など任意の形で URL を取得します。エンドポイントは課金処理の前に URL を検証します。

変換リクエストを POST

curl -X POST https://api.agentbody.io/v1/youtube/audio/download -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: <uuid>" -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","format":"mp3"}'。format と bitrate は任意で、デフォルトは mp3 と auto です。

200 を待つ

呼び出しは同期的で、ファイルを完全にダウンロード・保存するため通常数分で返ります。HTTP クライアントのタイムアウトは 5 分以上に設定し、504 は変換失敗ではなくリトライ可能なタイムアウトとして扱います。

レスポンスを読む

200 時は audio_url からファイル本体を取得し、メタデータフィールド——title、channel、duration_seconds、file_size_bytes、thumbnail_url——を表示や保存に使います。format と bitrate は実際の出力内容をエコーします。

ファイルを配信または保存

完全な管理が必要なら audio_url から自前のストレージにストリーム保存するか、リンクをそのままユーザーに渡します。URL が永久有効なため、どちらのパターンでも API を再呼び出しする必要はありません。

よくある質問

1 回の変換の料金は？

成功した各変換は、アカウントの料金ページに表示される固定価格で課金されます——価格はゲートウェイが管理するため、サイトに固定値は記載していません。失敗した変換は課金されず、長い動画は上流で制限されるため、形式・ビットレートに関わらず固定価格が維持されます。

必須のリクエストフィールドは？

必須は url のみです：公開 YouTube 動画 URL（watch、youtu.be、Shorts、embed）。format はデフォルト mp3 で、m4a、wav、aac、flac、opus、vorbis、alac を受け付けます。bitrate はデフォルト auto で、source、320k、256k、192k、128k、64k を受け付けます。

なぜ呼び出しに数分かかるのですか？

期限切れの CDN リンクを返す変換ツールと違い、この API はレスポンス前に音声ファイルを完全にダウンロード・保存します——それが返り値の URL が永久有効な理由です。一般的な楽曲は 1〜3 分で完了します。クライアントタイムアウトは 5 分確保し、504 はリトライしてください。

プレイリストや長いポッドキャストを変換できますか？

いいえ。エンドポイントは 1 呼び出しにつき 1 本の動画のみを変換し、プレイリスト URL を拒否します。約 25 分を超える動画は上流のコストガードで拒否され、固定価格が維持されます。バッチ処理は動画ごとに 1 呼び出しを、それぞれ独立した冪等キーでキューイングしてください。

リトライと冪等性はどう機能しますか？

変換ごとに一意の Idempotency-Key を含めます。同じキーでのリトライは二重課金なしで元の結果を返します。409 はそのキーが別のパラメータで使用済みであることを意味します。ネットワーク障害や 5xx レスポンスは同じキーで安全にリトライできます。

API が変換できないコンテンツは？

非公開、限定公開、年齢制限の動画はプラットフォーム自体がアクセスを拒否するため変換できず、上流エラーとして表面化します。著作権法と YouTube の利用規約に従い、所有・許可・その他の合法根拠のある公開コンテンツのみを変換してください。