> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno Voice Cloning API Integration Guide

> Suno Music Generation integration guide - Ace Data Cloud

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.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/suno-audios) 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`.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.