効果音生成 API
インターフェースの説明
効果音生成は数秒の効果音を作るもので、楽曲ではありません。雷、雨粒、衝突音といった短い音に向いており、トランジション効果音、環境音、ドラムループにも使えます。多くは 5 秒以内、最長でも 20 秒程度で、単発とループの 2 つのモードに対応します。
エンドポイント: POST /api/music/sounds
課金: 有料。現在は既定で 0.6 元/回。実際の請求額は現在の管理画面の価格設定に従います。
待ち時間とタイムアウト（重要）: 本エンドポイントは同期インターフェースで、レスポンスが返った時点で初めて注文が受理され生成に投入されます。実測では多くのリクエストが 1〜3 秒で返り、約 10% が 30 秒を超え、最長は約 230 秒です。クライアントのタイムアウトは 300 秒以上に設定してください。レスポンスが無いことは未生成を意味せず、タイムアウト直後の再試行は注文の重複と二重課金につながります。 接続が切れた場合は少し後に
GET /api/music/songsで確認できます。詳しくは新版 API 概要の「待ち時間とタイムアウト設定」をご覧ください。
リクエストパラメータ
Headers
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| Authorization | string | はい | Bearer YOUR_API_KEY |
| Content-Type | string | はい | application/json |
ボディパラメータ
| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| model | string | いいえ | suno-v6 | 対客モデル名: suno-v6、suno-v6-wild、suno-v6-mini |
| description | string | はい | - | 欲しい音を説明します。英語の短いフレーズが最も安定します。例: cinematic whoosh transition, bright impact |
| title | string | いいえ | - | タイトル。省略時は説明から生成できます |
| type | string | いいえ | one_shot | 種類: one_shot（単発）、loop（ループ） |
| loop | boolean | いいえ | false | ループするかどうか。type を loop にするのと同じ意味です |
| bpm | number | いいえ | - | BPM。0 より大きい数値である必要があります。不正な値は黙って無視されず 400（invalid_sound_bpm）を返します |
| key | string | いいえ | - | 調性。音名（C-B）+ 任意の #/b + 任意の Major/Minor の形式で、例: C Major、C#m、Bb。空または any は指定なしを意味します。不正な値は 400（invalid_sound_key）を返します |
リクエスト例
curl -X POST https://www.suno-api.io/api/music/sounds \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"description": "cinematic whoosh transition, bright impact",
"title": "cinematic whoosh",
"type": "one_shot",
"loop": false,
"bpm": 120,
"key": "C"
}'
レスポンス結果
楽曲の配列が返ります。フィールドは新版 API 概要の共通の楽曲返却フィールドと同じです。