YouTube Shorts to MP3 API

認証付き POST 1 回で任意の YouTube Shorts URL を保存済み MP3 に——音声ファイルリンクと正規化トラックメタデータをきれいな JSON で。

単一 REST エンドポイント
すべての Shorts URL 形態
フォーマット制御
正規化トラックメタデータ
冪等な課金書き込み
予測可能なエラーコード

リクエスト例

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

レスポンス例

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

Retained audio file and normalized public track metadata.

{
  "audio_format": "mp3",
  "audio_url": "https://example.com/audio.mp3",
  "bitrate": 192000,
  "bytes": 4194304,
  "channel_title": "Example Channel",
  "content_type": "audio/mpeg",
  "duration_seconds": 180,
  "size_mb": 4,
  "title": "Example Track",
  "url": "https://www.youtube.com/watch?v=Gef1KePPRoI",
  "video_id": "Gef1KePPRoI"
}

機能特徴

Shorts to MP3 API をサウンド収集パイプライン、ポッドキャストツール、コンテンツ業務に使う——Shorts URL を入れ、音声リンクを得る。

単一 REST エンドポイント

bearer API キーと Shorts URL を付けて POST /v1/youtube/music/download を呼びます。API が音声を保存し保持されたファイルリンクを返します。ストリームのリッピングもブラウザ自動化の維持も不要です。

すべての Shorts URL 形態

youtube.com/shorts/ リンク、youtu.be リンク、アプリ共有リンクがすべて同じリクエストで解決します。統合側はユーザーが貼るものをそのまま受け付けます。

フォーマット制御

リクエストごとに audio_format を mp3、m4a、webm で渡し、利用可否が地域により異なる場合は地域コードも任意で指定できます。レスポンスは実際に配送されたフォーマット、ビットレート、サイズを報告します。

正規化トラックメタデータ

毎回のレスポンスは audio_url に video_id、title、チャンネル、再生時間、ビットレート、ファイルサイズを組み合わせます。リクエストごとのパースなしで保存できる安定フィールドです。

冪等な課金書き込み

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

予測可能なエラーコード

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

使い方

次のステップで Shorts to MP3 API を呼び出します。キーを作成し、POST リクエストを構築し、返された音声リンクを処理します。

API キーを作成

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

リクエストを構築

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

冪等キーを追加

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

キーはサーバー側に

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

JSON レスポンスをパース

返された audio_url、タイトル、チャンネル、再生時間、ビットレート、サイズを読み取ります。リンクとメタデータを一緒に保存するか、URL をそのままストレージ層に渡します。

エラーを正しく処理

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

よくある質問

YouTube Shorts to MP3 API とは何ですか？

認証付き POST エンドポイント /v1/youtube/music/download です。公開 Short の音声を MP3、M4A、または WebM として保存し、保持された音声ファイルリンクと正規化メタデータ——タイトル、チャンネル、再生時間、ビットレート、サイズ——を構造化 JSON で返します。

Shorts URL を直接受け付けますか？

はい——youtube.com/shorts/VIDEO_ID リンクはネイティブに解決し、youtu.be リンクとアプリ共有リンクも同様です。1 つのリクエスト構造がすべての Shorts URL 形式をカバーします。

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

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

どのフォーマットを抽出できますか？

audio_format フィールドで mp3（デフォルト）、m4a、webm です。レスポンスは配送されたフォーマット、ビットレート、ファイルサイズを確認します。

非公開の Shorts から音声を抽出できますか？

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

API エラーの処理方法は？

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