Suno Voice Cloning API Integration Guide

SUNO allows us to create custom voice personas through any audio file, enabling voice cloning for music generation. Unlike the existing Persona API (which uses Suno-generated audio_id), this API accepts a publicly accessible audio_url, namely your own vocal recording. This document explains how to integrate the voice cloning API.

Step 1: Create a Voice Persona

This API has three input parameters: audio_url (required), which is a publicly accessible MP3 or WAV audio file URL containing clear vocals from a single person; name and description (optional), which are the name and description of the voice persona.

Audio File Requirements

  • The audio format must be WAV or MP3
  • The audio duration must be between 10~240 seconds; clean single-speaker dry vocal material of 30~60 seconds is recommended
  • The audio should contain clear, recognizable speech or singing vocals from a single person
  • Be sure to avoid background noise, accompaniment, echo, and reverb; complete songs with accompaniment will usually fail voiceprint verification
  • Do not include multiple speakers or multiple vocal layers
  • Material with volume that is too low, unclear speech, or excessive noise may result in cloning failure or poor generation results Usage Restrictions
  • Voice personas created by uploading audio are private resources
  • This voice persona does not support reuse across accounts
  • It is recommended to use it as soon as possible after successful creation; it may become invalid or unavailable if left unused for a long time
  • The returned name is automatically generated by the system; please use the returned persona_id as the reference

Please Retry First When a Call Fails Voice cloning is a compute-intensive task. Even if the material is fully compliant, there is still a certain probability of occasional failures, with common responses such as voices_sound_different (voiceprint verification failed). Such failures are unrelated to audio quality, and retrying with the same material can usually succeed. It is recommended to implement 1~2 automatic retries for failed results during integration. Failed requests will not be charged.

curl -X POST 'https://api.worldai.chat/suno/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3",
  "name": "My Voice",
  "description": "单人清晰人声示例"
}'

The above https://cdn.acedata.cloud/suno_demo.mp3 is an example material that can be called directly (MP3, 41 seconds, single-person dry vocal). If you need a WAV format example, you can use https://cdn.acedata.cloud/uploads/82d23b97-ec1c-4b41-91b8-989fc51f8765 (WAV, 41 seconds, mono 44.1kHz).

The result is as follows:

{
  "success": true,
  "task_id": "0fa609a6-c8d9-4bb5-8574-e4c93bb55d02",
  "data": {
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16",
    "name": "VOICE_20260803037676",
    "is_public": false
  }
}

As you can see, the persona_id field in data is the created voice persona ID. The is_public field is always false, because voice personas created by uploading audio are private. Note that the returned name is automatically generated by the system; please use persona_id to reference this voice persona subsequently.

Step 2: Generate Music Using the Voice Persona

After obtaining the voice persona ID, we can use the Suno Audios Generation API for music generation. Set action to generate, and set persona_id to the voice persona ID returned above; the generated song will be sung using the cloned voice.

Note: Voice cloning only supports chirp-v4-5 and later models (such as chirp-v4-5, chirp-v5, and chirp-v5-5), and does not support chirp-v4.

curl -X POST 'https://api.worldai.chat/suno/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "chirp-v5-5",
  "prompt": "A warm synth-pop song about city nights",
  "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
}'

The result is as follows:

{
  "success": true,
  "task_id": "53d8a334-a972-43c5-895e-60c4454e88d5",
  "data": [
    {
      "id": "16463960-077c-4700-bbb3-3c7897b943d3",
      "title": "Soft Neon on My Skin",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "prompt": "A warm synth-pop song about city nights",
      "duration": 156.28
    }
  ]
}

persona_id can be used for generate generation and also for cover / upload_cover covers. There is no need to specify vocal_gender at the same time when specifying a voice; voice similarity still depends on the reference material and generation result.

Voices created through this interface are private resources. Before covering an existing song, first call /suno/upload, passing the original song's audio_url and the voice's persona_id; after a successful upload, call /suno/audios using the returned data.audio_id and the same persona_id:

{
  "action": "upload_cover",
  "model": "chirp-v6",
  "audio_id": "<audio_id returned after uploading in association with this voice>",
  "persona_id": "<persona_id returned by the voice creation API>",
  "custom": true,
  "instrumental": false,
  "lyric": "[Verse]\nEnter the lyrics to be sung",
  "async": true
}

Creating a voice, uploading the original song, and creating the cover must use the same service channel. Do not directly reuse a song ID that was not previously associated with this private voice; see Suno Upload Reference Audio for details.