迁移到 Gemini 3.8 TTS

本页面介绍了如何从早期 Gemini TTS 模型（例如 gemini-3.1-flash-tts-preview、gemini-2.5-flash-tts、gemini-2.5-pro-tts 和 gemini-2.5-flash-lite-preview-tts）迁移到 Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) 和 Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts)。如需了解早期模型，请参阅 Google CloudText-to-Speech 文档中的 Gemini-TTS。

选择换货型号

  • 建议使用 Gemini 3.8 Flash-Lite TTS 替代 gemini-3.1-flash-tts-preview。适用于大规模生产、语音智能体、大声朗读功能和日常单人语音。
  • Gemini 3.8 Flash TTS 是旗舰模型。当语音保真度、表演细微差别、多说话者对话或方言覆盖范围最重要时（例如有声读物和录音室旁白），请选择此模型。

这两个模型使用相同的请求架构，因此您可以通过更改模型 ID 在它们之间切换。如需进行比较，请参阅何时使用哪种模型。

变更摘要

区 早期 Gemini TTS 模型 Gemini 3.8 TTS 模型
API Cloud Text-to-Speech API 或 Gemini Enterprise API 仅限 Gemini Enterprise API（generateContent 和 streamGenerateContent）
位置 global 和区域端点 global、us和eu（自定义语音：仅限global）
风格方向 写入文本 ("Say the following in a curious way: ...") 或 Cloud Text-to-Speech prompt 字段 每个部分 speech_metadata.style
多角色对白 一个文本块中的说话者前缀，或 Cloud Text-to-Speech multiSpeakerMarkup 每回合一个部分，共 speech_metadata.speaker
内嵌人声标记 方括号，例如 [sigh] 尖括号，例如 <sigh>
语音选择 prebuiltVoiceConfig.voiceName voiceConfig.voice，该模型也接受指定的语音 ID 和语音复刻密钥。prebuiltVoiceConfig.voiceName 仍适用于预构建的声音。
自定义语音 replicatedVoiceConfig中的内嵌参考音频 通过 Voices API 进行语音设计和语音复刻
默认输出 (Gemini Enterprise API) 原始 16 位 PCM，24 kHz，单声道 一元请求：完整的 WAV 文件（16 位 PCM、24 kHz、单声道）。流式请求：原始 16 位 PCM，保持不变。您可以使用 responseFormat 请求其他编码。
temperature、topP、topK 忽略 因 INVALID_ARGUMENT 错误而被拒

更新您的请求

  1. 将风格指令移至 speech_metadata.style：Gemini 3.8 TTS 模型会将 text 视为逐字转写，因此写入文本中的指令可能会被大声朗读。将持续的表演、语气、韵律和节奏指示放在 speech_metadata.style 中。
  2. 每个对话轮次使用一个部分：对于多说话人对话，请将每个轮次作为单独的 part 传递，并将每个轮次的 speech_metadata.speaker 设置为 multiSpeakerVoiceConfig 中的一个说话人。
  3. 将方括号标记替换为尖括号标记：仅对时间点发声事件使用尖括号，例如 <sigh>、<laugh> 或 <short pause>。直接在转写内容中写入不流畅的语音，例如“uhm”。
  4. 预先设计角色：将冗长的“音频配置文件”或“导演笔记”提示替换为在语音设计中创建的语音，并使 style 保持简短或留空。
  5. 移除不受支持的参数：从请求中移除 temperature、topP、topK、candidateCount 和 systemInstruction。
  6. 处理一元请求的 WAV 输出：一元请求现在会返回完整的 WAV 文件，而不是原始 PCM。如果您的代码添加了 WAV 标头或串联了片段，请移除标头步骤，或将 generationConfig.responseFormat 设置为 AUDIO_L16 以保留原始 PCM 输出。
  7. 使用 Voices API 重新创建复制的声音：replicatedVoiceConfig 中的内嵌参考音频不受支持。使用 Voices API 创建存储的语音或语音复刻密钥，并在 voiceConfig.voice 中传递该密钥。如需了解详情，请参阅语音复刻。

如需有关撰写提示的更多指导，请参阅提示指南。

示例

以下示例展示了 gemini-3.1-flash-tts-preview 请求和等效的 Gemini 3.8 TTS 请求。

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 或更高版本

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

两个回答均以 response.candidates[0].content.parts[0].inline_data.data 格式返回音频。早期模型返回原始 16 位 PCM 音频（24 kHz，单声道），而 Gemini 3.8 TTS 模型返回完整的 WAV 文件。

从 Cloud Text-to-Speech API 迁移

如果您通过 Cloud Text-to-Speech API (texttospeech.googleapis.com) 调用 Gemini TTS，请改为将请求发送到 aiplatform.googleapis.com 上的 generateContent 方法。下表将 Cloud Text-to-Speech 请求字段映射到 Gemini Enterprise API 请求字段：

Cloud Text-to-Speech API (text:synthesize) Gemini Enterprise API (generateContent)
input.text contents[].parts[].text
input.prompt contents[].parts[].speechMetadata.style
input.multiSpeakerMarkup.turns[]（speaker、text） 每轮一个部分，包含 text 和 speechMetadata.speaker
voice.modelName 请求网址中的模型 ID
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（一元请求的默认值）
audioConfig.audioEncoding：PCM AUDIO_L16（流式传输请求的默认值）
audioConfig.audioEncoding：MULAW 或 ALAW AUDIO_MULAW 或 AUDIO_ALAW
audioConfig.audioEncoding：MP3 或 OGG_OPUS 不受支持。在客户端上对音频进行编码。
audioConfig.sampleRateHertz 不受支持。如需了解输出采样率，请参阅音频输出格式。

Cloud Text-to-Speech API 会在 audioContent 中返回 base64 编码的音频。 Gemini Enterprise API 会在 candidates[0].content.parts[0].inlineData.data 中返回该内容。

后续步骤