I modelli di sintesi vocale (TTS) di Gemini convertono il testo in audio con una o più voci. Puoi controllare lo stile, l'accento, il ritmo e il tono
dell'audio con i metadati strutturati del turno (speech_metadata) e i tag vocali
inline.
Questa pagina mostra come generare un discorso con i seguenti modelli utilizzando i metodi
generateContent e streamGenerateContent dell'API Gemini Enterprise:
- Gemini 3.8 Flash TTS
(
gemini-3.8-flash-tts) - Gemini 3.8 Flash-Lite TTS
(
gemini-3.8-flash-lite-tts)
I modelli TTS sono pensati per la recitazione esatta del testo con un controllo granulare su stile e suono, ad esempio narrazione, audiolibri e risposte dell'agente vocale. Per conversazioni interattive in tempo reale con input e output audio, utilizza l'API Live.
Se utilizzi un modello Gemini TTS precedente, ad esempio gemini-3.1-flash-tts-preview,
consulta la
guida alla migrazione.
Modelli supportati
| Modello | Unico relatore | Più relatori | Streaming | Progettazione della voce | Replica vocale |
|---|---|---|---|---|---|
Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) |
|||||
Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) |
|||||
Anteprima di Gemini 3.1 Flash TTS (gemini-3.1-flash-tts-preview) |
|||||
Gemini 2.5 Pro TTS (gemini-2.5-pro-tts) |
|||||
Gemini 2.5 Flash TTS (gemini-2.5-flash-tts) |
Gli esempi e le funzionalità in questa pagina si applicano ai modelli TTS Gemini 3.8. Per i modelli precedenti, consulta Gemini-TTS nella Google Cloud documentazione di Text-to-Speech.
Quando utilizzare un modello o l'altro
Entrambi i modelli Gemini 3.8 TTS condividono lo stesso schema di richiesta e formato del prompt, quindi puoi passare da uno all'altro modificando l'ID modello:
- Utilizza Gemini 3.8 Flash TTS (
gemini-3.8-flash-tts) quando la priorità assoluta è la fedeltà acustica, l'interpretazione ricca di sfumature e il controllo espressivo. È adatto a lavori creativi di livello professionale, dialoghi complessi tra più speaker, tag vocali frequenti, pronunce difficili, dialetti regionali o di minoranze e narrazioni lunghe che richiedono una voce e un tono della stanza stabili. - Utilizza Gemini 3.8 Flash-Lite TTS (
gemini-3.8-flash-lite-tts) per carichi di lavoro di produzione rapidi ed economici. È la sostituzione consigliata digemini-3.1-flash-tts-previewed è adatta alla produzione di batch ad alto volume, alle cascate di agenti vocali conversazionali, alle funzionalità di lettura vocale, alla replica della voce e alla sintesi vocale quotidiana con un solo speaker nelle principali lingue.
Prima di iniziare
- Configura un progetto e abilita l'API Gemini Enterprise.
- Configura le Credenziali predefinite dell'applicazione per l'ambiente di sviluppo.
Per utilizzare gli esempi Python, installa la versione 2.25.0 o successive dell'SDK Google Gen AI:
pip install --upgrade "google-genai>=2.25.0"
I modelli Gemini 3.8 TTS sono disponibili nella località global. Invia richieste
all'endpoint aiplatform.googleapis.com.
TTS con un solo speaker
Per convertire il testo in audio con un solo oratore, passa la trascrizione letterale in
parts[].text, aggiungi uno stile facoltativo a livello di turno in parts[].speech_metadata
e imposta la voce in speechConfig.voiceConfig.voice. Il campo voice accetta
un nome di voce predefinita, un
ID voce della raccolta di voci estesa o l'ID (voice_...) di una
voce progettata o
replicata (o una chiave
voicekey_... stateless facoltativa).
Per impostazione predefinita, le richieste unarie restituiscono un file WAV completo (PCM a 16 bit, 24 kHz, mono), quindi puoi scrivere i byte audio direttamente in un file .wav. Le richieste di streaming restituiscono invece blocchi PCM non elaborati. Per dettagli e altre codifiche, vedi
Formati di uscita audio.
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-3.8-flash-tts",
contents=[{
"role": "user",
"parts": [{
"text": "Have a wonderful day!",
"speech_metadata": {"style": "cheerful and friendly"},
}],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {"voice_config": {"voice": "Kore"}},
},
)
# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("out.wav", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Have a wonderful day!",
"speechMetadata": {"style": "cheerful and friendly"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "Kore"}
}
}
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > out.wav
TTS per lo streaming con un solo speaker
Per ricevere l'audio mentre il modello lo sta ancora sintetizzando, utilizza il
metodo streamGenerateContent. Le risposte di streaming restituiscono blocchi PCM a 16 bit non elaborati (24 kHz, mono), quindi puoi passare ogni blocco a un lettore, a un
socket o a un'altra pipeline audio man mano che arrivano. Nel seguente esempio Python, la funzione emit_audio rappresenta la destinazione.
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
def emit_audio(pcm: bytes) -> None:
"""Sends a chunk of raw 16-bit PCM audio (24 kHz, mono) downstream."""
# Replace with your audio destination, such as a player, a WebSocket,
# or a telephony stream.
print(f"Received {len(pcm)} bytes of audio")
response_stream = client.models.generate_content_stream(
model="gemini-3.8-flash-lite-tts",
contents=[{
"role": "user",
"parts": [{
"text": "Have a wonderful day!",
"speech_metadata": {"style": "cheerful and friendly"},
}],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {"voice_config": {"voice": "Kore"}},
},
)
for chunk in response_stream:
if not chunk.candidates or not chunk.candidates[0].content:
continue
for part in chunk.candidates[0].content.parts or []:
if part.inline_data and part.inline_data.data:
emit_audio(part.inline_data.data)
REST
curl -N -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-lite-tts:streamGenerateContent?alt=sse" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Have a wonderful day!",
"speechMetadata": {"style": "cheerful and friendly"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "Kore"}
}
}
}' | sed -n 's/^data: //p' \
| jq -r '.candidates[0].content.parts[0].inlineData.data // empty' \
| while read -r chunk; do echo "$chunk" | base64 --decode; done > streamed.pcm
Il file streamed.pcm contiene audio PCM non elaborato a 16 bit a 24 kHz, mono.
TTS multilocutore
Per il dialogo tra due oratori, configura entrambi gli oratori in
speechConfig.multiSpeakerVoiceConfig.speakerVoiceConfigs. Quindi, passa ogni turno
come part separato, imposta speech_metadata.speaker su ogni turno su uno dei
nomi degli speaker configurati e aggiungi un style facoltativo a livello di turno.
Le richieste con più speaker richiedono esattamente due speaker.
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-3.8-flash-tts",
contents=[{
"role": "user",
"parts": [
{
"text": "How's it going today, Jane?",
"speech_metadata": {"speaker": "Joe", "style": "cheerful and friendly"},
},
{
"text": "Not too bad, how about you? Ready to test these new voices?",
"speech_metadata": {"speaker": "Jane", "style": "calm and relaxed"},
},
],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {
"multi_speaker_voice_config": {
"speaker_voice_configs": [
{"speaker": "Joe", "voice_config": {"voice": "Puck"}},
{"speaker": "Jane", "voice_config": {"voice": "Kore"}},
]
}
},
},
)
with open("dialogue.wav", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [
{
"text": "How'\''s it going today, Jane?",
"speechMetadata": {"speaker": "Joe", "style": "cheerful and friendly"}
},
{
"text": "Not too bad, how about you? Ready to test these new voices?",
"speechMetadata": {"speaker": "Jane", "style": "calm and relaxed"}
}
]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"multiSpeakerVoiceConfig": {
"speakerVoiceConfigs": [
{"speaker": "Joe", "voiceConfig": {"voice": "Puck"}},
{"speaker": "Jane", "voiceConfig": {"voice": "Kore"}}
]
}
}
}
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > dialogue.wav
TTS per lo streaming con più speaker
Le richieste con più oratori supportano anche lo streaming. Utilizza la stessa richiesta di
sintesi vocale multilingue con il metodo streamGenerateContent.
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
def emit_audio(pcm: bytes) -> None:
"""Sends a chunk of raw 16-bit PCM audio (24 kHz, mono) downstream."""
# Replace with your audio destination, such as a player, a WebSocket,
# or a telephony stream.
print(f"Received {len(pcm)} bytes of audio")
response_stream = client.models.generate_content_stream(
model="gemini-3.8-flash-tts",
contents=[{
"role": "user",
"parts": [
{
"text": "How's it going today, Jane?",
"speech_metadata": {"speaker": "Joe", "style": "cheerful and friendly"},
},
{
"text": "Not too bad, how about you? Ready to test these new voices?",
"speech_metadata": {"speaker": "Jane", "style": "calm and relaxed"},
},
],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {
"multi_speaker_voice_config": {
"speaker_voice_configs": [
{"speaker": "Joe", "voice_config": {"voice": "Puck"}},
{"speaker": "Jane", "voice_config": {"voice": "Kore"}},
]
}
},
},
)
for chunk in response_stream:
if not chunk.candidates or not chunk.candidates[0].content:
continue
for part in chunk.candidates[0].content.parts or []:
if part.inline_data and part.inline_data.data:
emit_audio(part.inline_data.data)
REST
curl -N -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:streamGenerateContent?alt=sse" \
-d '{
"contents": [{
"role": "user",
"parts": [
{
"text": "How'\''s it going today, Jane?",
"speechMetadata": {"speaker": "Joe", "style": "cheerful and friendly"}
},
{
"text": "Not too bad, how about you? Ready to test these new voices?",
"speechMetadata": {"speaker": "Jane", "style": "calm and relaxed"}
}
]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"multiSpeakerVoiceConfig": {
"speakerVoiceConfigs": [
{"speaker": "Joe", "voiceConfig": {"voice": "Puck"}},
{"speaker": "Jane", "voiceConfig": {"voice": "Kore"}}
]
}
}
}
}' | sed -n 's/^data: //p' \
| jq -r '.candidates[0].content.parts[0].inlineData.data // empty' \
| while read -r chunk; do echo "$chunk" | base64 --decode; done > dialogue_streamed.pcm
Il file dialogue_streamed.pcm contiene audio PCM non elaborato a 16 bit a 24 kHz,
mono.
Controllare lo stile del parlato con metadati e tag
I modelli Gemini 3.8 TTS trattano il campo text come una trascrizione letterale.
Le istruzioni scritte nel testo, ad esempio "Say cheerfully: Hello!" o
"Speaker 1: Hello!", potrebbero essere lette ad alta voce. Per controllare la pubblicazione, dividi le
istruzioni per ambito:
- Sustained turn-level delivery (
speech_metadata.style): inserisci l'emozione, lo stile di pronuncia, la prosodia, il ritmo e il volume che si applicano a un intero turno inspeech_metadata.style. Ad esempio,"style": "whispered urgently","style": "out of breath"o"style": "warm and enthusiastic". - Eventi puntuali (tag in linea): inserisci suoni vocali non verbali momentanei e pause all'interno della trascrizione tra parentesi angolari. Ad esempio,
"Wait... <short pause> did you hear that? <sigh>"o"Excuse me <cough> as I was saying...".
Per ulteriori indicazioni, consulta la guida ai prompt.
Opzioni vocali
I modelli Gemini 3.8 TTS supportano quattro modi per selezionare o creare voci:
- Voci predefinite: 30 voci selezionate.
- Libreria di voci estesa: più di 2000 voci preimpostate selezionate in base a lingue, accenti regionali e personaggi.
- Progettazione vocale:
Crea una voce personalizzata da una descrizione in linguaggio naturale con il metodo Voices
API
create(client.voices.create()nell'SDK Google Gen AI oPOST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices). ImpostatypesuVOICE_TYPE_PROMPTEDestoresutrue. La risposta restituisce un IDvoice_...memorizzato e un campione della voce. - Replica vocale:
Replica la voce di un oratore dall'audio di riferimento e di consenso con lo stesso
metodo
create. ImpostatypesuVOICE_TYPE_REPLICATED. Constore: true, la risposta restituisce un IDvoice_...memorizzato. Constore: false, restituisce una chiavevoicekey_...stateless.
Limiti e TTL della voce personalizzata
| Tipo di voce | Modalità di archiviazione | Gestione | Scadenza |
|---|---|---|---|
Voci memorizzate (voice_..., progettate o replicate) |
store: true |
Metodi API Voices list, get e delete |
1 anno dopo l'ultimo utilizzo |
Chiavi di replica vocale (voicekey_...) |
store: false |
Gestito dalla tua applicazione. Google non conserva la chiave. | 7 giorni dopo la creazione |
La generazione di un discorso con una voce memorizzata riavvia il periodo di conservazione di un anno,
in modo che una voce che utilizzi regolarmente non scada. Le richieste di creazione di voci sono
soggette a una quota per progetto al minuto. Se lo superi, il metodo create
restituisce un errore RESOURCE_EXHAUSTED. Per saperne di più, consulta Quote e limiti di sistema.
Voci predefinite
Il seguente elenco mostra il nome di ogni voce predefinita e la relativa caratteristica:
- Achernar: morbido
- Achird: amichevole
- Algenib: Gravelly
- Algieba: Fluida
- Alnilam: decisa
- Aoede: ariosa
- Autonoe: brillante
- Callirrhoe: informale
- Caronte: informativa
- Despina: fluida
- Enceladus: sussurrante
- Erinome: chiara
- Fenrir: emotiva
- Gacrux: matura
- Iapetus: chiara
- Kore: decisa
- Laomedeia: allegra
- Leda: giovanile
- Orus: solido
- Puck: Upbeat
- Pulcherrima: diretta
- Rasalgethi: informativa
- Sadachbia: vivace
- Sadaltager: esperta
- Schedar: Uniforme
- Sulafat: caldo
- Umbriel: tranquillo
- Vindemiatrix: delicata
- Zephyr: brillante
- Zubenelgenubi: informale
Libreria vocale estesa
Oltre alle 30 voci predefinite, la libreria di voci estese offre più di
2000 voci preimpostate curate in diverse lingue, accenti regionali, personaggi
e casi d'uso come audiolibri, agenti conversazionali e notizie.
Per utilizzare una voce della libreria, trasmetti il relativo ID in speechConfig.voiceConfig.voice, allo stesso modo in cui trasmetti il nome di una voce predefinita.
Per sfogliare la libreria, chiama il metodo list dell'API Voices (ListVoices). Restituisce le voci personalizzate memorizzate nel tuo progetto, seguite dalle voci predefinite e della libreria di voci estese. Ogni voce della libreria include il relativo id e
metadati come language_code, accent, gender, pitch, persona e
description. Per restringere i risultati, utilizza i seguenti filtri:
type: La fonte della voce:prebuiltper le voci predefinite e della libreria,promptedper le voci progettate oreplicatedper le voci replicate. Se trasmetti più di un valore, il metodo restituisce voci che corrispondono a uno qualsiasi di questi valori.search: testo da confrontare, senza distinzione tra maiuscole e minuscole, con il nome visualizzato e la descrizione di ogni voce.
L'esempio seguente cerca le voci del narratore nella libreria:
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.voices.list(type_=["prebuilt"], search="narrator", page_size=50)
for voice in response.voices or []:
print(voice.id, voice.language_code, voice.gender, voice.description)
REST
curl -G \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
--data-urlencode "type=prebuilt" \
--data-urlencode "search=narrator" \
--data-urlencode "pageSize=50"
Il metodo list restituisce fino a 50 voci per pagina. Per ottenere la pagina successiva, passa
il valore next_page_token della risposta come parametro page_token.
Formati di uscita audio
La codifica audio predefinita dipende dal metodo:
- Le richieste unarie (
generateContent) restituiscono un file WAV completo (audio/wav) con un'intestazione RIFF: PCM a 16 bit, 24 kHz, mono. - Le richieste di streaming (
streamGenerateContent) restituiscono blocchi PCM raw little-endian a 16 bit signed (audio/l16) a 24 kHz, mono.
Per richiedere una codifica diversa, imposta generationConfig.responseFormat su un
formato audio. I modelli Gemini 3.8 TTS supportano i seguenti valori di mimeType:
Valore mimeType |
Formato | Descrizione |
|---|---|---|
AUDIO_WAV (predefinito unario) |
WAV (audio/wav) |
File WAV completo con un'intestazione RIFF (PCM a 16 bit, 24 kHz, mono). |
AUDIO_L16 (predefinito per lo streaming) |
PCM lineare (audio/l16) |
PCM little endian signed a 16 bit non elaborato senza intestazione. Utilizzalo per lo streaming, le pipeline audio personalizzate o la concatenazione di clip multi-turn. |
AUDIO_MULAW |
μ-law (audio/mulaw) |
Audio compresso G.711 μ-law (8 kHz, mono), di uso comune nella telefonia nordamericana e giapponese. |
AUDIO_ALAW |
A-law (audio/alaw) |
Audio compresso G.711 A-law (8 kHz, mono), di uso comune nella telefonia europea e internazionale. |
I modelli ignorano il campo sampleRate. L'output PCM lineare e WAV è 24 kHz,
mentre l'output μ-law e A-law è 8 kHz, indipendentemente dalla tariffa nella risposta
mimeType. Ricampiona l'output sul client se la pipeline richiede una
frequenza di campionamento diversa.
L'esempio seguente richiede l'output μ-law per una pipeline di telefonia. L'SDK Google Gen AI per Python non espone responseFormat in GenerateContentConfig, quindi l'esempio Python lo passa nel corpo della richiesta con http_options.extra_body.
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-3.8-flash-tts",
contents=[{"role": "user", "parts": [{"text": "Have a wonderful day!"}]}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {"voice_config": {"voice": "Kore"}},
"http_options": {
"extra_body": {
"generationConfig": {
"responseFormat": [{"audio": {"mimeType": "AUDIO_MULAW"}}]
}
}
},
},
)
# The response is headerless μ-law audio at 8 kHz, mono.
with open("out.mulaw", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
-d '{
"contents": [{"role": "user", "parts": [{"text": "Have a wonderful day!"}]}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"responseFormat": [{"audio": {"mimeType": "AUDIO_MULAW"}}],
"speechConfig": {
"voiceConfig": {"voice": "Kore"}
}
}
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > out.mulaw
Lingue supportate
I modelli Gemini 3.8 TTS rilevano automaticamente la lingua di input. Gemini 3.8 Flash TTS supporta 130 lingue e Gemini 3.8 Flash-Lite TTS ne supporta 101:
Limitazioni
- I modelli TTS accettano input solo di testo e restituiscono output solo audio.
- Le richieste con più speaker richiedono esattamente due speaker. Per combinare voci progettate
(
voice_...) o replicate (voice_...ovoicekey_...) in dialoghi con più personaggi o per utilizzare più di due speaker, sintetizza il turno di ogni speaker singolarmente e concatena l'audio. Richiedi l'outputAUDIO_L16per ogni turno o rimuovi l'intestazione WAV da ogni clip prima di concatenarli. - I modelli sono disponibili solo nella località
global. - Le istruzioni di sistema non sono supportate.
- Non puoi impostare la frequenza di campionamento dell'output. L'output MP3 e Ogg Opus non è supportato.
Passaggi successivi
- Scopri come dirigere lo stile, il ritmo e i suoni vocali nella guida ai prompt.
- Crea voci personalizzate da una descrizione testuale con Voice design.
- Replica la voce di un oratore con la replica vocale.
- Consulta le specifiche del modello nelle pagine dei modelli Gemini 3.8 Flash TTS e Gemini 3.8 Flash-Lite TTS.