> ## 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 声音克隆 API 对接说明

> Suno Music Generation API guide - Ace Data Cloud

SUNO consente di creare ruoli vocali personalizzati tramite qualsiasi file audio, realizzando il cloning della voce per la generazione musicale. A differenza dell'API Persona esistente (che utilizza `audio_id` generato da Suno), questa API accetta un `audio_url` accessibile pubblicamente, ovvero la registrazione vocale di una persona. Questo documento spiega come integrare l'API di cloning della voce.

## Primo passo: Creare un ruolo vocale

Questa API ha tre parametri di input: `audio_url` (obbligatorio), che deve essere un URL di un file audio in formato MP3 o WAV accessibile pubblicamente, contenente una voce umana chiara; `name` e `description` (opzionali), che sono il nome e la descrizione del ruolo vocale.

> **Requisiti per il file audio**
>
> * Il formato audio deve essere `WAV` o `MP3`
> * La durata audio deve essere compresa tra `10~240 secondi`, si consiglia di utilizzare materiale vocale pulito di `30~60 secondi`
> * L'audio deve contenere **voce chiara e riconoscibile di una sola persona**
> * Evitare assolutamente **rumori di fondo, accompagnamenti, echi, riverberi**; canzoni complete con accompagnamento di solito non superano la verifica della voce
> * Non includere **più di un parlante** o **voci multiple**
> * Materiale con volume troppo basso, voce poco chiara o rumori eccessivi potrebbe causare **fallimento del cloning** o **risultati scadenti**
>   **Limitazioni d'uso**
> * I ruoli vocali creati tramite l'upload audio sono **risorse private**
> * Questo ruolo vocale **non supporta il riutilizzo tra account**
> * Si consiglia di utilizzarlo il prima possibile dopo la creazione, un lungo periodo di inattività potrebbe causare **scadenza o non disponibilità**
> * Il `name` restituito è generato automaticamente dal sistema, fare riferimento al `persona_id` restituito

> **In caso di fallimento della chiamata, riprovare**
> Il cloning della voce è un compito intensivo in termini di calcolo, anche se il materiale è completamente conforme, esiste una certa probabilità di fallimento occasionale, come il comune ritorno `voices_sound_different` (verifica della voce non superata). **Questi fallimenti non sono correlati alla qualità audio, riprovare con lo stesso materiale di solito porta al successo**,
> si consiglia di implementare 1-2 tentativi automatici in caso di risultati di fallimento. Le richieste fallite non verranno addebitate.

```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": "Esempio di voce chiara di una sola persona"
}'
```

> L'URL `https://cdn.acedata.cloud/suno_demo.mp3` è un materiale di esempio direttamente utilizzabile (MP3, 41 secondi, voce pulita di una sola persona).
> Per un esempio in formato `WAV`, è possibile utilizzare
> `https://cdn.acedata.cloud/uploads/82d23b97-ec1c-4b41-91b8-989fc51f8765` (WAV, 41 secondi, mono 44.1kHz).

Il risultato è il seguente:

```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
  }
}
```

Si può notare che il campo `persona_id` di `data` è l'ID del ruolo vocale creato. Il campo `is_public` è sempre `false`, poiché i ruoli vocali creati tramite l'upload audio sono privati. Si prega di notare che il `name` restituito è generato automaticamente dal sistema, utilizzare successivamente il `persona_id` per fare riferimento a questo ruolo vocale.

## Secondo passo: Utilizzare il ruolo vocale per generare musica

Una volta ottenuto l'ID del ruolo vocale, possiamo utilizzare l'[API di Generazione Audio di Suno](https://platform.acedata.cloud/documents/suno-audios) per generare musica. Impostare `action` su `generate` e `persona_id` sull'ID del ruolo vocale restituito sopra, la canzone generata utilizzerà la voce clonata per il canto.

> **Nota:** Il cloning della voce supporta solo modelli `chirp-v4-5` e superiori (come `chirp-v4-5`, `chirp-v5`, `chirp-v5-5`), non supporta `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": "Una calda canzone synth-pop sulle notti in città",
  "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
}'
```

Il risultato è il seguente:

```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://cdn1.suno.ai/16463960-077c-4700-bbb3-3c7897b943d3.mp3",
      "image_url": "https://cdn2.suno.ai/image_16463960-077c-4700-bbb3-3c7897b943d3.jpeg",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "prompt": "Una calda canzone synth-pop sulle notti in città",
      "duration": 156.28
    }
  ]
}
```

Si può notare che la canzone generata utilizza la voce clonata per il canto. Il `persona_id` può anche essere utilizzato con l'azione `cover` per reinterpretare canzoni esistenti con la voce clonata.