Guida all'uso
Guida all'uso di ElevenLabs Text to Dialogue: inviare l'audio di un dialogo a due voci tramite l'array dialogue
Dalla suddivisione del copione a due personaggi alle richieste di voce per singola battuta, invio e validazione secondo il contratto attuale di HiAPI
In questa pagina
Per prima cosa verifica che tu debba risolvere una sintesi dialogica e non una lettura a segmento singolo
Se il tuo materiale è un copione di dialogo a due voci (o con più personaggi), la soluzione più immediata è spesso sintetizzare ogni battuta separatamente e poi concatenarle in ordine. I problemi di questo approccio emergono solo in fase di consegna: ogni battuta è un audio indipendente, le pause tra le frasi, la continuità del ritmo e la coerenza del timbro vanno integrate a mano nel livello di concatenazione; con molti personaggi, l'ordine di concatenazione e l'abbinamento errato dei timbri diventano la principale fonte di bug.
elevenlabs/text-to-dialogue è pensato per esprimere un intero dialogo con una sola richiesta. Suddividi l'intero copione in un array dialogue e invialo: il modello realizza il dialogo multi-voce nella stessa generazione e restituisce un unico audio completo. Rispetto a «più sintesi a segmento singolo + concatenazione», la mappatura dei personaggi e l'ordine delle battute sono racchiusi nel corpo della richiesta, e in fase di validazione devi controllare solo un risultato.
Fai quindi prima una valutazione:
- se il contenuto è la lettura continua dello stesso parlante, basta la sintesi vocale da testo e non serve l'array
dialogue; - se il contenuto è un dialogo alternato tra due o più personaggi e desideri un ascolto complessivamente uniforme, usa l'array
dialoguedi questa interfaccia; - se il contenuto è un dialogo ma il totale dei caratteri supera di molto il limite, occorre suddividerlo in segmenti per semantica e inviarli separatamente, non tornare alla sintesi battuta per battuta.
Dopo aver stabilito che rientra nella seconda categoria, il passo successivo è chiarire la struttura dell'array stesso.

La struttura dell'array dialogue: text e voice per ogni riga
Nel contratto di HiAPI, l'input di elevenlabs/text-to-dialogue ha un solo campo obbligatorio come nucleo: dialogue. È un array, minimo 1 elemento, e ogni elemento è una riga di dialogo con due sotto-campi obbligatori:
text: il testo della battuta di quella riga, stringa, minimo 1 carattere;voice: la voce usata per quella riga, stringa, può contenere il nome di una voce predefinita o unvoice_id, valore predefinitoEkK5I93UQWFDigLMpZcX.
Entrambi i campi sono obbligatori: anche se vuoi usare solo la voce predefinita, è consigliabile scrivere esplicitamente voice, così il corpo della richiesta si spiega da solo. Una richiesta minima per due personaggi ha questa forma:
{
"dialogue": [
{ "text": "Come sta procedendo il lavoro da te?", "voice": "EkK5I93UQWFDigLMpZcX" },
{ "text": "Questa settimana riusciamo a produrre la prima versione.", "voice": "Z3R5wn05IrDiVCyEkUrK" },
{ "text": "Bene, allora ti mando subito la checklist di validazione.", "voice": "EkK5I93UQWFDigLMpZcX" }
]
}
Nota che l'ordine dell'array è l'ordine del dialogo: l'interfaccia non ha un campo aggiuntivo per il «parlante», i personaggi si distinguono esclusivamente tramite voice. Questo è l'aspetto da progettare in anticipo in tutto il processo di integrazione.

Suddividere il copione a due personaggi in voci per battuta
Dal testo del copione all'array dialogue, è consigliabile seguire una pipeline fissa per evitare errori nella scrittura manuale del JSON.
Primo passo: suddivisione per riga e indicazione del parlante
Organizza il copione in una struttura a coppie «parlante + battuta», una battuta per voce, senza unire le battute di due personaggi nello stesso text: in quel caso un elemento può avere un solo voice e dopo l'unione non è più possibile distinguere i personaggi. Le didascalie, le note di scena tra parentesi non sono battute e vanno rimosse separatamente, senza inserirle in text.
Secondo passo: pulizia del testo
Controlla ogni voce: rimuovi gli spazi iniziali e finali, uniforma punteggiatura e a capo, elimina le righe vuote. La lunghezza minima di text è 1 carattere e una stringa vuota fa scattare direttamente un errore di validazione. Se una riga contiene solo interiezioni (come «mh» o «sì»), puoi tenerla; ma se dopo la pulizia diventa una stringa vuota, occorre confermare con chi gestisce i contenuti se eliminare quella riga.
Terzo passo: creare la mappatura dei personaggi e generare l'array
Ogni etichetta di parlante viene mappata a un'unica voce, quindi si generano gli elementi nell'ordine delle righe. Lo pseudocodice è più o meno questo:
speaker_voice = {
"A": "EkK5I93UQWFDigLMpZcX",
"B": "Z3R5wn05IrDiVCyEkUrK",
}
dialogue = [
{"text": line.text, "voice": speaker_voice[line.speaker]}
for line in script
]
Errori comuni
- lo stesso personaggio usa voci diverse in due punti, con una netta frattura nell'ascolto;
- l'omissione di
voicefa ricadere l'intero segmento sulla voce predefinita e il dialogo a due voci diventa «una persona che interpreta due ruoli»; - l'ordine dell'array viene alterato da logiche di ordinamento o deduplicazione, spezzando la semantica del dialogo.
Dopo la generazione, stampa le prime voci e controllale manualmente, poi passa al controllo del budget di caratteri.
Mappatura fissa delle voci: un solo voice per lo stesso personaggio
Il motivo per cui voice deve essere «fisso» è che determina sia il timbro stesso sia la semantica di «chi sta parlando». Se lo stesso personaggio presenta due valori voice diversi nell'intero dialogo, gli ascoltatori penseranno a un cambio di persona; al contrario, se due personaggi finiscono sullo stesso voice, il dialogo perde capacità di distinzione.
In pratica è consigliabile mantenere nel codice una tabella di mappatura costante da personaggio a voce, invece di spargere stringhe letterali in ogni battuta:
const VOICE = {
host: "EkK5I93UQWFDigLMpZcX",
guest: "Z3R5wn05IrDiVCyEkUrK",
};
Tutte le righe prendono il valore solo da questa tabella, e cambi di riga o riordini nello script non compromettono la coerenza. voice accetta il nome di una voce predefinita o un voice_id; se il team ha già un proprio sistema di denominazione delle voci, puoi fare una conversione a livello di configurazione e uniformare al momento della richiesta a un valore accettato dall'interfaccia. Il contratto fornisce l'enumerazione delle voci: validarla una volta prima dell'invio blocca problemi banali come errori di battitura; i valori fuori dall'enumerazione non vengono trattati silenziosamente come valore predefinito.
Un altro punto spesso trascurato è la stabilità tra segmenti. Quando il totale dei caratteri supera il limite e occorre suddividere in più richieste, la tabella di mappatura delle voci va riutilizzata così com'è, senza scegliere nuove voci nelle nuove richieste, altrimenti lo stesso personaggio suona diverso in segmenti diversi.

Budget di caratteri e suddivisione delle richieste
L'interfaccia impone un vincolo rigido sulla dimensione: il totale dei caratteri di tutti i campi text nell'array dialogue non deve superare 5000. Attenzione: è la somma di tutto il testo nell'array, non la lunghezza di una singola riga né il numero di elementi. Cinese, inglese e punteggiatura di solito contano come caratteri; in fase di stima conviene lasciare margine secondo il criterio più ampio.
Il conteggio va inserito dopo la generazione dell'array e prima dell'invio della richiesta:
total = sum(len(item["text"]) for item in dialogue)
assert total <= 5000
Quando si supera il limite, la soluzione corretta è suddividere secondo i confini semantici in più sotto-dialoghi, inviarli separatamente, ottenere gli audio separatamente e poi combinarli secondo le esigenze di business; non troncare le battute né eliminarle. In fase di suddivisione tieni presenti tre punti:
- scegli i punti di taglio in corrispondenza di cambi di scena o di argomento, evitando di separare una domanda e la relativa risposta in due richieste;
- conta separatamente ogni sotto-segmento, che anch'esso non deve superare 5000;
- quando ricostruisci l'array di ogni segmento dopo la suddivisione, mantieni l'ordine originale delle righe e la mappatura delle voci dei personaggi.
Se il contenuto è già di per sé un dialogo lungo, è consigliabile organizzarlo a monte per «atti» o «capitoli», in modo che ogni atto rientri naturalmente nel budget e si riducano le fratture nell'ascolto dovute a suddivisioni temporanee.
Parametri opzionali: stability e language_code
Oltre a dialogue, l'interfaccia offre due parametri opzionali, la cui scelta dipende dal tipo di contenuto.
stability
stability è un parametro numerico, può valere 0, 0.5, 1, valore predefinito 0.5. Il significato è la stabilità del timbro:
- più il valore è basso, più l'emozione è ricca e varia, adatto a dialoghi con alti e bassi emotivi e contenuti narrativi;
- più il valore è alto, più l'output è stabile e coerente, adatto a scenari che richiedono un ascolto uniforme come annunci di marca e script di assistenza clienti;
- il valore predefinito 0.5 è un compromesso tra i due.
Nota che è un parametro a livello dell'intera richiesta, non impostabile riga per riga. Quando in uno stesso dialogo le emozioni dei personaggi differiscono molto, o accetti un valore di compromesso, oppure in fase di suddivisione fai usare stability diversi ai diversi segmenti.
language_code
language_code è un codice lingua in formato ISO, valore predefinito stringa vuota; lasciandolo vuoto si indica rilevamento automatico della lingua. Quando la lingua del contenuto è chiara e si vuole evitare deviazioni nel rilevamento, specificarla esplicitamente è più sicuro, ad esempio per contenuti in cinese inserisci zh. Il contratto fornisce l'enumerazione completa dei codici lingua: va validata una volta prima dell'invio per evitare di passare valori non supportati.
Nessuno dei due parametri è obbligatorio; se il contenuto non ha esigenze particolari, ometterli e usare il comportamento predefinito è del tutto possibile.
Invio e validazione: verifica secondo il contratto a task
L'interfaccia si invia in forma di task: invii l'input, ottieni il risultato di un task e poi fai la validazione su quel risultato. Questo implica due cose.
Primo, il contratto di input va validato da te. Prima di inviare la richiesta controlla punto per punto: dialogue è un array con almeno 1 elemento; ogni elemento ha sia text sia voice non vuoti; il totale dei caratteri di tutti i text non supera 5000; stability assume solo 0/0.5/1; language_code appartiene all'enumerazione o è vuoto. Mettere questi controlli nel client riduce sensibilmente gli invii non validi.
Secondo, non dare per scontati comportamenti non dichiarati dal contratto. La documentazione dell'interfaccia non promette retry automatici, chiavi di idempotenza o compensazioni in caso di errore, quindi non fare affidamento sul «reinviare la stessa richiesta» come rete di sicurezza: ogni invio va considerato un task indipendente. La prassi ingegneristica più sicura è:
- prima dell'invio, registra il riepilogo dell'input della richiesta (numero di elementi dell'array, totale caratteri, versione della mappatura delle voci) per un confronto successivo;
- dopo aver ottenuto il risultato, verifica prima che l'audio sia utilizzabile, la durata ragionevole e i personaggi distinguibili, poi procedi alla distribuzione a valle;
- se occorre rieseguire, ripeti l'intera validazione dell'input, senza riutilizzare un vecchio corpo di richiesta non verificato.
La validazione si concentra sul «se il risultato è conforme alle aspettative», non sul presumere i processi interni del servizio. Su HiAPI puoi consultare il contratto attuale dalla pagina del modello elevenlabs/text-to-dialogue prima di iniziare.
Checklist di autovalutazione prima del rilascio
Rendendo automatico il seguente gruppo di controlli prima dell'invio, si coprono di fatto la stragrande maggioranza delle cause di errore:
dialogueè un array con numero di elementi ≥ 1;- ogni elemento contiene sia
textsiavoice, e nessuno dei due è una stringa vuota; - ogni
voicerientra nell'enumerazione del contratto e lo stesso personaggio usa globalmente un solo valore; - l'ordine dell'array corrisponde all'ordine delle righe del copione, senza logiche di ordinamento o deduplicazione;
- il totale dei caratteri di tutti i
textè ≤ 5000, e i contenuti in eccesso sono stati suddivisi per semantica; - se impostati esplicitamente,
stability∈ {0, 0.5, 1},language_code∈ enumerazione o vuoto; - il riepilogo dell'input (numero di elementi, numero di caratteri, versione della mappatura) è registrato per il confronto in fase di validazione.
Oltre alla checklist, c'è una regola empirica: esegui prima l'end-to-end su un campione breve, poi estendi all'intero copione. I problemi di mappatura dei personaggi e di budget di caratteri emergono già su un campione di qualche decina di righe, senza bisogno di attendere l'invio dell'intero contenuto per scoprirli.
Articoli correlati
Vedi tutti gli articoli →-
Guida all'uso
Guida introduttiva a gpt-6.2-sol: limiti delle capacità, integrazione API e note sui prezzi per token
Punti decisionali e pratici per l'integrazione rivolti ai team di ingegneria
-
Guida all'uso
Guida introduttiva a gpt-6.2-astra: confini delle capacità del modello testuale, punti di integrazione e controllo dei costi
-
Guida all'uso
Guida introduttiva a Tripo H3.1: come scegliere tra tre modalità di input, parametri e prezzi
Guida pratica per sviluppatori: decisioni di integrazione e controllo dei costi nella generazione 3D