【推奨】音色クローン API

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

✅ 新規接続にはこの系統を推奨します。 多くのユーザーによる実際の評価では、この系統で生成した楽曲は原声の再現度が高く、完成品のボーカルがアップロードしたサンプル本人の音色に近くなります。そのため現在、対外的に推奨する第一候補としています。

比較: 以前の音声クローンと指定音声での生成 API（非推奨） も引き続き利用できますが、ナビゲーションでは「非推奨」と表示しており、新規接続には推奨していません。

• ドキュメント日付: 2026-09-26
• 対応範囲: 自分の音色を作成 → その音色で指定した楽曲をカバー / 音色で新曲を歌唱 → 進捗照会 → 完成品のダウンロード
• 本文中のインターフェース、フィールド、レスポンスはすべて実際の呼び出しで検証済み（「実測」と記した箇所が重点検証項目）

注記: 本文書はあなたが呼び出すインターフェースのみを説明します。素材処理、タスクスケジューリング、コンテンツ検証などはサーバー側で自動的に行われるため、クライアントでの実装は不要です。

0. 5 分で導入

4 ステップで、1 本のボーカルサンプルから 2 曲の完成品が得られます。

① 音色を作成    POST /api/music/voice-profile/create      → voice_id を取得（status=ready）
② 音色でカバー  POST /api/music/voice-profile/cover       → すぐに 2 つの song_id を取得
③ 進捗を照会    POST /api/music/query                     → status=completed までポーリング
④ 完成品をDL    GET  /api/music/download?song_id=…&kind=mp3

最小の実用例（curl）:

API_KEY="sk-あなたのキー"
BASE="https://www.suno-api.io"

# ① 音色を作成（ボーカルサンプルをアップロード。10 秒以上・10MB 以内を推奨）
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=私の音色" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② この音色で 1 曲をカバー（song_clip_id = カバーする楽曲の clip id）
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\n歌詞本文…",
        "style_requirements": "スローフォーク、アコースティックギター",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ ポーリング（複数の id を半角カンマ区切りでまとめて渡す）
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ 完成後に mp3 をダウンロード（status=completed でのみファイルが得られる）
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. 共通の取り決め

1.1 ドメインと環境

下文のすべてのパスは Base URL からの相対です。たとえば POST /api/music/voice-profile/create の完全なアドレスは https://www.suno-api.io/api/music/voice-profile/create です。

1.2 認証

すべてのインターフェースは同じリクエストヘッダーを使い、値は管理画面で作成した API Key です。

Authorization: Bearer sk-xxxxxxxx

• Bearer プレフィックスは付けても付けなくても構いません。sk- プレフィックスも同様です（Authorization: sk-xxx も有効）。
• Key がない、または無効 → HTTP 401。レスポンスは {"success":false,"message":"…"} の形です（文言はリクエスト言語に応じて変わります）。
• 各 Key は自分のアカウントの楽曲と音色だけを見て、操作できます。

1.3 リクエストボディの形式

• 音色作成: multipart/form-data（ファイルアップロード）を推奨。application/json（URL または base64）にも対応。
• その他のインターフェース: application/json。

1.4 2 種類のレスポンス外装（対客で見分ける必要があるのはこの 2 つだけ）

「音色管理」系（create / create-from-clip / list / detail / delete）は業務外装を使います。

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

「音色カバー」は生成チャネルを通り、生成外装を使います。成功は code/message/data、失敗は error オブジェクトです。

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

判定の手順: まず HTTP ステータスコード、次に success === false、最後に code !== 200 または error の有無を見ます。 業務上の失敗でも HTTP が 200 とは限りません（音色管理系はエラー時も HTTP 200 です）ので、HTTP ステータスコードだけで判断してはいけません。

1.5 冪等性

音色作成（「既存音声からの作成」を含む）は本当に冪等です: 同じ Key の下では、同じ client_request_id を再送しても音色は 1 件しか作られず、2 回目は 1 回目の結果をそのまま返します（success=true、同じ voice_id）。使い方は、クライアントが自分で id（UUID など）を生成し、タイムアウト後の再試行で同じ値を使い回すというものです。

カバーの送信はリクエスト単位の重複排除を行いません（1 回の課金生成です）。2 点に注意してください。

1. 送信識別子はリクエストヘッダー X-Create-Ui-Client-Request-Id: <あなたの送信 id> に置きます。これはサーバー側のタスク記録に書き込まれ、事後の調査に便利ですが、重複課金は防ぎません。
2. 送信タイムアウト ≠ 失敗です。リクエストはすでに受理され生成中の可能性があります。再試行の前に GET /api/music/songs?p=1&page_size=20（ページングパラメータは p / page_size、互換表記の ps も可）で generation_type=voice_profile_cover の新しい曲が現れていないか確認し、無い場合にだけ同じリクエストを送り直してください。

create と create-from-clip のボディにも client_request_id フィールドがあります（§3、§4 参照）。

1.6 課金の概要

価格はいつでも公開インターフェースから読めるので、固定値で書かないでください（§9 参照）。

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← 音色カバーの基準価格
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← 強化クローン価格
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

カバーは事前課金 + 失敗時の返金です:

• 拒否されたリクエスト（パラメータ誤り、プラットフォームの 4xx/5xx、残高不足そのもの）は課金されません。存在しない音色で送信した実測では残高がまったく変わりませんでした（delta = 0）。
• 受理されたタスクが最終的に失敗した場合（プラットフォームのサービス異常を含む）は、サーバー側の返金経路で事前課金額が戻ります。

1.7 ステータス辞書

音色の status:

楽曲の status（照会系インターフェースの戻り値）:

2. インターフェース一覧

3. 音色を作成する

POST /api/music/voice-profile/create

1 本のボーカル音声を「音色」として登録し、voice_id を取得します。プラットフォームにとって音色は「1 本の音声 + 曲庫内のその clip」にすぎないため、作成に成功するとその音源は永久に保持されます（以降のカバーで使用）。

3.1 3 つの入力形式（いずれか 1 つ）

形式 A: multipart でファイルをアップロード（推奨）

Content-Type: multipart/form-data

file=<音声バイナリ>          # 必須
title=<音色名>               # 任意。空ならファイル名から拡張子を除いたもの
file_name=<元のファイル名>
source_file_name=<元のファイル名>
source_kind=upload|record    # 任意。由来マーカー（アップロード / 録音）。既定は upload
enhanced=false|true          # 任意。true = 強化クローン（§3.5 参照）
client_request_id=<冪等キー>  # 任意
voice_id=<カスタム ID>        # 任意。通常は使いません

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=私の音色" \
  -F "source_kind=upload"

形式 B: JSON + 公網の音声 URL

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "私の音色"
      }'

• URL は公網から到達できる HTTPS の直リンクである必要があります。サーバーが 1 度ダウンロードし、当社のオブジェクトストレージへ転存します。
• アドレスを audio_url フィールドに入れても効果は同じです（両方送った場合は file_url を優先）。
• すでに本プラットフォームのオブジェクトストレージのアドレス（*.myqcloud.com/create-ui/voice-source/...）である場合は再ダウンロードせず、そのまま登録します。

形式 C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "私の音色"
}

• data:audio/xxx;base64, プレフィックスにも、純粋な base64 にも対応します。
• サイズに制限があります（base64 は 1.33 倍に膨らみます）。大きなファイルは形式 A を使ってください。

3.2 音声の要件

3.3 レスポンス

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "私の音色",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

フィールド説明（create / list / detail の 3 つは同じフィールド群を共有します）:

created_at / updated_at は秒単位のタイムスタンプ（10 桁）で、ミリ秒ではありません。

3.4 よくあるエラー

3.5 強化クローン（enhanced=true）

「音色サンプル自体に著作権のある歌詞が含まれる / 強化アップロードが必要」という場面向けです。価格は強化アップロード価格（既定 10 元/回、失敗時は自動返金）:

• レスポンスはすぐに status=processing + task_id（この時点では clip_id なし）で、非同期に実行されます。
• 処理中は GET /api/music/voice-profile/{voice_id} で進捗を照会でき、progress_percent / progress_stage / progress_message を返します。
• 完了すると status が ready になり、clip_id、audio_url、image_url が埋まります。
• 失敗すると status=failed になり、error_message は「強化アップロードに失敗しました。費用は自動返金されました。しばらくして再試行してください。」のような文言です。
• 強化クローンは通常作成より明らかに時間がかかります（分単位）。同期タイムアウトのロジックで待たないでください。

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=私の音色" -F "enhanced=true"

4. 既存の音声から音色を作成する

もうアップロードしたくない場合は、自分がすでにアップロード済み、または生成済みの音声をそのまま音色に複製できます。無料で冪等です。

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "徐清 強",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: 自分の名義にある完了済み音声の clip id（楽曲の song_id と同じ）。
• 同じ clip を再送しても新しいレコードは作られず、既存の音色をそのまま reused: true 付きで返します（実測）。

レスポンスは §3.3 の全フィールドに、読み取り専用の 2 つを加えたものです:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "徐清 強",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

エラー（message は原文のまま。そのまま表示するかローカライズを推奨）:

5. 音色の一覧 / 詳細 / 削除

5.1 一覧

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "私の音色", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

フィールドは §3.3 と完全に同じです。既定では削除済みの音色は返しません。

5.2 詳細

GET /api/music/voice-profile/{voice_id}

単一の音色オブジェクトを返します（data は配列ではなくオブジェクトそのもの）。強化クローンが処理中の場合、追加で次を返します:

5.3 削除

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• 削除すると一覧から消え、新しいカバーには使えなくなります: その voice_id で送信すると 400 を返します（§6.4 参照）。
• それで生成した曲はまったく影響を受けません。再生、ダウンロード、続きの生成、置き換え、分離はこれまでどおりです。
• 存在しない音色、または本アカウントに属さない音色の削除は {"success":false,"message":"voice not found"} を返します。

6. 音色でカバーする（中核インターフェース）

POST /api/music/voice-profile/cover
Content-Type: application/json

1 回の送信で 2 曲を生成します（通常生成と同じ）。

6.1 2 つのシナリオ

レスポンスの resolved_scene が cover か sing を返すので、どちらの経路を通ったか確認できます。

6.2 リクエストフィールド

リクエストヘッダー X-Create-Ui-Client-Request-Id: <同じ送信 id> も併せて付けることを推奨します: これだけがサーバー側のタスク記録に書き込まれ、事後調査の主キーになります（§1.5 参照）。

量の目安: audio_weight / style_weight / weirdness_constraint は 0〜1 の小数、variety は 0〜4 の整数、duration は秒です。混同すると拒否されるか、結果がおかしくなります。

シナリオ B の歌詞は任意です（モデルが自分で処理します）が、指定した内容を歌わせたいときは必ず lyrics を送ってください。

6.3 レスポンス

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "【タスク】これはカバーです。…（サーバーの固定構造部 + あなたが入力したカバー / スタイル要件）"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

要点:

1. 成品の識別は clips[].song_id（本インターフェースは id フィールドを返しません）。
2. すぐに 2 つの song_id を取得できますが、その時点の status はまだ processing（受理されただけ）で audio_url は空です。ダウンロードには completed までポーリングが必要です。play_url はプラットフォームの試聴ストリームで、送信段階から現れることもあり、期限切れになります。
3. description はサーバーが最終的に上送するプロンプト（固定構造部 + あなたが入力した cover_requirements / style_requirements）で、結果を調べるときに便利です。
4. source_updates はサーバーの素材処理結果で、クライアントは無視して構いません。
5. あなたが送った title はサーバーのタスク記録に書き込まれ、以降の照会で song_title として現れます。送信レスポンスの clips[].song_title は通常空で、これは正常です。

6.4 エラー

{ "error": { "message": "この音色は存在しないか削除されています（voice_id=vp_xxx）…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

残高不足は送信段階で課金エラーを直接返し、中途半端なタスクは残りません。

6.5 利用可能なモデル（対客モデル名）

対客モデル名（上記の名前）を使ってください。chirp-* はプラットフォーム内部の名称なので、直接使わないでください。

7. 進捗の照会

7.1 一括照会（推奨）

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids は半角カンマ区切りの文字列です（配列ではありません）。
• 戻りは裸の配列（いきなり [...] で、success / data の外装なし）です:

[
  {
    "song_id": "0f2a…",
    "song_title": "二匹の虎",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "【タスク】これはカバーです。…（サーバーの最終プロンプト）",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

ポーリングの目安: 5〜10 秒間隔、全体で 10〜15 分のタイムアウト（コールドアカウントの最遅実測は約 4 分半。ごく稀にもっと長い場合があります）。完了判定は audio_url が空かどうかではなく status で行ってください。

互換メモ: 本インターフェースは song_id を識別子にします。初期の一部レスポンスに id フィールドが現れたことがあるため、row.song_id || row.id と書くのが安全です。

7.2 1 曲の詳細

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "二匹の虎",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "二匹の虎",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• ここでの created_at / completed_at は Unix 秒です（一括照会の ISO 文字列とは異なります。クライアントは区別してください）。
• wav_url / video_url は本プラットフォームのダウンロード入口（現在のドメインからの相対）で、GET すればファイルが取れます。プラットフォームにその産物がない場合は空文字です。
• parameter_retention はその曲でどの送信パラメータを辿れるかを示します。core_parameters_available=true は歌詞 / スタイル / 出典などの核心パラメータが照会できること、extended_parameters_available=false のときは上に挙げた拡張パラメータが保存されていないこと（音色カバーは現在この分類です）を意味します。

7.3 自分の作品一覧

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=キーワード

ページングパラメータ: p（ページ番号、1 始まり）/ page_size（1 ページの件数、互換表記 ps）。任意の status、q（タイトルキーワード）。既定は作成時刻の降順です。

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "二匹の虎",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

generation_type=voice_profile_cover で「音色カバーが生んだ曲」と他の生成結果を区別できます。

8. 成品のダウンロード

8.1 mp3 を直接取る（推奨、無料）

3 つとも使えます。いずれか 1 つを選んでください:

1. 照会結果の audio_url を使う（オブジェクトストレージの直リンクで最も手軽）。
2. GET /api/music/download?song_id=<id>&kind=mp3 → 音声バイトストリームを直接返します（Content-Disposition にファイル名入り）。
3. POST /api/music/download-url（署名付きの一時アドレスを取得）。

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

kind の値: mp3（song と等価）/ playback（ストリーミング再生）/ wav / video / lyrics / timestamped_lyrics。 timestamped_lyrics（.lrc）は現在一部の楽曲のみ対応です。失敗した場合はタイムスタンプ付き歌詞 API で自分で生成してください。 レスポンスはそのままファイルバイトストリームで、Content-Type と Content-Disposition（ファイル名）は設定済みです。GET /api/music/songs/{song_id} が返す wav_url / video_url は kind=wav|video を付けた同じ入口です。

8.2 wav 変換 / 歌詞 / メタデータ取得（課金あり）

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files が対応する値: mp3 / wav / lyrics / metadata。1 回に最大 10 曲。
• 成功した曲数で課金（0.2 元/曲）。曲全体が失敗した場合は課金されず、ある形式だけの失敗は songs[].errors に現れます。
• 以前に取得済みのファイルを再取得する場合は、まず無料の POST /api/music/free2/cached（同じ song_ids + files）でアーカイブ先を取ってください。その戻りの songs[].missing_files がキャッシュされておらず再準備が必要な形式を示します。

9. 価格の照会

GET /api/pricing/catalog

認証不要の公開インターフェースです。対客で表示すべき単価はすべて data.catalog.meta（文字列）にあります:

価格は管理画面で調整されるため、リアルタイムに読み取り、クライアントに固定値で書かないでください。カバーの実際の課金 = voice_generation_price ×（max_mode が真ならさらに max_mode_factor）。

10. 制限と注意事項

1. アップロードサイズ: 10MB 以下（サーバーの許容上限はもっと高いですが、入口ゲートウェイが 10MiB で巨大なボディを切り詰め、「Suno に拒否された」ように見えます。手前で止めてください）。
2. サンプルの長さ: 最短 6 秒、10〜60 秒を推奨。短すぎるとプラットフォームに拒否されます。
3. サンプルの内容: クリーンなボーカル。既存録音とよく似たものは避けてください（曲庫の照合で拒否されます）。
4. テキスト上限: lyrics は 3000 文字以内。style_requirements / negative_tags / title はそれぞれ 1000 / 1000 / 100 文字以内を目安に（スタイルとカバー要件はプロンプトに連結されるため、合計を 3000 文字以内に収めてください）。
5. 歌詞は書き換えません: 渡したとおりに歌います（1 文字も違わず）。ローカルでの切り詰めも行いません。
6. 1 曲につき必ず 2 曲を産出します。1 曲だけ返ると仮定しないでください。
7. 音源は永久保持: 音色を削除しても音源は消去されません。これは以降のカバーを可能にし、コンプライアンス上の追跡を保つためです。
8. 音色は ready でなければなりません: processing の音色はカバーに使えません。
9. リクエストタイムアウト: コールドアカウントの初回送信は最遅で実測約 4 分半です。クライアントのタイムアウトは 6 分以上にしてください。カバーはリクエスト単位の重複排除を行わないため、タイムアウト後は新しい曲がすでに生まれていないかを確認（§1.5）してから再送を判断してください。
10. 音色の帰属: 音色は作成者に帰属して管理されます。カバーは準備完了（ready）かつ未削除の音色だけを受け付けます。存在しない、削除済み、または本アカウントに属さない場合は 400 を返します: この音色は存在しないか削除されています（voice_id=…）。

11. よくある質問（FAQ）

Q1. 音色作成でお金はかかりますか？ 通常作成と「既存音声からの作成」はどちらも無料です。課金されるのはカバー（1.2 元 / MAX 2.4 元）と強化クローン（既定 10 元）だけです。

Q2. 伴奏付きの完成曲を音色サンプルに使えますか？ おすすめしません。音楽が入っているもの、または曲庫の既存録音とよく似たものはプラットフォームに拒否されます（This audio matches an existing recording in our catalog.）。純粋な乾声を使ってください。

Q3. カバー送信後に audio_url が空なのはなぜですか？ 送信は受理されただけで、status はまだ processing です。/api/music/query を status=completed までポーリングして初めて、再生 / ダウンロード可能なアドレスが出ます。

Q4. シナリオ B（song_clip_id を送らない）で歌詞は必要ですか？ 任意です。指定した内容を歌わせたいときは lyrics を送ってください。送らない場合はモデルが自分で処理しますが、制御性は下がります。

Q5. 顧客が自分でアップロードした音声をそのまま音色にできますか？ できます。create の file_url 形式を使うか、先に楽曲としてアップロードしてから create-from-clip を呼んでください。

Q6. 失敗したら返金されますか？ 直接拒否されたリクエスト（パラメータ誤り / プラットフォームのエラー）は実測で課金されません。受理されたが最終的に失敗したタスクは事前課金額が戻ります。終端失敗時はタスクが status=failed と error_message を返します。

Q7. 音色を削除した後、それで生成した曲はまだ聴けますか？ 聴けます。削除はその音色を新しいカバーに使えるかどうかにだけ影響します。

Q8. 一度にどれくらいの長さの曲をカバーできますか？ duration は 1〜480 秒です。送らない場合はプラットフォームが原曲 / 素材から自動で決めます。プラットフォームの成品は最短で約 30 秒である点に注意してください。30 秒未満を指定しても、実測では 29.96 / 29.76 秒でした。

付録 A: 完全な呼び出し例（Node.js、ポーリングとダウンロード付き）

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① 音色を作成（multipart）
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② カバー
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "スローフォーク、アコースティックギター",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ 完了までポーリング（5 秒ごと、最大 15 分）
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // 裸の配列
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ ダウンロード
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "私の音色");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\n歌詞…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

付録 B: 変更履歴