Suno Voice Cloning API Integration Guide

SUNO allows us to create custom voice personas from any audio file, enabling voice cloning for music generation. Unlike the existing Persona API (which uses a 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-format audio file URL containing clear vocals from a single person; and 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 solo dry vocal material of 30~60 seconds is recommended
• The audio should contain clear, identifiable speech or singing vocals from a single person
• Be sure to avoid background noise, accompaniment, echo, and reverb; complete songs with accompaniment usually cannot pass voiceprint verification
• Do not include multiple speakers or multiple vocal layers
• Material with excessively low volume, 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 rely on the returned persona_id

Please Retry First When a Call Fails Voice cloning is a computationally intensive task. Even if the material is fully compliant, there is 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 will 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.qiyaov.com/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 sample material that can be called directly (MP3, 41 seconds, solo dry vocals). For 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 going forward.

¶ Step 2: Use the Voice Persona to Generate Music

After obtaining the voice persona ID, we can use the Suno Audios Generation API to generate music. 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 supports only chirp-v4-5 and higher models (such as chirp-v4-5, chirp-v5, and chirp-v5-5), and does not support chirp-v4.

curl -X POST 'https://api.qiyaov.com/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
    }
  ]
}

As you can see, the generated song is sung using the cloned voice. persona_id can also be used with the cover action to create a cover of an existing song using the cloned voice.