API di clonazione vocale e generazione con voce indicata (non consigliato)

Aggiornato il 2026-09-18 · team Suno-API

⛔ Catena precedente, non consigliata per le nuove integrazioni. Questa pagina descrive la catena persona iniziale (voice_task_id / generate-with-voice). Funziona ancora, ma non è più consigliata ai clienti; il menu di sinistra la segnala come «non consigliato».

Per le nuove integrazioni usa l'【Consigliato】 API profilo vocale: crea un profilo vocale da un campione di voce (POST /api/music/voice-profile/create) e usalo per fare una cover di un brano scelto o per cantarne uno nuovo. Il profilo vocale è una risorsa di prima classe: si può elencare, leggere ed eliminare, e il suo audio di origine viene conservato in modo permanente.

Se il tuo prodotto richiede il ciclo completo «creare una voce → riutilizzarla a lungo → fare cover», dai priorità alla catena nuova.

Avviso importante: una voce clonata può scadere.

Il voice_id / voice_task_id prodotto dalla clonazione vocale non è una risorsa utilizzabile per sempre: può smettere di funzionare per la durata di validità, lo stato dell'account o i cambiamenti dello stato della voce. Chi integra non deve clonare una volta e poi riutilizzare per sempre un ID voce salvato in cache locale.

Prassi consigliata:

• Salva voice_task_id, voice_id, is_available, updated_at e l'ora dell'ultima generazione riuscita.
• Prima di ogni generazione con una voce clonata, chiama GET /api/voice/clone/tasks/{voice_task_id} o POST /api/voice/clone/tasks/{voice_task_id}/check e verifica is_available=true.
• Se l'endpoint restituisce voce non disponibile, attività inesistente o selected voice is not ready, invita l'utente a clonare di nuovo o a scegliere un'altra voce disponibile.
• Non promettere all'utente finale che una voce clonata sia un «asset permanente»; mostra nell'interfaccia del prodotto che «la voce può scadere e richiedere una nuova verifica o una nuova clonazione».

Descrizione dell'endpoint

Questo gruppo di endpoint crea una voce riutilizzabile e genera brani con essa. Chi chiama ha bisogno solo della chiave API emessa dalla piattaforma; il server gestisce invio delle attività, sincronizzazione dello stato, fatturazione e download.

Autenticazione: Authorization: Bearer YOUR_API_KEY

Fatturazione:

• Verifica della voce, clonazione vocale, consultazione dello stato, eliminazione e download: gratuiti.
• L'ingresso di clonazione in un passo dell'area di lavoro: 5 ¥ fissi per chiamata; completa automaticamente la verifica della voce di origine e il secondo audio di verifica, e rimborsa in caso di errore.
• Proseguire automaticamente con l'audio di verifica dopo una clonazione normale: 5 ¥ fissi per chiamata; in caso di errore il rimborso segue il flusso esistente.
• Generare un brano con una voce clonata: a pagamento, 1,2 ¥ fissi per chiamata; ogni chiamata restituisce di norma 2 attività segnaposto.
• Con il Max Mode attivo (max_mode: true su POST /api/music/generate-with-voice) gli 1,2 ¥ per chiamata vengono fatturati al doppio, cioè 2,4 ¥ per chiamata; la generazione con voce supporta anche variety (0-4, senza costi aggiuntivi); le regole sui valori sono nella sezione «Parametri avanzati» della panoramica della nuova API.

Sequenza di chiamate

1. Chiama POST /api/voice/clone/validate per caricare la voce di origine e ottenere un voice_task_id.
2. Attendi o interroga GET /api/voice/clone/tasks/{voice_task_id} fino a ottenere validate_info.
3. L'utente legge quel testo ad alta voce e registra l'audio di verifica.
4. Chiama POST /api/voice/clone/tasks/{voice_task_id}/generate per inviare l'audio di verifica.
5. Chiama POST /api/voice/clone/tasks/{voice_task_id}/check o continua a interrogare l'attività finché is_available=true.
6. Chiama POST /api/music/generate-with-voice per generare un brano con quella voce.
7. L'endpoint di generazione restituisce prima attività segnaposto; quando la generazione è finita e hai il song_id reale, puoi usare gli endpoint di download per ottenere un singolo file o un pacchetto.
8. (Facoltativo) Quando la voce non serve più, chiama DELETE /api/voice/clone/voices/{voice_task_id} per eliminarla; la semantica è nella sezione 6.

Esiste anche la clonazione in un passo: nella prima pagina di registrazione/caricamento della voce dell'area di lavoro puoi scegliere di completare tutto in una volta; il sistema esegue insieme verifica e creazione della voce, così non devi registrare un secondo audio di verifica; costa 5 ¥ per chiamata e in caso di errore viene rimborsato.

Campi dell'attività voce

1. Inviare la voce di origine alla verifica

Endpoint: POST /api/voice/clone/validate

Parametri del corpo

vocal_end_s - vocal_start_s deve rispettare il minimo del frammento vocale. Carica una registrazione vocale pulita, senza accompagnamento o rumore evidenti.

Esempio di richiesta

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": "La mia voce femminile in cinese",
    "description": "Voce femminile in cinese, chiara e naturale",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Esempio di risposta

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "La mia voce femminile in cinese",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Interrogare un'attività voce

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

Esempio di richiesta

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

Esempio di risposta

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "La mia voce femminile in cinese",
      "validate_info": "Leggi ad alta voce il testo di verifica restituito qui",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Rigenerare il testo di verifica

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

Da chiamare quando il testo di verifica non è adatto alla lettura ad alta voce o quando serve rifare la verifica.

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. Inviare l'audio di verifica e creare la voce

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

Parametri del corpo

Esempio di richiesta

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": "La mia voce femminile in cinese"
  }'

5. Verificare se la voce è utilizzabile

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

Quando l'attività è utilizzabile, is_available nella risposta è true e viene restituito un voice_id.

6. Eliminare una voce

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

Fatturazione: gratuita.

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

Esempio di risposta

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

Cosa succede dopo l'eliminazione

• La voce non può più generare nuovi brani: chiamare POST /api/music/generate-with-voice con questo voice_task_id (o con il suo voice_id) viene rifiutato con il messaggio selected voice is not ready, senza alcun addebito.
• I brani già generati con essa non sono per nulla influenzati: riproduzione, download, proseguimento, sostituzione e separazione funzionano come prima.
• Questa attività voce scompare dalle interrogazioni: GET /api/voice/clone/tasks/{voice_task_id} restituisce record not found.
• L'audio di origine viene conservato secondo la politica di conservazione permanente della piattaforma (dal 2026-09-23 l'eliminazione non cancella più il campione vocale caricato), ma questo non significa che sia ripristinabile: quella vecchia attività è conclusa e, per continuare con la stessa voce, bisogna rifare tutto il flusso di clonazione, ottenendo un nuovo voice_task_id.
• Eliminazione ripetuta: eliminare di nuovo la stessa attività restituisce record not found (è già in stato eliminato e non è più consultabile).

7. Generare un brano con una voce clonata

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

Fatturazione: 1,2 ¥ per chiamata.

Parametri del corpo

Sono supportati suno-v6, suno-v6-wild e suno-v6-mini; un modello vuoto viene trattato come suno-v6. I vecchi modelli V5/V5.5 sono ritirati, ma le attività storiche possono ancora mostrare i nomi vecchi.

La struttura di richiesta condivisa interpreta anche campi di compatibilità Create UI come task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId e voiceId, ma non sono parametri client validi per questo endpoint: l'attività voce va inviata come voice_task_id, la verifica facoltativa della voce come voice_id, e la generazione musicale con voce non legge mai i campi sound.

Come compilare i parametri di generazione

• Con customMode=false prompt contiene la descrizione del brano; con customMode=true prompt contiene il testo completo e vanno compilati anche style e title. Non inviare il testo nel campo descrizione della modalità ispirazione e non trattare una descrizione del brano come testo della modalità avanzata.
• weirdnessConstraint e styleWeight sono proporzioni decimali da 0.0 a 1.0; non si possono inviare 50 o 50%. 0.5 è un valore equilibrato; ometterli significa «non specificato» e 0 è un valore esplicito valido.
• vocalGender accetta solo m, male, f o female. instrumental qui è solo un campo di compatibilità: la generazione con voce clonata è sempre trattata come brano cantato.
• waitAudio qui non cambia il comportamento; l'endpoint restituisce sempre le attività segnaposto in modo asincrono. Un audio_url vuoto nel risultato iniziale è normale: interroga con client_request_id e leggi l'indirizzo audio solo a risultato completato.

Parametri header

Comportamento di Idempotency-Key:

• La prima richiesta scrive un record di idempotenza persistente prima della fatturazione;
• Se la stessa chiave con la stessa richiesta è già completata, viene riprodotta la prima risposta di accettazione, senza secondo addebito né seconda attività;
• La stessa chiave con un corpo diverso viene rifiutata;
• La stessa chiave ancora in elaborazione restituisce un errore stabile «in elaborazione» ed espone un client_request_id sicuro solo quando è già stato generato;
• Se la prima richiesta con quella chiave fallisce, resta in stato di errore; per riprovare serve una chiave nuova.

Condizioni per la cover con sourceClipId

La cover da una sorgente nell'API client è gestita interamente dal server: l'accesso al brano di origine viene risolto lato server e il cliente non invia alcun dato di account. Se sia possibile lo decide la risposta reale dell'endpoint.

La sorgente deve appartenere all'utente API corrente, essere un brano dell'area di lavoro completato e non pending:, e avere audio utilizzabile. Sono supportate la generazione normale, le sorgenti da caricamento normale e il brano finale del caricamento potenziato; i record intermedi del caricamento potenziato vengono rifiutati prima della fatturazione. Il server accetta solo l'ID del brano di origine inviato dal cliente e mai un ID account; una sorgente non disponibile o non completata restituisce errore prima della fatturazione.

Esempio di richiesta

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": "Scrivi una canzone pop cinese su un litorale in una notte d'estate",
    "style": "Mandopop, warm piano, emotional",
    "title": "Brezza di mare in una notte d'estate",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Esempio di risposta

{
  "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": "Brezza di mare in una notte d'estate",
        "prompt": "Scrivi una canzone pop cinese su un litorale in una notte d'estate"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Brezza di mare in una notte d'estate",
        "prompt": "Scrivi una canzone pop cinese su un litorale in una notte d'estate"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Attività segnaposto e song_id finale

generate-with-voice è un endpoint di generazione asincrona. Una risposta riuscita significa solo che l'attività di generazione è stata inviata, non che il brano sia pronto.

Significato dei campi chiave della risposta:

Attenzione: un placeholder_id che inizia con pending: non può essere usato come song_id finale né passato a /api/music/query o agli endpoint di download. Chiamare /api/music/query solo con valori pending:* può restituire un array vuoto [], perché il brano reale non è ancora pronto o l'attività segnaposto non è ancora stata sostituita dall'ID finale.

Esempio errato:

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

Sequenza corretta:

1. Chiama POST /api/music/generate-with-voice per inviare l'attività di generazione con voce.
2. Salva client_request_id, items[].placeholder_id e items[].client_request_index dalla risposta.
3. Interroga in ciclo GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Quando items[].song_id ha un valore che non inizia con pending:, chiama /api/music/query, /api/music/download-file o /api/music/download-all.

La versione attuale aggiunge un endpoint pubblico di consultazione:

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

Restituisce i risultati delle attività con lo stesso client_request_id per l'utente corrente, così il cliente può recuperare da sé il song_id finale. Nell'elenco restituito:

• song_id è l'ID reale del brano;
• placeholder_id compare solo finché l'attività è in stato di segnaposto;
• un valore che inizia con pending: non può essere usato con /api/music/query né con gli endpoint di download.

Se hai salvato solo il client_request_id o un ID segnaposto pending:*, chiama prima questo endpoint dei risultati; se il song_id reale continua a non comparire, invia il client_request_id al supporto tecnico per la localizzazione.

Consultare i risultati della generazione con voce

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

Fatturazione: gratuita.

Parametri query

Esempio di richiesta

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"

Esempio di risposta in elaborazione

{
  "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": "Brezza di mare in una notte d'estate"
      }
    ]
  }
}

Esempio di risposta completata

{
  "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": "Brezza di mare in una notte d'estate",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Significato dello status di primo livello

8. Scaricare un singolo file

Endpoint: POST /api/music/download-file

Parametri del corpo

Esempio di richiesta

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

La risposta è un flusso di file; Content-Type e nome del file seguono ciò che restituisce il backend.

9. Scaricare le risorse del brano in un pacchetto

Endpoint: POST /api/music/download-all

Parametri del corpo

Esempio di richiesta

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

Il pacchetto contiene di norma l'audio, la copertina e metadata.json; se un tipo di risorsa non è ancora stato generato, non entra nell'archivio.

Errori comuni

Gli errori di questo gruppo restituiscono sempre HTTP 200: giudica l'esito dal campo success nel corpo (false indica fallimento, con il motivo in message) e non basarti solo sul codice di stato HTTP. La semantica completa dell'eliminazione di una voce (se resta utilizzabile, se è recuperabile) è nella sezione 6.