Voice clone and generate-with-voice API (not recommended)

Updated 2026-09-18 · Suno-API team

⛔ Legacy chain — not recommended for new integrations. This page documents the early persona chain (voice_task_id / generate-with-voice). It still works, but it is no longer recommended to customers; the left-hand navigation marks it "not recommended".

For new integrations use the 【Recommended】 Voice profile API: create a voice profile from one vocal sample (POST /api/music/voice-profile/create), then use it to cover a chosen song or to sing a new song. A voice profile is a first-class resource — it can be listed, fetched and deleted, and its source audio is kept permanently.

If your product needs the full loop "create a voice → reuse it for a long time → cover songs", prefer the new chain.

Important: a cloned voice can expire.

The voice_id / voice_task_id produced by voice cloning is not a permanently usable resource — it can stop working because its validity period elapsed or because the account or voice state changed. Integrators must not clone once and then reuse a locally cached voice ID forever.

Recommended practice:

• Store voice_task_id, voice_id, is_available, updated_at and the time of the last successful generation.
• Before every generation that uses a cloned voice, call GET /api/voice/clone/tasks/{voice_task_id} or POST /api/voice/clone/tasks/{voice_task_id}/check and confirm is_available=true.
• If the endpoint reports that the voice is unavailable, that the task does not exist or returns selected voice is not ready, ask the user to clone again or to pick another available voice.
• Do not promise end users that a cloned voice is a "permanent asset"; show a hint in your product UI that "a voice can expire and may need re-validation or re-cloning".

Endpoint description

This group of endpoints creates a reusable voice and generates songs with it. The caller only needs the API Key issued by the platform; the server handles task submission, status synchronisation, billing and downloads.

Authentication: Authorization: Bearer YOUR_API_KEY

Billing:

• Voice validation, voice cloning, status queries, deletion and downloads: free.
• The one-step clone entry in the workspace: a flat ¥5 per call; it completes source-voice validation and the second verification audio automatically, and refunds on failure.
• Continuing automatically into the verification audio after an ordinary clone: a flat ¥5 per call, refunded on failure according to the existing flow.
• Generating a song with a cloned voice: charged, a flat ¥1.2 per call; each call usually returns 2 placeholder tasks.
• With Max Mode switched on (max_mode: true on POST /api/music/generate-with-voice) the ¥1.2 per call is billed at 2×, that is ¥2.4 per call; voice generation also supports variety (0-4, no extra charge) — see the "Advanced parameters" section of the new API overview.

Calling flow

1. Call POST /api/voice/clone/validate to upload the source voice and obtain a voice_task_id.
2. Wait or poll GET /api/voice/clone/tasks/{voice_task_id} until you get validate_info.
3. The user reads the text out and records the verification audio.
4. Call POST /api/voice/clone/tasks/{voice_task_id}/generate to submit the verification audio.
5. Call POST /api/voice/clone/tasks/{voice_task_id}/check or keep polling the task until is_available=true.
6. Call POST /api/music/generate-with-voice to generate a song with that voice.
7. The generation endpoint first returns placeholder tasks; once generation finishes and you have the real song_id, use the download endpoints to fetch a single file or a bundle.
8. (Optional) When the voice is no longer needed, call DELETE /api/voice/clone/voices/{voice_task_id} to delete it — the semantics are in section 6.

There is also a one-step clone: on the first recording/upload page in the workspace you can choose to finish in one go, and the system completes validation and voice creation together, so you do not have to record a second verification audio; it costs ¥5 per call with a refund on failure.

Voice task fields

1. Submit the source voice for validation

Endpoint: POST /api/voice/clone/validate

Body parameters

vocal_end_s - vocal_start_s must meet the minimum vocal-segment requirement. Upload a clear vocal recording with no obvious backing music or noise.

Request example

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": "My Chinese female voice",
    "description": "A clear, natural Chinese female voice",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Response example

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "My Chinese female voice",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Query a voice task

Endpoint: GET /api/voice/clone/tasks/{voice_task_id}

Request example

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

Response example

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "My Chinese female voice",
      "validate_info": "Please read out the verification text returned here",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Regenerate the verification text

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Use this when the verification text is unsuitable to read out loud or when validation has to be redone.

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. Submit the verification audio and create the voice

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/generate

Body parameters

Request example

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": "My Chinese female voice"
  }'

5. Check whether the voice is usable

Endpoint: 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 '{}'

When the task is usable, is_available in the response is true and a voice_id is returned.

6. Delete a voice

Endpoint: DELETE /api/voice/clone/voices/{voice_task_id}

Billing: free.

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

Response example

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

What happens after deletion

• The voice can no longer be used to generate new songs: calling POST /api/music/generate-with-voice with this voice_task_id (or its voice_id) is rejected with the message selected voice is not ready, and nothing is charged.
• Songs already generated with it are completely unaffected: playback, download, extend, replace and separation all keep working.
• The voice task disappears from queries: GET /api/voice/clone/tasks/{voice_task_id} returns record not found.
• The source audio is kept under the platform's permanent-retention policy (since 2026-09-23, deleting no longer cleans up the vocal sample you uploaded), but that does not mean it can be restored: this old task has ended, and continuing with the same voice means going through the clone flow again, which yields a new voice_task_id.
• Deleting twice: deleting the same task again returns record not found (it is already in the deleted state and can no longer be found).

7. Generate a song with a cloned voice

Endpoint: POST /api/music/generate-with-voice

Billing: ¥1.2 per call.

Body parameters

suno-v6, suno-v6-wild and suno-v6-mini are supported; an empty model is treated as suno-v6. The old V5/V5.5 models are retired, but historical tasks may still show the old model names.

The shared request structure also parses Create UI compatibility fields such as task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId and voiceId, but they are not valid customer parameters for this endpoint: a voice task must be sent as voice_task_id, an optional voice verification must be sent as voice_id, and voice music generation never reads the sound fields.

How to fill in the generation parameters

• With customMode=false, prompt holds the song description; with customMode=true, prompt holds the full lyrics, and style and title must be filled in as well. Do not send lyrics into the description field of simple mode, or treat a song description as advanced-mode lyrics.
• weirdnessConstraint and styleWeight are both decimal ratios from 0.0 to 1.0; you cannot send 50 or 50%. 0.5 is a reasonable balanced value; omitting them means "unspecified", while 0 is a valid explicit value.
• vocalGender accepts only m, male, f or female. instrumental is a compatibility-only field on this endpoint — cloned-voice generation is always treated as a vocal song.
• waitAudio does not change behaviour here; the endpoint always returns placeholder tasks asynchronously. An empty audio_url in the initial result is normal: query with client_request_id and read the audio address only after the result completes.

Header parameters

Idempotency-Key behaviour:

• The first request writes a persistent idempotency record before billing;
• If the same key with the same request has already completed, the first acceptance response is replayed, with no second charge and no second task;
• The same key with a different request body is rejected;
• The same key while still processing returns a stable "processing" error, and only exposes a safe client_request_id once one has been generated;
• After the first request under a given key fails, it stays failed; retrying requires a new key.

sourceClipId cover requirements

Source covers on the customer API are handled entirely server-side: the server deals with source-song access and the customer passes no account information. Whether a cover is allowed is decided by the actual endpoint response.

The source must belong to the current API user, be a completed workspace song that is not pending: and have usable audio. Ordinary generation, ordinary upload sources and enhanced-upload final songs are supported; enhanced-upload intermediate records are rejected before billing. The server only accepts the source song ID submitted by the customer and never an account ID from the customer; an unavailable or unfinished source returns an error before billing.

Request example

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": "Write a Chinese pop song about the seaside on a summer night",
    "style": "Mandopop, warm piano, emotional",
    "title": "Sea breeze on a summer night",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Response example

{
  "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": "Sea breeze on a summer night",
        "prompt": "Write a Chinese pop song about the seaside on a summer night"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Sea breeze on a summer night",
        "prompt": "Write a Chinese pop song about the seaside on a summer night"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

About placeholder tasks and the final song_id

generate-with-voice is an asynchronous generation endpoint. A successful response only means the generation task has been submitted, not that the song has finished generating.

Key fields in the response:

Note: a placeholder_id starting with pending: cannot be used as the final song_id, nor passed to /api/music/query or the download endpoints. Calling /api/music/query with only pending:* values may return an empty array [], because the real song is not finished yet or the placeholder task has not been replaced by the final song ID.

Wrong example:

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

Correct flow:

1. Call POST /api/music/generate-with-voice to submit the voice-generation task.
2. Store client_request_id, items[].placeholder_id and items[].client_request_index from the response.
3. Poll GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Once items[].song_id has a value that does not start with pending:, call /api/music/query, /api/music/download-file or /api/music/download-all.

The current version adds a public query endpoint:

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

It returns the task results for that client_request_id under the current user, so customers can look up the final song_id themselves. In the returned list:

• song_id is the real song ID;
• placeholder_id only appears while the task is still a placeholder;
• a value starting with pending: cannot be used with /api/music/query or the download endpoints.

If you only stored the client_request_id or a pending:* placeholder ID, call this results endpoint first; if the real song_id is still not found, send the client_request_id to technical support for help.

Query the results of voice generation

Endpoint: GET /api/music/generate-with-voice/results

Billing: free.

Query parameters

Request example

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"

Processing response example

{
  "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": "Sea breeze on a summer night"
      }
    ]
  }
}

Completed response example

{
  "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": "Sea breeze on a summer night",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Top-level status values

8. Download a single file

Endpoint: POST /api/music/download-file

Body parameters

Request example

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

The response is a file stream; Content-Type and the file name follow what the backend returns.

9. Bundle download of song assets

Endpoint: POST /api/music/download-all

Body parameters

Request example

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

The bundle usually contains the audio, the cover and metadata.json; if some asset type has not been generated yet it is left out of the archive.

Common errors

Errors from this endpoint group always return HTTP 200: judge success from the success field in the body (false means failure, with the reason in message) and do not look only at the HTTP status code. The full semantics of deleting a voice (whether it remains usable, whether it can be restored) are in section 6.