Suno API ドキュメント概要

2026-09-18 更新 · Suno-API チーム

メールアドレスで登録すれば API キーを作成できます。生成は 1 回 0.6 元で 2 曲を返し、MP3/WAV のダウンロード、カバー、続き生成、ステム分離、ボイスクローンに対応します。ベース URL は https://www.suno-api.io です。

このページでは、現在利用できるモデル、生成・編集インターフェースの一覧、課金方式、推奨の読み進め方を説明します。新規に接続する場合は上から順に読んでください。401/403/429 の調査入口もここにまとめています。

よくある質問（早見表）

API キーはどう取得しますか。 メールアドレスで登録し、コンソール → トークン管理で新しいトークンを作成するだけです。電話番号もカード登録も不要です。

1 回いくらですか。 生成は 1 回 0.6 元で 2 曲を返します。ステータス照会、WAV、タイムスタンプ付き歌詞、プロンプト提案などのインターフェースは追加料金がかかりません。

どのモデルに対応していますか。 suno-v6（既定）、suno-v6-wild、suno-v6-mini です。v5.5 以前の通常生成モデルは終了しており、既存の作品には影響しません。

ベース URL は何ですか。 https://www.suno-api.io で、ヘッダーに Authorization: Bearer YOUR_API_KEY を付けます。

現在利用できるモデル

通常の楽曲生成でお客様が指定できるモデルは suno-v6、suno-v6-wild、suno-v6-mini の 3 つで、model を省略した場合は suno-v6 が使われます。

通常モデル suno-v2、suno-v3、suno-v3-5、suno-v4、suno-v4-5、suno-v4-5-all、suno-v4-5-plus、suno-v5、suno-v5-5 は終了しました。過去のタスクを照会すると古いモデル名が残っていることがありますが、それは履歴データであり、そのモデルを新規リクエストに使えるという意味ではありません。例外はステム分離で、詳しくはステム（ボーカル・伴奏分離）APIをご覧ください。

認証方式

公開 API キーのインターフェースはすべて同じヘッダーを使います。

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

ベース URL：

https://www.suno-api.io

パラメータの共通ルール

• リクエストボディの number は JSON の数値で送ってください。百分率の文字列は使えません。強度 50% は 0.5 と書き、50 や 50% とは書けません。
• boolean は true か false を送ってください。true、false、0、1 などを代用しないでください。
• 「任意」と書かれたフィールドは、まったく送らなくて構いません。意味が確かでないパラメータは省略し、サービスの既定動作に任せてください。未送信の代わりに空文字列・null・0 を送らないでください。0 が有効な値になる数値フィールドがあるためです。
• フィールド名は綴りを区別します。各インターフェースのページに推奨フィールドと互換フィールドを記載しています。新規接続ではパラメータ表のとおりに送ってください。snake_case と camelCase の両方に対応すると書かれている場合も、同時に両方を送らないでください。
• _s または Seconds で終わる時間フィールドの単位は秒で、小数も使えます。Unix タイムスタンプは秒かミリ秒かを個別に明記しています。
• pending: で始まる ID はプラットフォームの仮 ID で、実際の楽曲 ID ではありません。仮 ID に対応すると明記されたインターフェース以外では使用せず、実際の song_id が返るまで待ってください。

テキストフィールドの上限

上限を超えるとそのまま HTTP 400 を返します。生成は始まらず、事前課金もなく、タスクレコードも作られません。文字数は Unicode 文字で数え（漢字 1 文字＝1 文字）、前後の空白も含みます。

超過時の message には対象フィールド名と実測文字数が出るので、その 2 つの数値に合わせて削れば済みます。

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

対象インターフェース：/api/music/create、/api/music/create/custom、/api/music/extend、/api/music/upload-cover、/api/music/generate-from-source、/api/music/add-instrumental、/api/music/add-vocal、/api/music/add-stem、/api/music/mashup、/api/music/sample、/api/music/inspo、/api/music/crop、/api/music/remove-section、/api/music/fade、/api/music/reverse、/api/music/speed、/api/music/replace-section、/api/music/generate-with-voice。

唯一の例外は POST /api/music/sounds の description（効果音の説明）で、上限は 100 文字です。効果音はプラットフォーム側のより短い制限を使います。

非同期生成と音声アドレス

楽曲生成のインターフェースは既定で非同期に動作します。最初の応答の status が pending、submitted、processing のとき、audio_url、video_url、cover_url が空なのは正常で、失敗を意味しません。実際の song_id（または返された client_request_id）を保存し、対応する照会インターフェースでポーリングしてください。音声アドレスを読んだりダウンロードしたりするのは、ステータスが完了になってからです。

⚠️ 音声アドレスの有効期限は 7 日です。早めに転送してください

audio_url、wav_url、video_url、および各種ダウンロードインターフェースが返すアドレスは、プラットフォームのオブジェクトストレージから配信され、既定で 7 日後に失効します（ファイルは回収され、古いアドレスは 404 / ダウンロード不可になります）。

• アドレスを取得したら 7 日以内にご自身のストレージへ移してください（自前のオブジェクトストレージ、CDN、サーバーのディスクなど）。当社のアドレスを長期リンクとして使わないでください。
• 失効しても楽曲の再生成は不要で、追加費用もかかりません。楽曲照会 API（またはメディアダウンロード API）を呼び直せば、その楽曲の新しい有効なアドレスを取得できます。

待ち時間とタイムアウト設定

生成系インターフェースは同期インターフェースです。応答が返った時点で初めて注文が受理され、プラットフォームへ生成が投入されます。それまではサーバー側でアカウントの割り当てと必要な安全確認を行うため、途中経過の応答は一切なく、他のインターフェースからもこの注文は見えません。したがって「生成されたかどうか」を判断できる唯一の根拠は応答そのもので、待っている間に観測できる現象ではありません。

実測の待ち時間（2026-09-18〜2026-09-20、本番環境の /api/music/create 系）

• 約 10% のリクエストは 30 秒以上かかり、約 1% は 1〜2 分かかります。待ち時間が長いリクエストは、今回だけ安全確認を 1 回通す必要があったケースがほとんどです。
• リクエストのフィールド、応答構造、エラーコード、課金方式はいずれも変わっていないため、既存の接続先はクライアントのタイムアウト設定を変えるだけでよく、他のコード変更は不要です。

接続時の要件

1. クライアントのタイムアウトは 300 秒以上に設定してください。既定が 30 秒・60 秒・120 秒のクライアントは待機中に自ら切断します。
2. 応答が無いことは、生成されていないことを意味しません。 接続がタイムアウト・切断した場合でも、注文はすでに受理されて生成中かもしれません。
3. タイムアウト後にすぐ再試行しないでください。同じ送信を繰り返すと新しい注文が作られ、再度課金されます。
4. 接続が切れた場合は、少し後に GET /api/music/songs を新しい順で確認してください。受理済みの注文は通常どおり一覧に出ます。本当に無いことを確認してから再送信してください。
5. 障害報告には応答ヘッダーの X-Oneapi-Request-Id を添えてください。その 1 件のリクエストを直接特定できます。

長い接続を張りたくない場合は受理レシート方式を。 POST /api/music/create と POST /api/music/create/custom は任意の受理レシートに対応しています。ボディに "accept_mode": "async"（またはヘッダー X-Accept-Mode: async）を付けると、すぐに 202 と受理番号が返り、生成はバックグラウンドで続きます。進捗は GET /api/music/requests/{request_id} で確認します。数十秒しかタイムアウトを取れないクライアントでも「生成されていない」と誤判定せず、再試行による二重課金も避けられます。詳しくはシンプルモード生成 APIの「受理レシート方式」をご覧ください。

参考：python requests は timeout=300、urllib は urlopen(..., timeout=300)、Node は req.setTimeout(300000)、curl は --max-time 300。

推奨インターフェース一覧

上記の /api/voice/clone/* と /api/music/generate-with-voice は初期のボイスクローン経路で、新規接続には推奨しません。 【推奨】ボイスプロフィール API をご利用ください。

詳細パラメータ：Max Mode と Variety

生成系インターフェースは次の 2 つの任意パラメータに対応しています（省略すれば従来の動作と価格のままです）。

これらに対応するインターフェース：POST /api/music/create、POST /api/music/create/custom、 POST /api/music/extend、POST /api/music/upload-cover、POST /api/music/generate-from-source、 POST /api/music/add-instrumental、POST /api/music/add-vocal、POST /api/music/add-stem、 POST /api/music/mashup、POST /api/music/sample、POST /api/music/inspo、 POST /api/music/replace-section、POST /api/music/voice-profile/cover、POST /api/music/speech。

• max_mode の 2 倍価格の例：既定 1 回 0.6 元のインターフェースは有効時に 1.2 元になります。 指定した声での生成 は既定 1 回 1.2 元で、有効時は 2.4 元です。 【推奨】ボイスプロフィール API のボイスカバーも同じく 1 回 1.2 元（max_mode 有効時は 2.4 元）です。
• variety は suno-v6 系（suno-v6、suno-v6-wild、suno-v6-mini）でのみ有効で、 他のモデルに送ると 400 を返します。
• 効果音生成、ステム分離、連結、WAV、Studio 系の編集アクション（トリミング、セクション削除、フェード、逆再生、速度変更など）に この 2 つのパラメータはありません。明示的に送ると 400 を返し、「送ったのに効かない」状態を作りません。
• variety は 0〜4 の整数そのままで、style_weight や weirdness_constraint（0〜1 の小数）とは桁の扱いが異なります。

共通の楽曲返却フィールド

生成、カバー、続き生成、分離、照会などのインターフェースは、通常は楽曲の配列を返します。よく使うフィールドは次のとおりです。

接続の 4 ステップ（最小構成の例）

新規接続はこの 4 ステップを順に実行すれば最初の 1 曲を取得できます。各ステップの詳細なフィールドは「推奨インターフェース一覧」の該当ページにあります。

# 1) 生成を送信：1 回 0.6 元で 2 曲
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandopop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) status が completed になるまでポーリング（3〜5 秒間隔が目安）
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "1 つ目の手順で返った song_id"}'

# 3) メディアアドレスを取得：読み取り系は無料。song / wav / video / cover / midi を指定できます
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "同じ song_id", "kind": "song"}'

問題が起きたときの入口：401 / 402 / 403 / 429 はエラー一覧を、タイムアウトと二重課金は上記の「待ち時間とタイムアウト設定」を、各インターフェースの説明は下記の「推奨インターフェース一覧」をご覧ください。

利用上の推奨

• 新規接続では suno-v6 に統一することをおすすめします。
• 既定価格を記載しているインターフェースでも、実際の請求額は現在の管理画面の価格設定とリクエストのモデルに従います。
• 生成系は通常、まずタスクを返し、最終的な音声は /api/music/query で取得します。
• wait_completion=true は完了までブロックして待つため、低頻度のテスト向けです。本番では非同期のポーリングを推奨します。
• 生成系は応答までに時間がかかることがあります。クライアントのタイムアウトは 300 秒以上に設定し、「応答が無い」ことは「生成されていない」ことではない点にご注意ください（上記「待ち時間とタイムアウト設定」参照）。
• アップロード、カバー、差し替え、WAV などはプラットフォームのアカウントとソース clip の権限に依存します。失敗した場合は、返された message または error_message を先に確認してください。

バージョンについて

このドキュメントは、現在の Create UI が実際に接続している機能に合わせて整理し直したものです。新規接続のお客様はまずこの節をお読みください。旧版のインターフェースドキュメントは「旧版インターフェースドキュメント（互換）」の節に残しており、既存のお客様は従来どおり呼び出せます。