Generare la sintesi vocale con Gemini TTS

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:

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 di gemini-3.1-flash-tts-preview ed è 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

  1. Configura un progetto e abilita l'API Gemini Enterprise.
  2. Configura le Credenziali predefinite dell'applicazione per l'ambiente di sviluppo.
  3. 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 in speech_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:

  1. Voci predefinite: 30 voci selezionate.
  2. Libreria di voci estesa: più di 2000 voci preimpostate selezionate in base a lingue, accenti regionali e personaggi.
  3. 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 o POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices). Imposta type su VOICE_TYPE_PROMPTED e store su true. La risposta restituisce un ID voice_... memorizzato e un campione della voce.
  4. Replica vocale: Replica la voce di un oratore dall'audio di riferimento e di consenso con lo stesso metodo create. Imposta type su VOICE_TYPE_REPLICATED. Con store: true, la risposta restituisce un ID voice_... memorizzato. Con store: false, restituisce una chiave voicekey_... 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: prebuilt per le voci predefinite e della libreria, prompted per le voci progettate o replicated per 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_... o voicekey_...) 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'output AUDIO_L16 per 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