プロモード生成 API

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

インターフェースの説明

プロモードは、歌詞・スタイル・タイトルがすでに決まっていて、歌声やスタイル参考度、生成のランダム度まで制御したい場合に向いています。

エンドポイント: POST /api/music/create/custom

課金: 有料、現在は既定で 1 回 0.6 元。通常は 1 回につき 2 曲が返ります。実際の請求額は現在の管理画面の価格設定に従います。

Max Mode / Variety: 本エンドポイントは任意パラメータ max_mode と variety（0〜4）に対応しています。 max_mode を有効にするとこの 1 回は 2 倍の価格で課金され（0.6 → 1.2 元/回）、variety に追加課金は ありません。両者の意味と書き方は新版 API 概要の「高度なパラメータ」の節をご覧ください。

待ち時間とタイムアウト（重要）: 本エンドポイントは同期インターフェースで、レスポンスが返った時点で初めて注文が受理され生成に投入されます。実測では多くのリクエストが 1〜3 秒で返り、約 10% が 30 秒を超え、最長は約 230 秒です。クライアントのタイムアウトは 300 秒以上に設定してください。レスポンスが無いことは未生成を意味せず、タイムアウト直後の再試行は注文の重複と二重課金につながります。 接続が切れた場合は少し後に GET /api/music/songs で確認できます。詳しくは新版 API 概要の「待ち時間とタイムアウト設定」をご覧ください。

リクエストパラメータ

Headers

Body パラメータ

高度なパラメータの説明

声の性別 vocal_gender

• 男声は m または male、女声は f または female を渡します。
• サーバー側で male、female はそれぞれ m、f に正規化されます。
• instrumental=true のときは、声の性別パラメータは生成側に送られません。

スタイル参考度 style_weight

生成結果が style_tags をどれだけ参照するかを制御します。値が高いほど、入力したスタイルタグに沿った結果になりやすくなります。

ランダム度 weirdness_constraint

生成結果の変化の大きさと実験性を制御します。値が高いほど変化が大きく、低いほど無難な結果になりやすくなります。

数値パラメータはいずれも 0.0〜1.0 の範囲で、0 も有効な明示値です。フィールドを完全に省略した場合だけが「未指定」を意味します。

入力時は、これらが割合の小数であって百分率の整数ではないことに注意してください。目安: 0.0〜0.3 は保守的、0.4〜0.6 はバランス型、0.7〜1.0 は実験的。明確な好みがなければ 0.5 を使うか、そのまま省略しても構いません。例: weirdness_constraint: 0.5。50 や 50% は書かないでください。

instrumental=true のときは純音楽が生成されるため、歌詞と声の性別は歌唱曲のようには効きません。ボーカルが必要なら false を渡すか、そのフィールドを省略してください。ブール値は JSON の true/false を使い、文字列は使わないでください。

Python リクエスト例

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\n夜が海面に降りる\n窓辺をそっと風が過ぎる',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': '海辺の夕風',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

受理レシートモード（任意）

本エンドポイントもひらめきモード生成 API の受理レシートモードに対応しています。リクエスト本文に "accept_mode": "async"（またはヘッダ X-Accept-Mode: async）を付けると、インターフェースはすぐに 202 と受理番号を返し、生成はバックグラウンドで続きます。進捗は GET /api/music/requests/{request_id} で照会します。

クライアントが長い接続に適さない場合や、タイムアウトで「生成されていない」と誤判定したくない場合に適しています。このパラメータを付けない場合の動作は従来と完全に同じです。

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "海辺の夕風",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

返却構造とポーリング方法はひらめきモード生成 API の「受理レシートモード」の節をご覧ください。

パラメータ検証

次の場合は HTTP 400 を返し、エラー応答の message が無効なフィールドを示します：

• style_weight または weirdness_constraint が数値でない。
• 数値が 0.0 未満または 1.0 を超える。
• vocal_gender が m、f、male、female のいずれでもない。

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

次のフィールドも超過時は HTTP 400 を返し、生成に入らず、前受金も差し引かれません。数え方は Unicode 文字単位（漢字 1 字は 1 文字）で、前後の空白も含みます：

エラーメッセージは style_tags must not exceed 1000 characters; received 2772 の形です。先頭の語が超過したフィールド名、末尾が実測文字数なので、400 を受け取ったらこの 2 つの数字でそのまま削ればよく、フィールドを一つずつ試す必要はありません。共通の決まりは新版 API 概要の「テキストフィールドの上限」にあります。

レスポンス結果

通常は 2 曲を含む配列を返します。非同期リクエストの初期状態は通常 pending なので、song_id を保存し、楽曲照会 API で最終状態と音声アドレスを取得してください。曲のフィールドはひらめきモード生成 API と同じです。

互換フィールド

新規接続では snake_case に統一してください。同じリクエストで snake_case と camelCase を同時に渡した場合、snake_case の値が優先されます。