API di generazione parlato (Speech)

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

Descrizione dell'endpoint

Speech trasforma un testo di discorso o una descrizione di una riga in audio di "parlato/discorso", con musica di sottofondo opzionale. È adatto a discorsi, brindisi, narrazioni, testi di voce fuori campo, contenuti audio e scenari simili.

Attenzione: questo endpoint genera audio parlato, non un brano cantato (nessuna melodia e nessuna voce cantata). Se ti serve il canto, usa l'API di generazione in modalità semplice o l'API di generazione in modalità personalizzata.

Endpoint: POST /api/music/speech

Fatturazione: A pagamento, attualmente 0,6 ¥ per chiamata per impostazione predefinita. Ogni chiamata restituisce di solito 2 audio; l'importo effettivamente addebitato segue la configurazione prezzi 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 pochi secondi (1-10 s); ma, come gli altri endpoint di generazione sincroni, in casi estremi può richiedere più tempo. 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.

Conformità dei contenuti: la piattaforma verifica il testo per diritto d'autore e policy sui contenuti. Se viene giudicato come materiale protetto (per esempio citare il testo di una canzone altrui o il testo letterale di un'opera nota), questa chiamata fallisce e l'importo viene rimborsato per intero automaticamente. Passa a una tua formulazione, o trasforma la citazione in una parafrasi, e riprova.

Parametri della richiesta

Headers

Parametri del body

Questo endpoint non supporta duration: inviarlo restituisce HTTP 400, non viene ignorato in silenzio. La durata del discorso è determinata dalla lunghezza del contenuto di script.

Esempi di richiesta

Richiesta minima (solo il testo)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Buongiorno a tutti! Oggi il mio intervento riguarda come usare bene il nostro tempo e andare avanti."
  }'

Richiesta completa (con tono, genere e musica di sottofondo disattivata)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Esempio in Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Buon pomeriggio, colleghi. Vi aggiorno sullo stato di avanzamento di questa settimana.',
        'tone': 'pacato e chiaro, resoconto di riunione',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # di solito 2 elementi
for item in items:
    print(item['song_id'], item['status'])

Note sui parametri

script (il discorso, obbligatorio)

• Incolla il contenuto che vuoi dire; puoi anche scrivere solo una descrizione e lasciare che il modello scriva il discorso (per esempio "un discorso di incoraggiamento a metà partita per una squadra sotto di venti punti, dal sussurro al ruggito a pieni polmoni").
• Interruzioni di riga, paragrafi e indicazioni sceniche come [pausa] si possono scrivere direttamente e il modello le seguirà per quanto possibile.
• Il limite è di 3000 caratteri (contati come caratteri Unicode; un ideogramma cinese conta 1); oltre il limite restituisce 400 e non addebita nulla.

tone (tono e contesto, opzionale)

Descrive come parlare, non cosa dire. Conviene includere quattro tipi di informazione: tono, ritmo/velocità, emozione e contesto.

Energico e potente, ritmo da lento ad accelerato, pause nette; aula magna, davanti a tutti gli studenti
Caldo e morbido, ritmo disteso; ricevimento di nozze
Pacato e misurato, ritmo costante e chiaro; relazione al consiglio

Il limite è di 1000 caratteri. Se non lo invii, il modello lo deduce dal contenuto di script.

gender / vocal_gender (genere di chi parla, opzionale)

• Per una voce maschile invia m o male, per una femminile f o female; il server li normalizza in m / f.
• Entrambi i nomi di campo funzionano; usane uno solo: gender è la forma consigliata per questo endpoint; se usi già la modalità personalizzata, puoi continuare con vocal_gender.
• Non inviarlo significa "indifferente", e decide il modello.

backing_music (musica di sottofondo, opzionale)

• Il valore predefinito è true (con musica di sottofondo), come nella versione web di Suno.
• false dà un discorso con la sola voce, comodo se poi vuoi aggiungere una tua traccia o un doppiaggio.
• Deve essere un booleano JSON true / false; le stringhe "true" e "1" sono accettate, ma si consigliano i booleani.

model (modello, opzionale)

Tutti e tre i modelli lato cliente sono disponibili allo stesso prezzo (0,6 ¥ per chiamata). Il discorso è generato dalla famiglia Suno v6; se omesso viene trattato come suno-v6. Salvo preferenze precise, di solito non serve inviare questo campo.

Validazione dei parametri e limiti di testo

I casi seguenti restituiscono HTTP 400 e tutti vengono bloccati prima dell'addebito, quindi non generano alcun costo:

Limiti dei campi di testo

Anche il superamento restituisce HTTP 400 e non avvia la generazione né effettua pre-addebiti. Il conteggio è in caratteri Unicode (un ideogramma cinese conta 1) e include gli spazi iniziali e finali:

L'errore ha la forma script must not exceed 3000 characters; received 4120: la prima parola è il campo che ha superato il limite e il finale è il conteggio reale, quindi con un 400 puoi tagliare direttamente con quei due numeri.

Risposta

La risposta è un array di brani esattamente come quello degli altri endpoint di generazione (di solito 2 elementi); salva il song_id e usa l' API di consultazione e cronologia dei brani per vedere lo stato finale e l'indirizzo audio:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Usare bene il tempo",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Fallimento della generazione e rimborsi

Se la generazione fallisce, l'addebito di quella chiamata viene rimborsato per intero automaticamente; non serve contattare l'assistenza. Il motivo si vede nella risposta o nel error_message dell'API di consultazione e cronologia dei brani.

Il fallimento più comune è il giudizio della piattaforma che il contenuto comprenda materiale protetto, per esempio:

Your lyrics contain copyrighted material. Please change it and try again.

In quel caso sostituisci il testo con una tua formulazione (o trasforma la citazione in parafrasi) e invialo di nuovo.

Domande frequenti

D: Perché il risultato è "parlato" e non canto? R: Questo è l'endpoint dei discorsi e l'output è audio parlato. Per cantare usa gli endpoint di generazione o della modalità personalizzata.

D: Perché restituisce 2 elementi ogni volta? R: Come gli altri endpoint di generazione della piattaforma, una generazione produce 2 candidati; consultali separatamente per song_id e tieni quello che preferisci.

D: Come controllo la durata? R: È determinata dalla lunghezza di script; questo endpoint non accetta il parametro duration.

D: Posso indicare una voce (per esempio la mia voce clonata)? R: La versione attuale non lo consente. Il discorso usa un insieme fisso di voci e gender sceglie maschile o femminile; se ti serve la tua voce, usa la funzione corrispondente dell'API di creazione profilo vocale (consigliato).

D: Cosa succede se non invio tone? R: Il modello deduce tono e ritmo dal contenuto di script. Per riprodurre uno stile in modo stabile, scrivi tono, velocità e contesto in tone.

Campi compatibili

Nelle nuove integrazioni usa snake_case in modo coerente. Gli altri campi (script, tone, song_title, backing_music) non hanno alias in camelCase.

Passi successivi

Una volta ottenuto il song_id:

1. Usa l'API di consultazione e cronologia dei brani per vedere lo stato di generazione e l'indirizzo audio;
2. Al termine, usa l'API di download e anteprima dei media dei brani per scaricarlo o ascoltarlo;
3. Per download in blocco o per copiarlo nel tuo storage, vedi gli endpoint del centro download.