音声クローンと指定音声での生成 API（非推奨）

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

⛔ 旧系統のため、新規接続には推奨しません。 本ページは初期の persona 系統（voice_task_id / generate-with-voice）を扱います。現在も利用できますが、対外的には推奨していません。左側のナビゲーションでも「非推奨」と表示しています。

新規接続には【推奨】音色クローン API をご利用ください。1 本のボーカルサンプルから音色を作成し（POST /api/music/voice-profile/create）、その音色で指定した楽曲をカバーしたり、新しい歌を歌わせたりできます。音色はファーストクラスのリソースで、一覧・取得・削除ができ、元の音声も永久に保持されます。

「音色を作成 → 長期的に再利用 → カバー」という一連の流れが必要な製品では、新しい系統を優先してください。

重要: クローンした音声は期限切れになることがあります。

音声クローンで生成される voice_id / voice_task_id は、永続的に使えるリソースではありません。有効期限、アカウントの状態、音声の状態の変化によって使えなくなることがあります。連携側は、初回のクローンに成功したあと、ローカルにキャッシュした音声 ID をそのまま永久に使い回してはいけません。

推奨する運用:

• voice_task_id、voice_id、is_available、updated_at、直近の生成成功時刻を保存する。
• クローン音声で生成する前に、毎回 GET /api/voice/clone/tasks/{voice_task_id} または POST /api/voice/clone/tasks/{voice_task_id}/check を呼び、is_available=true を確認する。
• 音声が利用できない、タスクが存在しない、selected voice is not ready などのエラーが返ったら、ユーザーに再クローンまたは別の利用可能な音声の選択を促す。
• クローン音声をエンドユーザーへ「永久資産」として約束しない。製品の画面で「音声は期限切れになることがあり、再検証または再クローンが必要です」と案内する。

インターフェースの説明

本グループのインターフェースは、再利用可能な音声を作成し、その音声で楽曲を生成するためのものです。呼び出し側はプラットフォームが発行する API Key を使うだけで、タスク投入・状態同期・課金・ダウンロードはサーバー側が一括して処理します。

認証方式: Authorization: Bearer YOUR_API_KEY

課金:

• 音声の検証、音声クローン、状態照会、削除、ダウンロード: 無料。
• ワークスペースのワンステップ・クローン入口: 1 回 5 元の固定。元音声の検証と 2 回目の検証音声までを自動で完了し、失敗時は返金されます。
• 通常クローンの完了後に続けて検証音声を自動生成する場合: 1 回 5 元の固定。失敗時は既存のフローに従って返金されます。
• クローン音声で楽曲を生成: 有料、1 回 1.2 元の固定。1 回の呼び出しで通常 2 件のプレースホルダータスクが返ります。
• Max Mode を有効にする（POST /api/music/generate-with-voice に max_mode: true を渡す）と、上記の 1 回 1.2 元が 2 倍の 1 回 2.4 元で課金されます。音声生成も variety（0〜4、追加課金なし）に対応しています。値のルールは新版 API 概要 の「高度なパラメータ」の節をご覧ください。

呼び出しフロー

1. POST /api/voice/clone/validate を呼び、元音声をアップロードして voice_task_id を取得します。
2. GET /api/voice/clone/tasks/{voice_task_id} を待つかポーリングし、validate_info を取得します。
3. ユーザーが validate_info を読み上げて検証音声を録音します。
4. POST /api/voice/clone/tasks/{voice_task_id}/generate を呼び、検証音声を提出します。
5. POST /api/voice/clone/tasks/{voice_task_id}/check を呼ぶかタスクを照会し続けて、is_available=true になるまで待ちます。
6. POST /api/music/generate-with-voice を呼び、その音声で楽曲を生成します。
7. 生成インターフェースはまずプレースホルダータスクを返します。楽曲の生成が完了して実際の song_id を取得したら、ダウンロードインターフェースで単体ファイルまたは一括ファイルを取得できます。
8. （任意）この音声が不要になったら DELETE /api/voice/clone/voices/{voice_task_id} で削除します。意味は第 6 節をご覧ください。

ほかにワンステップ・クローンもあります。ワークスペースの初回録音／元音声アップロード画面で一括完了を選ぶと、検証と音色作成を一度に終わらせ、2 本目の検証音声を録音する必要がありません。1 回 5 元で、失敗時は返金されます。

音声タスクのフィールド

1. 元音声の検証を提出する

エンドポイント: POST /api/voice/clone/validate

Body パラメータ

vocal_end_s - vocal_start_s は最短のボーカル区間の要件を満たす必要があります。明瞭で、目立つ伴奏やノイズのないボーカル録音をアップロードしてください。

リクエスト例

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "私の中国語女性ボイス",
    "description": "澄んで自然な中国語の女性ボイス",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "私の中国語女性ボイス",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. 音声タスクを照会する

エンドポイント: GET /api/voice/clone/tasks/{voice_task_id}

リクエスト例

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "私の中国語女性ボイス",
      "validate_info": "ここで返る検証テキストを読み上げてください",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. 検証テキストを再生成する

エンドポイント: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

検証テキストが読み上げに適さない場合や、検証をやり直したい場合に呼び出します。

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. 検証音声を提出して音声を作成する

エンドポイント: POST /api/voice/clone/tasks/{voice_task_id}/generate

Body パラメータ

リクエスト例

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "私の中国語女性ボイス"
  }'

5. 音声が利用可能か確認する

エンドポイント: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

タスクが利用可能になると、レスポンスの is_available が true になり、voice_id が返ります。

6. 音声を削除する

エンドポイント: DELETE /api/voice/clone/voices/{voice_task_id}

課金: 無料。

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

削除するとどうなるか

• 新しい楽曲の生成には使えなくなります: この voice_task_id（またはその voice_id）で POST /api/music/generate-with-voice を呼ぶと拒否され、エラーメッセージは selected voice is not ready で、課金はありません。
• すでにこの音声で生成した楽曲はまったく影響を受けません: 再生、ダウンロード、続きの生成、置き換え、ステム分離はこれまでどおりです。
• この音声タスクは照会から消えます: GET /api/voice/clone/tasks/{voice_task_id} は record not found を返します。
• 元音声はプラットフォームの永久保持ポリシーに従って保持されます（2026-09-23 以降、削除してもアップロードしたボーカル素材は消去されません）。ただし復元できるという意味ではありません: この古いタスクはすでに終了しており、同じ声を使い続けるにはクローンの流れをもう一度通す必要があり、新しい voice_task_id が発行されます。
• 二重削除: 同じタスクをもう一度削除すると record not found が返ります（すでに削除状態で、照会できません）。

7. クローン音声で楽曲を生成する

エンドポイント: POST /api/music/generate-with-voice

課金: 1 回 1.2 元。

Body パラメータ

suno-v6、suno-v6-wild、suno-v6-mini に対応しています。モデルが空の場合は suno-v6 として処理されます。旧 V5/V5.5 モデルは終了しましたが、過去のタスクには古いモデル名が残っていることがあります。

共有のリクエスト構造は task、soundType、soundLoop、soundBpm、soundKey、voiceTaskId、voiceId などの Create UI 互換フィールドも解釈しますが、これらは本インターフェースの有効なお客様パラメータではありません。音声タスクは必ず voice_task_id で渡し、任意の音声検証は voice_id で渡す必要があり、音声での楽曲生成が sound 系フィールドを読むことはありません。

生成パラメータの記入方法

• customMode=false のときは prompt に楽曲の説明を、customMode=true のときは prompt に完全な歌詞を入れ、style と title も必ず入力します。歌詞を簡易モードの説明フィールドへ誤って渡したり、楽曲の説明を詳細モードの歌詞として扱ったりしないでください。
• weirdnessConstraint と styleWeight はどちらも 0.0〜1.0 の比率の小数で、50 や 50% は指定できません。バランスの取れた値としては 0.5 が使えます。省略は「指定なし」を意味し、0 は有効な明示値です。
• vocalGender に使えるのは m、male、f、female だけです。instrumental は本インターフェースでは互換フィールドにすぎず、クローン音声の生成は常にボーカル曲として扱われます。
• waitAudio は本インターフェースでは挙動を変えず、常に非同期でプレースホルダータスクを返します。初期結果の audio_url が空なのは正常です。client_request_id で照会し、結果が完了してから音声アドレスを読んでください。

Header パラメータ

Idempotency-Key の挙動:

• 最初のリクエストは課金の前に永続的な冪等レコードを書き込みます。
• 同じ Key で同じリクエストが完了済みの場合、最初の受付レスポンスを再送し、再課金もタスクの再作成も行いません。
• 同じ Key でリクエストボディが異なる場合は拒否されます。
• 同じ Key がまだ処理中の場合は安定した処理中エラーを返し、生成済みの場合にのみ安全な client_request_id を返します。
• 同じ Key の最初のリクエストが失敗した場合は失敗状態のままなので、再試行には新しい Key が必要です。

sourceClipId でのカバー条件

お客様 API の参照元カバーは、参照元楽曲へのアクセスをサーバー側が一括して処理するため、お客様がアカウント情報を渡す必要はありません。利用可否は実際のレスポンスで判断してください。

参照元は現在の API ユーザーに属し、完了済みで pending: ではないワークスペースの楽曲で、利用可能な音声を持つ必要があります。通常生成、通常アップロードの参照元、強化アップロードの最終楽曲に対応します。強化アップロードの中間レコードは課金前に拒否されます。サーバーはお客様が提出した参照元楽曲 ID のみを受け付け、アカウント ID は受け付けません。参照元が利用できない、または未完了の場合は課金前にエラーを返します。

リクエスト例

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "夏の夜の海辺を歌った中国語ポップスを書いてください",
    "style": "Mandopop, warm piano, emotional",
    "title": "夏の夜の潮風",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "夏の夜の潮風",
        "prompt": "夏の夜の海辺を歌った中国語ポップスを書いてください"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "夏の夜の潮風",
        "prompt": "夏の夜の海辺を歌った中国語ポップスを書いてください"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

プレースホルダータスクと最終的な song_id について

generate-with-voice は非同期の生成インターフェースです。成功レスポンスは生成タスクを受け付けたことだけを意味し、楽曲の生成が完了したことを意味しません。

レスポンスの主なフィールドの意味:

注意: pending: で始まる placeholder_id は、最終的な song_id として使えず、/api/music/query やダウンロードインターフェースにも直接渡せません。pending:* だけで /api/music/query を呼ぶと空配列 [] が返ることがありますが、これは実際の楽曲がまだ完成していないか、プレースホルダータスクが最終的な楽曲 ID に置き換わっていないためです。

誤った例:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

正しい流れ:

1. POST /api/music/generate-with-voice を呼び、音声での楽曲生成タスクを提出します。
2. レスポンスの client_request_id、items[].placeholder_id、items[].client_request_index を保存します。
3. GET /api/music/generate-with-voice/results?client_request_id=cu_xxx をポーリングします。
4. 返ってくる items[].song_id に値が入り、pending: で始まらなくなったら、/api/music/query、/api/music/download-file、/api/music/download-all を呼びます。

現在のバージョンでは公開の照会インターフェースが追加されています:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

現在のユーザーに属する同じ client_request_id のタスク結果を返すため、お客様自身で最終的な song_id を照会できます。返るリストでは:

• song_id は実際の楽曲 ID です。
• placeholder_id はタスクがまだプレースホルダー状態のときだけ現れます。
• pending: で始まる値は /api/music/query やダウンロードインターフェースに使えません。

保存しているのが client_request_id または pending:* のプレースホルダー ID だけの場合は、まずこの結果インターフェースを呼んでください。実際の song_id がまだ見つからない場合は、client_request_id を技術サポートへ送って調査を依頼してください。

音声での楽曲生成結果を照会する

エンドポイント: GET /api/music/generate-with-voice/results

課金: 無料。

Query パラメータ

リクエスト例

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

生成中のレスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "夏の夜の潮風"
      }
    ]
  }
}

生成完了のレスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "夏の夜の潮風",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

最上位の status の意味

8. 単体ファイルをダウンロードする

エンドポイント: POST /api/music/download-file

Body パラメータ

リクエスト例

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

レスポンスはファイルストリームです。Content-Type とファイル名はバックエンドが返す値に従います。

9. 楽曲リソースを一括ダウンロードする

エンドポイント: POST /api/music/download-all

Body パラメータ

リクエスト例

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

一括ファイルには通常、音声・カバー・metadata.json が含まれます。まだ生成されていない種類のリソースは圧縮ファイルに入りません。

よくあるエラー

本グループのエラーはすべて HTTP 200 で返ります。成否はレスポンスボディの success フィールドで判断してください（false が失敗で、理由は message）。HTTP ステータスコードだけで判断しないでください。 音声削除の完全な意味（削除後も使えるか、復元できるか）は第 6 節をご覧ください。