Migra a Gemini 3.8 TTS

En esta página, se describe cómo migrar de modelos anteriores de Gemini TTS, como gemini-3.1-flash-tts-preview, gemini-2.5-flash-tts, gemini-2.5-pro-tts y gemini-2.5-flash-lite-preview-tts, a Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) y Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts). Los modelos anteriores se documentan en Gemini-TTS en la documentación de Google CloudText-to-Speech.

Elige un modelo de reemplazo

  • Gemini 3.8 Flash-Lite TTS es el reemplazo recomendado para gemini-3.1-flash-tts-preview. Elige esta opción para la producción de gran volumen, los agentes de voz, las funciones de lectura en voz alta y el habla cotidiana con una sola bocina.
  • Gemini 3.8 Flash TTS es el modelo insignia. Elige esta opción cuando la fidelidad de la voz, los matices de la actuación, el diálogo con varios oradores o la cobertura de dialectos sean lo más importante, como en el caso de los audiolibros y la narración de estudio.

Ambos modelos usan el mismo esquema de solicitud, por lo que puedes cambiar entre ellos modificando el ID del modelo. Para obtener una comparación, consulta Cuándo usar cada modelo.

Resumen de cambios

Área Modelos anteriores de Gemini TTS Modelos de TTS de Gemini 3.8
API API de Cloud Text‑to‑Speech o API de Gemini Enterprise Solo API de Gemini Enterprise (generateContent y streamGenerateContent)
Ubicación global y extremos regionales Solo global
Dirección de estilo Escrito en el texto ("Say the following in a curious way: ...") o en el campo prompt de Cloud Text-to-Speech speech_metadata.style en cada parte
Diálogo con varios oradores Prefijos de orador en un bloque de texto o multiSpeakerMarkup de Cloud Text-to-Speech Una parte por turno con speech_metadata.speaker
Etiquetas vocales intercaladas Corchetes, como [sigh] Corchetes angulares, como <sigh>
Selección de voz prebuiltVoiceConfig.voiceName voiceConfig.voice, que también acepta IDs de voces diseñadas y claves de replicación de voz. prebuiltVoiceConfig.voiceName sigue funcionando para las voces prediseñadas.
Voces personalizadas Audio de referencia intercalado en replicatedVoiceConfig Diseño de voz y replicación de voz a través de la API de Voices
Salida predeterminada (API de Gemini Enterprise) PCM sin procesar de 16 bits, 24 kHz, mono Solicitudes unarias: Un archivo WAV completo (PCM de 16 bits, 24 kHz, mono). Solicitudes de transmisión: PCM sin procesar de 16 bits, sin cambios. Puedes solicitar otras codificaciones con responseFormat.
temperature, topP, topK Omitida Se rechazó con un error INVALID_ARGUMENT

Actualiza tus solicitudes

  1. Mueve las indicaciones de estilo a speech_metadata.style: Los modelos de TTS de Gemini 3.8 leen text como una transcripción literal, por lo que las indicaciones escritas en el texto se pueden leer en voz alta. Coloca instrucciones sostenidas de actuación, tono, prosodia y ritmo en speech_metadata.style.
  2. Usa una parte por turno de diálogo: Para el diálogo con varios interlocutores, pasa cada turno como un part independiente y establece speech_metadata.speaker en cada turno como uno de los interlocutores en multiSpeakerVoiceConfig.
  3. Reemplaza las etiquetas de corchetes por etiquetas de corchetes angulares: Usa corchetes angulares, como <sigh>, <laugh> o <short pause>, solo para eventos vocales en un momento determinado. Escribe las disfluencias, como "eh", directamente en la transcripción.
  4. Diseña arquetipos por adelantado: Reemplaza las indicaciones largas de "Perfil de audio" o "Notas del director" con una voz creada en Diseño de voz y mantén style corto o vacío.
  5. Quita los parámetros no admitidos: Quita temperature, topP, topK, candidateCount y systemInstruction de tus solicitudes.
  6. Controla la salida WAV de las solicitudes unarias: Las solicitudes unarias ahora devuelven un archivo WAV completo en lugar de PCM sin procesar. Si tu código agrega un encabezado WAV o concatena clips, quita el paso del encabezado o configura generationConfig.responseFormat en AUDIO_L16 para conservar la salida de PCM sin procesar.
  7. Recrea voces replicadas con la API de Voices: No se admite el audio de referencia intercalado en replicatedVoiceConfig. Crea una voz almacenada o una clave de replicación de voz con la API de Voices y pásala en voiceConfig.voice. Para obtener más información, consulta Replicación de voz.

Para obtener más orientación sobre cómo escribir instrucciones, consulta la guía de instrucciones.

Ejemplo

En el siguiente ejemplo, se muestran una solicitud de gemini-3.1-flash-tts-preview y la solicitud de TTS de Gemini 3.8 equivalente.

Antes de 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 versiones posteriores

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

Ambas respuestas devuelven el audio en response.candidates[0].content.parts[0].inline_data.data. El modelo anterior devuelve audio PCM sin procesar de 16 bits (24 kHz, mono), y el modelo de TTS de Gemini 3.8 devuelve un archivo WAV completo.

Migra desde la API de Cloud Text‑to‑Speech

Si llamas a Gemini TTS a través de la API de Cloud Text‑to‑Speech (texttospeech.googleapis.com), envía tus solicitudes al método generateContent en aiplatform.googleapis.com. En la siguiente tabla, se asignan los campos de solicitud de Cloud Text-to-Speech a los campos de solicitud a la API de Gemini Enterprise:

API de Cloud Text‑to‑Speech (text:synthesize) API de Gemini Enterprise (generateContent)
input.text contents[].parts[].text
input.prompt contents[].parts[].speechMetadata.style
input.multiSpeakerMarkup.turns[] (speaker, text) Una parte por turno, con text y speechMetadata.speaker
voice.modelName El ID del modelo en la URL de la solicitud
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 (predeterminado para solicitudes unarias)
audioConfig.audioEncoding: PCM AUDIO_L16 (predeterminado para solicitudes de transmisión)
audioConfig.audioEncoding: MULAW o ALAW AUDIO_MULAW o AUDIO_ALAW
audioConfig.audioEncoding: MP3 o OGG_OPUS No compatible. Codifica el audio en el cliente.
audioConfig.sampleRateHertz No compatible. Para conocer las frecuencias de muestreo de salida, consulta Formatos de salida de audio.

La API de Cloud Text‑to‑Speech devuelve audio codificado en Base64 en audioContent. La API de Gemini Enterprise lo devuelve en candidates[0].content.parts[0].inlineData.data.

¿Qué sigue?