【Consigliato】 API profilo vocale

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

✅ Catena consigliata per le nuove integrazioni. Secondo le valutazioni reali di molti utenti, i brani generati con questa catena conservano molto bene la voce originale: la voce nella traccia finale somiglia di più alla persona del campione che hai caricato, perciò è la via che consigliamo attualmente ai clienti.

Confronto: la precedente API di clonazione vocale e generazione con voce indicata funziona ancora, ma il menu la segnala come «non consigliato» e non è più consigliata per le nuove integrazioni.

• Data del documento: 2026-09-26
• Copertura: creare la propria voce → usarla per fare una cover di un brano scelto / cantare un brano nuovo → seguire l'avanzamento → scaricare i risultati
• Tutti gli endpoint, i campi e le risposte sono stati verificati con chiamate reali (i punti marcati «misurato» sono stati verificati nel dettaglio)

Nota: questo documento descrive solo gli endpoint che devi chiamare. Il trattamento dei materiali, la pianificazione delle attività e la validazione dei contenuti sono gestiti automaticamente dal server; il client non li implementa.

0. Pronti in cinque minuti

Bastano quattro passi per trasformare un campione vocale in due brani finiti.

① Creare la voce  POST /api/music/voice-profile/create      → ottenere voice_id (status=ready)
② Fare la cover   POST /api/music/voice-profile/cover       → ottenere subito 2 song_id
③ Seguire         POST /api/music/query                     → interrogare fino a status=completed
④ Scaricare       GET  /api/music/download?song_id=…&kind=mp3

Esempio minimo (curl):

API_KEY="sk-la-tua-chiave"
BASE="https://www.suno-api.io"

# ① Creare la voce (carica un campione vocale; 10 s o più consigliati, sotto 10 MB)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=La mia voce" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Fare una cover con questa voce (song_clip_id = il clip id del brano da coverare)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\ntesto del brano…",
        "style_requirements": "folk lento, chitarra acustica",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Interrogare (più id in una volta, separati da virgole)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Scaricare l'mp3 a fine lavorazione (solo con status=completed ottieni il file)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Convenzioni comuni

1.1 Dominio e ambiente

Tutti i percorsi seguenti sono relativi alla Base URL; per esempio l'indirizzo completo di POST /api/music/voice-profile/create è https://www.suno-api.io/api/music/voice-profile/create.

1.2 Autenticazione

Tutti gli endpoint usano lo stesso header di richiesta, il cui valore è la chiave API che hai creato nella console:

Authorization: Bearer sk-xxxxxxxx

• Il prefisso Bearer è facoltativo; anche quello sk- (Authorization: sk-xxx funziona allo stesso modo).
• Chiave assente o non valida → HTTP 401, con un corpo come {"success":false,"message":"…"} (il testo varia con la lingua della richiesta).
• Ogni chiave può vedere e può agire solo sui brani e sulle voci del proprio account.

1.3 Formati del corpo della richiesta

• Creazione della voce: si consiglia multipart/form-data (caricamento di un file); è supportato anche application/json (un URL o base64).
• Tutti gli altri endpoint: application/json.

1.4 Due involucri di risposta (il cliente deve conoscere solo questi due)

Gli endpoint di «gestione delle voci» (create / create-from-clip / list / detail / delete) usano l'involucro di business:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

La «cover con voce» passa per il canale di generazione e usa l'involucro di generazione: il successo è code/message/data, il fallimento è un oggetto error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Come decidere: guarda prima il codice di stato HTTP, poi success === false, infine code !== 200 o la presenza di error. Un fallimento di business non garantisce un HTTP diverso da 200 (gli endpoint di gestione delle voci restituiscono comunque HTTP 200 in caso di errore), quindi non puoi basarti solo sul codice di stato.

1.5 Idempotenza

La creazione di una voce (incluso «creare da audio esistente») è realmente idempotente: sotto la stessa chiave, inviare di nuovo lo stesso client_request_id crea una sola voce e il secondo tentativo restituisce direttamente il primo risultato (success=true, lo stesso voice_id). L'uso previsto è che il client generi da sé un id (un UUID, per esempio) e riutilizzi lo stesso valore quando riprova dopo un timeout.

L'invio di una cover non deduplica a livello di richiesta (è una generazione fatturata), quindi tieni presente due cose:

1. L'identificatore di invio va nell'header X-Create-Ui-Client-Request-Id: <il tuo id di invio>. Viene scritto nel record di attività lato server per facilitare le indagini successive; non impedisce un addebito duplicato.
2. Timeout ≠ fallimento: la richiesta potrebbe essere già stata accettata e in generazione. Prima di riprovare, controlla con GET /api/music/songs?p=1&page_size=20 (i parametri di paginazione sono p / page_size; la grafia compatibile ps funziona pure) se è già comparso un brano nuovo con generation_type=voice_profile_cover, e re-invia la stessa richiesta solo se non c'è.

I corpi di create e create-from-clip accettano anch'essi un campo client_request_id (vedi §3 e §4).

1.6 Panoramica della fatturazione

I prezzi si leggono in qualsiasi momento da un endpoint pubblico, quindi non fissarli nel codice (vedi §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← prezzo base di una cover con voce
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← prezzo della clonazione potenziata
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

La cover usa addebito anticipato + rimborso in caso di errore:

• Una richiesta rifiutata (parametri errati, un 4xx/5xx della piattaforma, saldo insufficiente in sé) non viene addebitata: inviando con una voce inesistente il saldo è rimasto del tutto invariato nelle nostre misure (delta = 0);
• Un'attività accettata che alla fine fallisce (compreso un errore di servizio della piattaforma) passa per la via di rimborso del server e restituisce l'importo anticipato.

1.7 Dizionario degli stati

Lo status della voce:

Lo status del brano (il valore restituito dagli endpoint di interrogazione):

2. Panoramica degli endpoint

3. Creare una voce

POST /api/music/voice-profile/create

Registra un frammento di audio vocale come «voce» e ottieni un voice_id. Per la piattaforma una voce è semplicemente «un audio + il suo clip nel catalogo», quindi dopo la creazione riuscita quell'audio di origine viene conservato per sempre (per le cover successive).

3.1 Tre forme di input (scegline una)

Forma A: caricamento file multipart (consigliata)

Content-Type: multipart/form-data

file=<binario audio>         # obbligatorio
title=<nome della voce>      # facoltativo; se vuoto, il nome del file senza estensione
file_name=<nome file originale>
source_file_name=<nome file originale>
source_kind=upload|record    # facoltativo, marcatore di origine (caricamento / registrazione); predefinito upload
enhanced=false|true          # facoltativo, true = clonazione potenziata (vedi §3.5)
client_request_id=<chiave di idempotenza>   # facoltativo
voice_id=<ID personalizzato> # facoltativo, raramente usato

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=La mia voce" \
  -F "source_kind=upload"

Forma B: JSON + un URL audio pubblico

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "La mia voce"
      }'

• L'URL deve essere un link diretto HTTPS raggiungibile pubblicamente; il server lo scarica una volta e lo deposita nel nostro object storage.
• Puoi mettere l'indirizzo anche nel campo audio_url, l'effetto è identico (se invii entrambi vince file_url).
• Se l'indirizzo è già sull'object storage di questa piattaforma (*.myqcloud.com/create-ui/voice-source/...) non viene riscaricato: viene registrato direttamente.

Forma C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "La mia voce"
}

• Sono accettati sia il prefisso data:audio/xxx;base64, sia il base64 puro.
• La dimensione è limitata (il base64 gonfia di 1,33×), quindi per i file grandi usa la forma A.

3.2 Requisiti dell'audio

3.3 Risposta

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "La mia voce",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Riferimento dei campi (create / list / detail condividono lo stesso insieme):

created_at / updated_at sono timestamp in secondi (10 cifre), non in millisecondi.

3.4 Errori comuni

3.5 Clonazione potenziata (enhanced=true)

Per i casi in cui «il campione vocale stesso contiene testi protetti / serve un caricamento potenziato». Fatturata al prezzo del caricamento potenziato (10 ¥ per chiamata per impostazione predefinita, rimborso automatico in caso di errore):

• La risposta è subito status=processing + task_id (ancora senza clip_id) e l'esecuzione è asincrona;
• Durante l'elaborazione usa GET /api/music/voice-profile/{voice_id} per l'avanzamento, che restituisce progress_percent / progress_stage / progress_message;
• Al termine status diventa ready e clip_id, audio_url, image_url vengono completati;
• In caso di errore status=failed e error_message dice qualcosa come «il caricamento potenziato non è riuscito; l'importo è stato rimborsato automaticamente, riprova più tardi»;
• Una clonazione potenziata richiede molto più tempo di una creazione standard (minuti), quindi non attenderla con un timeout sincrono.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=La mia voce" -F "enhanced=true"

4. Creare una voce da audio esistente

Se preferisci non ricaricare: copia direttamente in voce un audio che hai già caricato o già generato. Gratuito e idempotente.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: il clip id di un audio finito del tuo account (equivale alla song_id del brano).
• Reinviare lo stesso clip non crea un nuovo record: restituisce direttamente la voce esistente con reused: true (misurato).

La risposta è composta da tutti i campi di §3.3 più due campi in sola lettura:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Errori (il message così com'è restituito; si consiglia di mostrarlo o localizzarlo):

5. Elenco / dettaglio / eliminazione delle voci

5.1 Elenco

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "La mia voce", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

I campi sono esattamente quelli di §3.3. Per impostazione predefinita le voci eliminate non vengono restituite.

5.2 Dettaglio

GET /api/music/voice-profile/{voice_id}

Restituisce un singolo oggetto voce (data è l'oggetto stesso, non un array). Mentre una clonazione potenziata è in corso, aggiunge:

5.3 Eliminazione

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Dopo l'eliminazione la voce sparisce dall'elenco e non può più essere usata per nuove cover: inviando con quel voice_id si ottiene 400 (vedi §6.4).
• I brani già generati con essa non sono minimamente influenzati; riproduzione, download, prosecuzione, sostituzione e separazione funzionano come prima.
• Eliminare una voce inesistente, o che non appartiene a questo account, restituisce {"success":false,"message":"voice not found"}.

6. Fare una cover con una voce (l'endpoint centrale)

POST /api/music/voice-profile/cover
Content-Type: application/json

Un invio genera 2 brani (come la generazione normale).

6.1 Due scenari

Il resolved_scene della risposta restituisce cover o sing, così puoi confermare quale percorso è stato seguito.

6.2 Campi della richiesta

Si consiglia di inviare anche l'header X-Create-Ui-Client-Request-Id: <lo stesso id di invio>: solo quello viene scritto nel record di attività lato server e serve da chiave per le indagini successive (vedi §1.5).

Unità da tenere d'occhio: audio_weight / style_weight / weirdness_constraint sono decimali da 0 a 1, variety è un intero da 0 a 4 e duration è in secondi. Confonderli porta a rifiuti o risultati strani.

Il testo è facoltativo nello scenario B (il modello si arrangia), ma invia sempre lyrics quando un contenuto preciso deve essere cantato.

6.3 Risposta

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Attività] Questa è una cover. … (la parte strutturale fissa del server + i tuoi requisiti di cover / stile)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Punti chiave:

1. Identifica i brani finiti con clips[].song_id (questo endpoint non restituisce un campo id).
2. Ottieni subito 2 valori song_id, mentre status è ancora processing (significa solo che sono stati accettati) e audio_url è vuoto; devi interrogare fino a completed prima di scaricare. play_url è il flusso di ascolto della piattaforma, può già comparire all'invio e scadrà.
3. description è il prompt che il server invia alla fine (la parte strutturale fissa + i cover_requirements / style_requirements che hai inserito); è molto utile quando si indaga su un risultato.
4. source_updates è il risultato del trattamento dei materiali del server e il client può ignorarlo.
5. Il title che invii viene scritto nel record di attività lato server e compare come song_title nelle interrogazioni successive; che clips[].song_title sia vuoto nella risposta di invio è normale.

6.4 Errori

{ "error": { "message": "questa voce non esiste o è stata eliminata (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Un saldo insufficiente restituisce un errore di fatturazione già all'invio e non lascia mai attività a metà.

6.5 Modelli disponibili (nomi per il cliente)

Usa i nomi modello per il cliente (quelli sopra). chirp-* sono nomi interni della piattaforma e non vanno usati direttamente.

7. Seguire l'avanzamento

7.1 Interrogazione in blocco (consigliata)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids è una stringa separata da virgole (non un array).
• La risposta è un array nudo (direttamente [...], senza involucro success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "Due tigri",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Attività] Questa è una cover. … (il prompt finale del server)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Consiglio sull'interrogazione: ogni 5–10 secondi, con timeout totale di 10–15 minuti (l'account freddo più lento misurato ha impiegato circa 4 minuti e mezzo; pochissimi di più). Non giudicare la fine dal fatto che audio_url sia vuoto: usa status.

Nota di compatibilità: questo endpoint identifica i brani con song_id; in alcune risposte iniziali comparve un campo id, quindi row.song_id || row.id è la lettura sicura.

7.2 Dettaglio di un brano

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Due tigri",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Due tigri",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Qui created_at / completed_at sono secondi Unix (a differenza delle stringhe ISO dell'interrogazione in blocco, quindi i client devono distinguerli).
• wav_url / video_url sono le entrate di download di questa piattaforma (relative al dominio corrente) e un GET recupera il file; sono stringhe vuote quando la piattaforma non ha prodotto quel materiale.
• parameter_retention indica a quali parametri di invio quel brano è riconducibile: core_parameters_available=true significa che i parametri principali (testo / stile / origine) sono interrogabili, mentre con extended_parameters_available=false i parametri estesi elencati sopra non sono stati conservati (le cover con voce rientrano attualmente in questa categoria).

7.3 I miei lavori

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=parola chiave

Parametri di paginazione: p (numero di pagina, da 1) / page_size (elementi per pagina; ps è una grafia compatibile). Facoltativi status e q (una parola chiave del titolo). Per impostazione predefinita ordinati per data di creazione decrescente.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Due tigri",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Con generation_type=voice_profile_cover distingui «i brani prodotti da una cover con voce» dagli altri risultati di generazione.

8. Scaricare i brani finiti

8.1 Prendere l'mp3 direttamente (consigliato, gratuito)

Vanno bene tutte e tre; scegline una:

1. Usare l'audio_url del risultato dell'interrogazione (un link diretto all'object storage, il più comodo).
2. GET /api/music/download?song_id=<id>&kind=mp3 → restituisce direttamente il flusso di byte audio (con il nome del file già in Content-Disposition).
3. POST /api/music/download-url (per ottenere un indirizzo temporaneo firmato).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Valori di kind: mp3 (equivalente a song) / playback (riproduzione in streaming) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) è al momento disponibile solo per alcuni brani; se fallisce, genera il file tu stesso con l'API dei testi con timestamp. La risposta è il flusso di byte del file, con Content-Type e Content-Disposition (nome file) già impostati; i wav_url / video_url restituiti da GET /api/music/songs/{song_id} sono la stessa entrata con kind=wav|video.

8.2 Convertire in wav / ottenere testi / metadati (a pagamento)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files accetta: mp3 / wav / lyrics / metadata, fino a 10 brani alla volta.
• Fatturato per brano riuscito (0,2 ¥ ciascuno); un brano completamente fallito non viene addebitato, e un formato fallito compare solo in songs[].errors.
• Per riottenere file già scaricati in precedenza, usa prima il gratuito POST /api/music/free2/cached (gli stessi song_ids + files) per ottenere indirizzi archiviati; il suo songs[].missing_files elenca i formati non in cache da preparare di nuovo.

9. Consultare i prezzi

GET /api/pricing/catalog

Un endpoint pubblico che non richiede autenticazione. Tutti i prezzi unitari che il cliente deve mostrare sono in data.catalog.meta (stringhe):

I prezzi vengono regolati nel back-office, quindi leggili in tempo reale invece di fissarli nel client. L'addebito effettivo della cover = voice_generation_price × (con max_mode vero, ancora × max_mode_factor).

10. Limiti e avvertenze

1. Dimensione del caricamento: ≤ 10 MB (il server ne accetta di più, ma il gateway d'ingresso tronca i corpi sovradimensionati a 10 MiB, cosa che si manifesta come «rifiutato da Suno»; bloccalo prima dal tuo lato).
2. Durata del campione: almeno 6 s, 10–60 s consigliati; troppo corto e la piattaforma rifiuta.
3. Contenuto del campione: voce pulita; evita qualsiasi cosa molto simile a una registrazione esistente (il confronto con il catalogo la rifiuta).
4. Limiti di testo: lyrics ≤ 3000 caratteri; per style_requirements / negative_tags / title si consigliano 1000 / 1000 / 100 caratteri (i requisiti di stile e di cover vengono concatenati al prompt, tieni il totale entro 3000 caratteri).
5. I testi non vengono riscritti: si canta quello che passi (carattere per carattere), senza troncamenti locali.
6. Ogni brano produce 2 tracce; non dare per scontato un solo risultato.
7. L'audio di origine è conservato per sempre: eliminare una voce non ripulisce il suo audio di origine; così restano possibili le cover successive e tracciabile la conformità.
8. La voce deve essere pronta: una voce in processing non può essere usata per le cover.
9. Timeout della richiesta: su un account freddo il primo invio nelle misure ha richiesto fino a circa 4 minuti e mezzo, quindi imposta il timeout del client a ≥ 6 minuti. Le cover non deduplicano a livello di richiesta, quindi dopo un timeout controlla se è già comparso un brano nuovo (§1.5) prima di decidere di rinviare.
10. Proprietà della voce: le voci appartengono a chi le crea; una cover accetta solo voci pronte e non eliminate. Una voce inesistente, eliminata o di un altro account restituisce 400: questa voce non esiste o è stata eliminata (voice_id=…).

11. Domande frequenti (FAQ)

D1. Creare una voce costa? La creazione standard e «creare da audio esistente» sono gratuite; si fatturano solo le cover (1,2 ¥ / MAX 2,4 ¥) e le clonazioni potenziate (10 ¥ per impostazione predefinita).

D2. Posso usare come campione un brano finito con accompagnamento? Sconsigliato. Qualsiasi cosa con musica, o molto simile a una registrazione esistente nel catalogo, viene rifiutata dalla piattaforma (This audio matches an existing recording in our catalog.). Usa una registrazione puramente vocale e asciutta.

D3. Perché audio_url è vuoto dopo l'invio di una cover? L'invio significa solo che è stata accettata e status è ancora processing. Un indirizzo riproducibile/scaricabile compare solo dopo aver interrogato /api/music/query fino a status=completed.

D4. Nello scenario B (senza song_clip_id) devo inviare il testo? Facoltativo. Invia lyrics per cantare un contenuto preciso; senza, il modello si arrangia, ma con meno controllo.

D5. Un audio caricato dal cliente può essere usato direttamente come voce? Sì: tramite la forma file_url di create, oppure caricandolo prima come brano e poi chiamando create-from-clip.

D6. In caso di errore i soldi vengono rimborsati? Una richiesta respinta di netto (parametri errati / errore della piattaforma) non viene addebitata, secondo le misure; un'attività accettata che alla fine fallisce restituisce l'importo anticipato. In caso di fallimento definitivo l'attività riporta status=failed più error_message.

D7. Dopo aver eliminato una voce, posso ancora ascoltare i brani generati prima con essa? Sì. L'eliminazione influisce solo sulla possibilità di usare quella voce per cover nuove.

D8. Quanto lungo può essere un brano da coverare in una volta? duration accetta da 1 a 480 secondi; se lo ometti decide la piattaforma in base all'originale / al materiale. Attenzione: le tracce finite della piattaforma sono lunghe almeno circa 30 secondi; con un valore più piccolo le misure davano comunque 29,96 / 29,76 secondi.

Appendice A: esempio completo (Node.js, con interrogazione e download)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Creare la voce (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Cover
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "folk lento, chitarra acustica",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Interrogare fino al completamento (ogni 5 secondi, massimo 15 minuti)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // array nudo
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Download
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "La mia voce");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\ntesto…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Appendice B: registro delle modifiche