Generare la sintesi vocale con Gemini TTS

I modelli di sintesi vocale (TTS) di Gemini convertono il testo in audio con uno o più parlanti. Puoi controllare lo stile, l'accento, il ritmo e il tono dell'audio con i metadati dei turni strutturati (speech_metadata) e i tag vocali incorporati.

Questa pagina mostra come generare il parlato con i seguenti modelli utilizzando i metodi generateContent e streamGenerateContent dell'API Gemini Enterprise:

I modelli TTS sono personalizzati per la recitazione esatta del testo con un controllo granulare su stile e suono, come narrazione, audiolibri e risposte degli agenti vocali. Per conversazioni interattive in tempo reale con input e output audio, utilizza invece l'API Live.

Se utilizzi un modello Gemini TTS precedente, ad esempio gemini-3.1-flash-tts-preview, consulta la guida alla migrazione.

Per provare la generazione di voce di una singola persona senza scrivere codice, apri Gemini 3.8 Flash TTS in Agent Studio:

Prova Gemini 3.8 TTS in Agent Studio

Modelli supportati

Modello Unico relatore Più relatori Streaming Voice design (anteprima) Replica vocale (anteprima)
Gemini 3.8 Flash TTS (gemini-3.8-flash-tts)
Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts)
Gemini 3.1 Flash TTS Preview (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à di questa pagina si applicano ai modelli Gemini 3.8 TTS. Per i modelli precedenti, consulta Gemini-TTS nella documentazione diGoogle Cloud Text-to-Speech.

Quando utilizzare un modello o l'altro

Entrambi i modelli Gemini 3.8 TTS condividono lo stesso schema di richiesta e lo stesso formato di 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 fedeltà acustica, la recitazione sfumata e il controllo espressivo sono la priorità assoluta. È adatto per lavori creativi di livello professionale, dialoghi complessi con più interlocutori, tag di vocal burst frequenti, pronunce difficili, dialetti regionali o di minoranze e narrazioni di lunga durata che richiedono una voce e un tono ambientale stabili.
  • Utilizza Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) per workload di produzione rapidi ed economici. È la sostituzione consigliata per gemini-3.1-flash-tts-preview ed è adatta per la produzione in batch di volumi elevati, le cascate di agenti vocali conversazionali, le funzionalità di lettura ad alta voce, la replica vocale e il parlato quotidiano con un singolo 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 il tuo ambiente di sviluppo.

  3. Per utilizzare gli esempi di Python, installa la versione 2.33.0 o successive dell'SDK Google Gen AI:

    pip install --upgrade "google-genai>=2.33.0"

Località ed endpoint regionali disponibili

I modelli Gemini 3.8 TTS sono disponibili nella località global e nelle località multi-regione us e eu:

Località Parametro di località Endpoint
Globale global https://aiplatform.googleapis.com
Stati Uniti (multiregionale) us https://aiplatform.us.rep.googleapis.com
Unione Europea (multiregionale) eu https://aiplatform.eu.rep.googleapis.com

Per indirizzare le richieste a un endpoint regionale, imposta location="us" (o location="eu") durante l'inizializzazione del client nell'SDK oppure invia le richieste al nome host multiregionale corrispondente (https://aiplatform.us.rep.googleapis.com o https://aiplatform.eu.rep.googleapis.com) con il percorso della località corrispondente nell'URL REST:

Python

from google import genai

# Set location to 'us' or 'eu' for multi-region routing (or 'global' for global)
client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="us",
)

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"}},
    },
)

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.us.rep.googleapis.com/v1/projects/PROJECT_ID/locations/us/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 con un solo speaker

Per convertire il testo in audio con un singolo interlocutore, 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 il nome di una voce predefinita, l'ID di una voce della libreria 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), in modo da poter scrivere i byte audio direttamente in un file .wav. Le richieste di streaming restituiscono invece blocchi PCM non elaborati. Per informazioni dettagliate e altre codifiche, consulta Formati di output audio.

Console

  1. Apri Gemini 3.8 Flash TTS o Gemini 3.8 Flash-Lite TTS in Agent Studio.
  2. Nel riquadro delle impostazioni, scegli una voce predefinita, una lingua (o mantieni Rilevamento automatico) e una descrizione facoltativa dello stile (ad esempio, cheerful and friendly).
  3. Inserisci la trascrizione da pronunciare nel campo del prompt e inviala per generare, riprodurre o scaricare l'audio WAV. Fai clic su Ottieni codice per esportare la richiesta come Python, JavaScript o curl.

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 in streaming con un singolo interlocutore

Per ricevere l'audio mentre il modello lo sta ancora sintetizzando, utilizza il metodo streamGenerateContent. Le risposte in streaming restituiscono blocchi PCM non elaborati a 16 bit senza intestazione (24 kHz, mono), in modo da poter passare ogni blocco a un player, a un socket o a un'altra pipeline audio non appena arriva. Nell'esempio Python seguente, 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 con più speaker

Per il dialogo tra due interlocutori, configura entrambi gli interlocutori 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 in streaming con più speaker

Le richieste con più speaker supportano anche lo streaming. Utilizza la stessa richiesta di TTS con più speaker 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.

Controlla 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, come "Say cheerfully: Hello!" o "Speaker 1: Hello!", potrebbero essere lette ad alta voce. Per controllare la consegna, suddividi le istruzioni in base all'ambito:

  • Resa sostenuta a livello di turno (speech_metadata.style): inserisci l'emozione, lo stile di resa, 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 incorporati): inserisci i suoni vocali non verbali momentanei e le 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: oltre 2000 voci preimpostate curate in diverse lingue, accenti regionali e personalità dei personaggi.
  3. Voice design (anteprima): crea una voce personalizzata da una descrizione in linguaggio naturale con il metodo create dell'API Voices (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 (anteprima): 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_... archiviato. 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 list, get e delete dell'API Voices 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 parlato con una voce memorizzata riavvia il periodo di conservazione di un anno, quindi una voce che utilizzi regolarmente non scade. Le richieste di creazione della voce sono soggette a una quota per progetto e al minuto. Se lo superi, il metodo create restituisce un errore RESOURCE_EXHAUSTED. Per saperne di più, consulta Quote e limiti di sistema.

Archiviazione e conservazione dei dati

Google memorizza gli input che fornisci quando crei una voce memorizzata, insieme agli artefatti vocali derivati, in associazione al progettoGoogle Cloud che ha creato la voce.

Quando crei una voce replicata dalla registrazione di un oratore, vengono memorizzati i seguenti dati:

  • Audio di riferimento: il campione dello speaker la cui voce viene replicata.
  • Audio di consenso: l'oratore che legge la dichiarazione di consenso richiesta.

Quando crei una voce progettata utilizzando una descrizione testuale di una voce in un prompt, vengono memorizzati i seguenti dati:

  • Il prompt testuale che hai scritto per descrivere la voce.
  • L'audio della voce generato dal prompt, che il modello utilizza come riferimento per la voce.

Una voce progettata non ha un audio di consenso, perché viene generata da una descrizione anziché dalla registrazione di una persona.

Gli input vocali vengono memorizzati in modo che la tua voce continui a funzionare con gli aggiornamenti del modello. Gli artefatti vocali vengono rigenerati dagli input archiviati quando il modello sottostante viene aggiornato. Se non vengono trovati input archiviati per una voce, i relativi artefatti non possono essere rigenerati e la voce smette di funzionare dopo un aggiornamento del modello. Dovrai quindi creare di nuovo la voce.

Gli input archiviati vengono utilizzati solo per rigenerare la voce quando i modelli vengono aggiornati. Sono criptati at-rest e isolati nel progetto che ha creato la voce.

Periodo di conservazione

Le voci e tutti i dati archiviati associati vengono conservati per un massimo di un anno (365 giorni) dall'ultima volta che hai utilizzato la voce per sintetizzare il parlato. Il periodo inizia quando crei la voce e viene reimpostato ogni volta che invii una richiesta di sintesi che utilizza la voce. Se una voce non viene utilizzata per 365 giorni, la voce, gli input memorizzati e gli artefatti derivati vengono eliminati.

Eliminazione da parte del cliente

Puoi eliminare una voce in qualsiasi momento con il metodo delete dell'API Voices. L'eliminazione di una voce comporta l'eliminazione degli input archiviati e degli artefatti derivati. L'eliminazione del progetto Google Cloud proprietario di una voce comporta anche l'eliminazione della voce, seguendo la procedura standard di eliminazione del progetto.

Voci predefinite

Il seguente elenco mostra il nome di ogni voce predefinita e la relativa caratteristica:

  • Achernar: morbido
  • Achird: amichevole
  • Algenib: rauca
  • Algieba: Smooth
  • Alnilam: decisa
  • Aoede: ariosa
  • Autonoe: brillante
  • Callirrhoe: informale
  • Charon: informativa
  • Despina: fluida
  • Enceladus: sussurrante
  • Erinome: Clear
  • Fenrir: emotiva
  • Gacrux: matura
  • Iapetus: chiara
  • Kore: decisa
  • Laomedeia: allegra
  • Leda: giovanile
  • Orus: azienda
  • Puck: Upbeat
  • Pulcherrima: diretta
  • Rasalgethi: informativa
  • Sadachbia: vivace
  • Sadaltager: esperta
  • Schedar: Uniforme
  • Sulafat: calda
  • Umbriel: rilassata
  • Vindemiatrix: delicata
  • Zephyr: brillante
  • Zubenelgenubi: disinvolta

Raccolta di voci estesa

Oltre alle 30 voci predefinite, la libreria di voci estesa offre più di 2000 voci preimpostate selezionate in varie lingue, accenti regionali, personaggi e casi d'uso come audiolibri, agenti conversazionali e notizie. Per utilizzare una voce della libreria, passa il suo ID in speechConfig.voiceConfig.voice, nello stesso modo in cui passi un nome di voce predefinita.

Per sfogliare la libreria, chiama il metodo list dell'API Voices (ListVoices). Restituisce le voci personalizzate archiviate nel tuo progetto, seguite dalle voci predefinite e della libreria di voci estesa. Ogni voce della libreria include il proprio id e i metadati come language_code, accent, gender, pitch, persona e description. Per restringere i risultati, utilizza i seguenti filtri:

  • type: l'origine della voce: prebuilt per le voci predefinite e della libreria, prompted per le voci progettate o replicated per le voci replicate. Se passi più di un valore, il metodo restituisce le 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 nella libreria le voci del narratore:

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 visualizzare 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 non elaborati a 16 bit con segno, little-endian e senza intestazione (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 mimeType:

Valore mimeType Formato Descrizione
AUDIO_WAV (unary default) WAV (audio/wav) File WAV completo con un'intestazione RIFF (PCM a 16 bit, 24 kHz, mono).
AUDIO_L16 (valore predefinito per lo streaming) PCM lineare (audio/l16) PCM raw a 16 bit signed, little endian, senza intestazione. Utilizzalo per lo streaming, le pipeline audio personalizzate o la concatenazione di clip multi-turn.
AUDIO_MULAW μ-law (audio/mulaw) Audio compresso con legge μ G.711 (8 kHz, mono), di uso comune nella telefonia nordamericana e giapponese.
AUDIO_ALAW A-law (audio/alaw) Audio compresso con legge A G.711 (8 kHz, mono), di uso comune nella telefonia europea e internazionale.

I modelli ignorano il campo sampleRate. L'output PCM e WAV lineare è di 24 kHz, mentre l'output μ-law e A-law è di 8 kHz, indipendentemente dalla frequenza nella risposta mimeType. Se la pipeline richiede una frequenza di campionamento diversa, ricampiona l'output sul client.

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 supporta 101 lingue:

Limitazioni

  • I modelli TTS accettano input di solo testo e restituiscono output di solo audio.
  • Le richieste con più speaker richiedono esattamente due speaker. Per combinare voci progettate (voice_...) o replicate (voice_... o voicekey_...) in un dialogo 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 concatenare i clip.
  • I modelli sono disponibili nelle località global, us e eu.
  • Le voci personalizzate di proprietà dell'utente (voci create con la progettazione o la replica vocale) sono disponibili solo nella località global.
  • Le istruzioni di sistema non sono supportate.
  • Non puoi impostare la frequenza di campionamento di output. L'output MP3 e Ogg Opus non è supportato.

Passaggi successivi