API di generazione in modalità personalizzata

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

Descrizione dell'endpoint

La modalità personalizzata serve quando hai già testo, stile e titolo pronti e vuoi controllare la voce che canta, la forza dell'influenza dello stile e il grado di casualità della generazione.

Endpoint: POST /api/music/create/custom

Fatturazione: A pagamento, attualmente 0,6 ¥ per chiamata per impostazione predefinita. Ogni chiamata restituisce di solito 2 brani; l'importo effettivamente addebitato segue la configurazione prezzi attuale del back-office.

Max Mode / Variety: questo endpoint supporta i parametri opzionali max_mode e variety (0-4). Con max_mode attivo, questa chiamata viene fatturata al doppio del prezzo (0,6 → 1,2 ¥ per chiamata); variety non costa nulla in più. Significato e modalità di invio sono nella sezione «Parametri avanzati» della Panoramica della nuova API.

Tempi di attesa e timeout (importante): è un endpoint sincrono — l'ordine viene accettato e passato alla generazione solo quando arriva la risposta. Dai dati misurati, la maggior parte delle richieste risponde in 1-3 secondi, circa il 10% supera i 30 secondi e la più lunga arriva a circa 230 secondi. Imposta il timeout del client a 300 secondi o più; nessuna risposta non significa che non sia stato generato nulla, e non ritentare subito dopo un timeout (duplica l'ordine e riaddebita). Se la connessione è caduta, verifica più tardi con GET /api/music/songs. Vedi «Tempi di attesa e impostazione del timeout» nella Panoramica della nuova API.

Parametri della richiesta

Headers

Parametri del body

Note sui parametri avanzati

Genere della voce vocal_gender

• Invia m o male per una voce maschile, f o female per una voce femminile.
• Il servizio normalizza male e female rispettivamente in m e f.
• Con instrumental=true nessun parametro di genere vocale viene inviato al servizio di generazione.

Influenza dello stile style_weight

Controlla con quanta forza il risultato segue style_tags. Più alto è il valore, più il risultato tende a seguire i tag di stile indicati.

Casualità weirdness_constraint

Controlla quanto il risultato varia e resta sperimentale. Valori alti danno di solito più variazione; valori bassi danno di solito un risultato più sicuro.

Entrambi i parametri numerici vanno da 0.0 a 1.0, e 0 è un valore esplicito valido. Solo omettere del tutto il campo significa «non specificato».

Quando li compili, ricorda che sono frazioni decimali, non numeri interi percentuali. Riferimento suggerito: da 0.0 a 0.3 è conservativo, da 0.4 a 0.6 è equilibrato, da 0.7 a 1.0 è più sperimentale; senza preferenze nette usa 0.5 oppure omettili. Esempio: weirdness_constraint: 0.5, mai 50 o 50%.

Con instrumental=true il risultato è strumentale, quindi testo e genere della voce non agiscono come in un brano cantato; se ti serve la voce, invia false o ometti il campo. I campi booleani devono usare true/false di JSON, non stringhe.

Esempio di richiesta in Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nLa notte scende sul mare\nuna brezza sfiora la finestra',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Brezza della sera sul mare',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Modalità ricevuta di accettazione (opzionale)

Questo endpoint supporta anche la modalità ricevuta di accettazione della API di generazione in modalità semplice: con "accept_mode": "async" nel body (o l'intestazione X-Accept-Mode: async), l'endpoint restituisce subito 202 e un numero di ricevuta, la generazione continua in background e segui il progresso con GET /api/music/requests/{request_id}.

Adatta a client che non devono tenere connessioni lunghe, o che non vogliono che un timeout venga letto come «non è stato generato nulla». Senza quel parametro il comportamento è esattamente quello di prima.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Brezza della sera sul mare",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

La forma della risposta e il metodo di polling sono nella sezione «Modalità ricevuta di accettazione» della API di generazione in modalità semplice.

Validazione dei parametri

Questi casi restituiscono HTTP 400 e il message dell'errore indica il campo non valido:

• style_weight o weirdness_constraint non è un numero.
• Un valore numerico è sotto 0.0 o sopra 1.0.
• vocal_gender non è uno tra m, f, male, female.

Limiti dei campi di testo

Anche questi campi restituiscono HTTP 400 se troppo lunghi, e non entrano mai in generazione né vengono pre-addebitati. Il conteggio è per carattere Unicode (un carattere han conta come 1) e include gli spazi iniziali e finali:

Il messaggio di errore ha la forma style_tags must not exceed 1000 characters; received 2772: la prima parola è il campo che ha sforato e la fine è il conteggio misurato, quindi su un 400 tagli con quei due numeri invece di provare campo per campo. Le convenzioni generali sono in «Limiti dei campi di testo» della Panoramica della nuova API.

Risposta

L'endpoint restituisce di solito un array con 2 brani. Una richiesta asincrona parte normalmente in pending; salva il song_id e leggi lo stato finale e l'indirizzo audio con la API di consultazione dei brani. I campi del brano sono gli stessi della API di generazione in modalità semplice.

Campi compatibili

Le nuove integrazioni dovrebbero usare snake_case ovunque. Se una stessa richiesta porta sia snake_case sia camelCase, prevale il valore in snake_case.