Esegui la migrazione a Gemini 3.8 TTS

Questa pagina descrive come passare dai modelli Gemini TTS precedenti, come gemini-3.1-flash-tts-preview, gemini-2.5-flash-tts, gemini-2.5-pro-tts, e gemini-2.5-flash-lite-preview-tts, a Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) e Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts). I modelli precedenti sono documentati in Gemini-TTS nella Google Cloud documentazione Text-to-Speech.

Scegliere un modello sostitutivo

  • Gemini 3.8 Flash-Lite TTS è la sostituzione consigliata per gemini-3.1-flash-tts-preview. Sceglila per la produzione di grandi volumi, gli agenti vocali, le funzionalità di lettura ad alta voce e la sintesi vocale quotidiana con un solo speaker.
  • Gemini 3.8 Flash TTS è il modello di punta. Sceglilo quando la fedeltà della voce, la sfumatura della recitazione, il dialogo tra più persone o la copertura dei dialetti sono più importanti, ad esempio per audiolibri e narrazioni in studio.

Entrambi i modelli utilizzano lo stesso schema di richiesta, quindi puoi passare da uno all'altro modificando l'ID modello. Per un confronto, consulta Quando utilizzare un modello o l'altro.

Riepilogo delle modifiche

Area Modelli Gemini TTS precedenti Modelli TTS di Gemini 3.8
API API Cloud Text-to-Speech o API Gemini Enterprise Solo API Gemini Enterprise (generateContent e streamGenerateContent)
Località global ed endpoint regionali Solo global
Direzione dello stile Scritto nel testo ("Say the following in a curious way: ...") o nel campo prompt di Cloud Text-to-Speech speech_metadata.style su ogni parte
Dialogo con più relatori Prefissi dell'oratore in un blocco di testo o Cloud Text-to-Speech multiSpeakerMarkup Una parte per turno con speech_metadata.speaker
Tag vocali in linea Parentesi quadre, ad esempio [sigh] Parentesi angolari, ad esempio <sigh>
Selezione della voce prebuiltVoiceConfig.voiceName voiceConfig.voice, che accetta anche ID vocali progettati e chiavi di replica vocale. prebuiltVoiceConfig.voiceName funziona ancora per le voci predefinite.
Voci personalizzate Audio di riferimento in linea in replicatedVoiceConfig Progettazione vocale e replica vocale tramite l'API Voices
Output predefinito (API Gemini Enterprise) PCM a 16 bit non elaborato, 24 kHz, mono Richieste unarie: un file WAV completo (PCM a 16 bit, 24 kHz, mono). Richieste di streaming: PCM a 16 bit non elaborato, invariato. Puoi richiedere altre codifiche con responseFormat.
temperature, topP, topK Ignorato Rifiutato con errore INVALID_ARGUMENT

Aggiorna le richieste

  1. Sposta le indicazioni di stile in speech_metadata.style: i modelli TTS di Gemini 3.8 leggono text come una trascrizione letterale, quindi le indicazioni scritte nel testo potrebbero essere lette ad alta voce. Inserisci le indicazioni su recitazione, tono, prosodia e ritmo in speech_metadata.style.
  2. Utilizza una parte per ogni turno di dialogo: per i dialoghi con più interlocutori, passa ogni turno come part separato e imposta speech_metadata.speaker su ogni turno su uno degli interlocutori in multiSpeakerVoiceConfig.
  3. Sostituisci i tag tra parentesi quadre con tag tra parentesi angolari: utilizza le parentesi angolari, ad esempio <sigh>, <laugh> o <short pause>, solo per gli eventi vocali in un determinato momento. Scrivi le disfluenze, ad esempio "ehm", direttamente nella trascrizione.
  4. Progetta le persona in anticipo: sostituisci le richieste lunghe "Profilo audio" o "Note del regista" con una voce creata in Progettazione della voce e mantieni style breve o vuoto.
  5. Rimuovi parametri non supportati: rimuovi temperature, topP, topK, candidateCount e systemInstruction dalle tue richieste.
  6. Gestisci l'output WAV dalle richieste unarie: le richieste unarie ora restituiscono un file WAV completo anziché PCM non elaborato. Se il codice aggiunge un'intestazione WAV o concatena i clip, rimuovi il passaggio dell'intestazione o imposta generationConfig.responseFormat su AUDIO_L16 per mantenere l'output PCM non elaborato.
  7. Ricrea le voci replicate con l'API Voices: l'audio di riferimento in linea in replicatedVoiceConfig non è supportato. Crea una voce memorizzata o una chiave di replica della voce con l'API Voices e passala in voiceConfig.voice. Per maggiori dettagli, consulta Replica vocale.

Per ulteriori indicazioni sulla scrittura dei prompt, consulta la guida ai prompt.

Esempio

L'esempio seguente mostra una richiesta gemini-3.1-flash-tts-preview e la richiesta TTS Gemini 3.8 equivalente.

Prima di Gemini 3.8

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-3.1-flash-tts-preview",
    contents="Say the following in a curious way: OK, so... tell me about this [uhm] AI thing.",
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO"],
        speech_config=types.SpeechConfig(
            language_code="en-US",
            voice_config=types.VoiceConfig(
                prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
            ),
        ),
    ),
)

Gemini 3.8 o versioni successive

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-3.8-flash-lite-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "OK, so... uhm, tell me about this AI thing.",
            "speech_metadata": {"style": "curious"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "language_code": "en-US",
            "voice_config": {"voice": "Kore"},
        },
    },
)

Entrambe le risposte restituiscono l'audio in response.candidates[0].content.parts[0].inline_data.data. Il modello precedente restituisce audio PCM a 16 bit non elaborato (24 kHz, mono), mentre il modello TTS Gemini 3.8 restituisce un file WAV completo.

Eseguire la migrazione dall'API Cloud Text-to-Speech

Se chiami Gemini TTS tramite l'API Cloud Text-to-Speech (texttospeech.googleapis.com), invia le richieste al metodo generateContent su aiplatform.googleapis.com. La seguente tabella mappa i campi della richiesta Cloud Text-to-Speech ai campi della richiesta dell'API Gemini Enterprise:

API Cloud Text-to-Speech (text:synthesize) API Gemini Enterprise (generateContent)
input.text contents[].parts[].text
input.prompt contents[].parts[].speechMetadata.style
input.multiSpeakerMarkup.turns[] (speaker, text) Una parte per turno, con text e speechMetadata.speaker
voice.modelName L'ID modello nell'URL della richiesta
voice.name generationConfig.speechConfig.voiceConfig.voice
voice.languageCode generationConfig.speechConfig.languageCode
voice.multiSpeakerVoiceConfig.speakerVoiceConfigs[] (speakerAlias, speakerId) generationConfig.speechConfig.multiSpeakerVoiceConfig.speakerVoiceConfigs[] (speaker, voiceConfig.voice)
audioConfig.audioEncoding: LINEAR16 generationConfig.responseFormat[].audio.mimeType: AUDIO_WAV (valore predefinito per le richieste unarie)
audioConfig.audioEncoding: PCM AUDIO_L16 (valore predefinito per le richieste di streaming)
audioConfig.audioEncoding: MULAW o ALAW AUDIO_MULAW o AUDIO_ALAW
audioConfig.audioEncoding: MP3 o OGG_OPUS Non supportati. Codifica l'audio sul client.
audioConfig.sampleRateHertz Non supportati. Per le frequenze di campionamento dell'uscita audio, consulta Formati di uscita audio.

L'API Cloud Text-to-Speech restituisce l'audio con codifica base64 in audioContent. L'API Gemini Enterprise lo restituisce in candidates[0].content.parts[0].inlineData.data.

Passaggi successivi