Migrar para o Gemini 3.8 TTS

Esta página descreve como migrar de modelos anteriores do Gemini TTS, como gemini-3.1-flash-tts-preview, gemini-2.5-flash-tts, gemini-2.5-pro-tts e gemini-2.5-flash-lite-preview-tts, para o Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) e o Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts). Os modelos anteriores estão documentados em Gemini-TTS na documentação de Google CloudText-to-Speech.

Escolher um modelo substituto

  • O Gemini 3.8 Flash-Lite TTS é a substituição recomendada para gemini-3.1-flash-tts-preview. Escolha essa opção para produção em grande volume, agentes de voz, recursos de leitura em voz alta e fala cotidiana com um único alto-falante.
  • O Gemini 3.8 Flash TTS é o modelo principal. Escolha essa opção quando a fidelidade da voz, a sutileza da atuação, o diálogo com vários falantes ou a cobertura de dialetos forem mais importantes, como em audiolivros e narrações de estúdio.

Os dois modelos usam o mesmo esquema de solicitação. Portanto, é possível alternar entre eles mudando o ID do modelo. Para uma comparação, consulte Quando usar cada modelo.

Resumo das mudanças

Área Modelos anteriores do Gemini TTS Modelos de TTS do Gemini 3.8
API API Cloud Text-to-Speech ou API Gemini Enterprise Somente API Gemini Enterprise (generateContent e streamGenerateContent)
Local global e endpoints regionais Apenas o global
Direção de estilo Escrito no texto ("Say the following in a curious way: ...") ou no campo prompt do Cloud Text-to-Speech speech_metadata.style em cada parte
Diálogo com vários falantes Prefixos de falante em um bloco de texto ou Cloud Text-to-Speech multiSpeakerMarkup Uma parte por vez com speech_metadata.speaker
Tags vocais inline Colchetes, como [sigh] Colchetes angulares, como <sigh>
Seleção de voz prebuiltVoiceConfig.voiceName voiceConfig.voice, que também aceita IDs de voz projetados e chaves de replicação de voz. prebuiltVoiceConfig.voiceName ainda funciona para vozes pré-criadas.
Vozes personalizadas Áudio de referência inline em replicatedVoiceConfig Design de voz e replicação de voz usando a API Voices
Saída padrão (API Gemini Enterprise) PCM bruto de 16 bits, 24 kHz, mono Solicitações unárias: um arquivo WAV completo (PCM de 16 bits, 24 kHz, mono). Solicitações de streaming: PCM bruto de 16 bits, sem alterações. Você pode solicitar outras codificações com responseFormat.
temperature, topP, topK Ignorado Rejeitado com um erro INVALID_ARGUMENT

Atualizar suas solicitações

  1. Mova as instruções de estilo para speech_metadata.style: os modelos de TTS do Gemini 3.8 leem text como uma transcrição literal. Portanto, as instruções escritas no texto podem ser faladas em voz alta. Coloque instruções de atuação, tom, prosódia e ritmo sustentados em speech_metadata.style.
  2. Use uma parte por turno de diálogo: para diálogos com vários falantes, transmita cada turno como um part separado e defina speech_metadata.speaker em cada turno como um dos falantes em multiSpeakerVoiceConfig.
  3. Substitua tags de colchetes por tags de chaves angulares: use chaves angulares, como <sigh>, <laugh> ou <short pause>, apenas para eventos vocais pontuais. Escreva as disfluências, como "hum", diretamente na transcrição.
  4. Crie personas de design antecipadamente: substitua os comandos longos de "Perfil de áudio" ou "Observações do diretor" por uma voz criada em Design de voz e mantenha style curto ou vazio.
  5. Remova parâmetros sem suporte: remova temperature, topP, topK, candidateCount e systemInstruction das suas solicitações.
  6. Processar saída WAV de solicitações unárias: agora as solicitações unárias retornam um arquivo WAV completo em vez de PCM bruto. Se o código adicionar um cabeçalho WAV ou concatenar clipes, remova a etapa de cabeçalho ou defina generationConfig.responseFormat como AUDIO_L16 para manter a saída PCM bruta.
  7. Recrie vozes replicadas com a API Voices: o áudio de referência inline em replicatedVoiceConfig não é compatível. Crie uma voz armazenada ou uma chave de replicação de voz com a API Voices e transmita-a em voiceConfig.voice. Para mais detalhes, consulte Replicação de voz.

Para mais orientações sobre como escrever comandos, consulte o guia de comandos.

Exemplo

O exemplo a seguir mostra uma solicitação gemini-3.1-flash-tts-preview e a solicitação equivalente de TTS do Gemini 3.8.

Antes do 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 ou versões mais recentes

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

As duas respostas retornam o áudio em response.candidates[0].content.parts[0].inline_data.data. O modelo anterior retorna áudio PCM bruto de 16 bits (24 kHz, mono), e o modelo TTS do Gemini 3.8 retorna um arquivo WAV completo.

Migrar da API Cloud Text-to-Speech

Se você chamar o Gemini TTS pela API Cloud Text-to-Speech (texttospeech.googleapis.com), envie as solicitações para o método generateContent em aiplatform.googleapis.com. A tabela a seguir mapeia os campos de solicitação de API do Cloud Text-to-Speech para os campos de solicitação de API da 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) Uma parte por vez, com text e speechMetadata.speaker
voice.modelName O ID do modelo no URL da solicitação
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 (padrão para solicitações unárias)
audioConfig.audioEncoding: PCM AUDIO_L16 (padrão para solicitações de streaming)
audioConfig.audioEncoding: MULAW ou ALAW. AUDIO_MULAW ou AUDIO_ALAW
audioConfig.audioEncoding: MP3 ou OGG_OPUS. Incompatível. Codifique o áudio no cliente.
audioConfig.sampleRateHertz Incompatível. Para taxas de amostragem de saída, consulte Formatos de saída de áudio.

A API Cloud Text-to-Speech retorna áudio codificado em Base64 em audioContent. A API Gemini Enterprise retorna esse valor em candidates[0].content.parts[0].inlineData.data.

A seguir