Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

迁移到 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`
样式方向	写入文本 (`"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` 错误而被拒

更新请求

将样式指令移至 speech_metadata.style：Gemini 3.8 TTS 模型会将 text 读作逐字转写，因此写入文本的指令可能会被大声朗读。将持续表演、语气、韵律和节奏指令放在 speech_metadata.style 中。
在每个对话回合中使用一个部分：对于多说话人对话，请将每个回合作为单独的 part 传递，并将每个回合的 speech_metadata.speaker 设置为 multiSpeakerVoiceConfig 中的一个说话人。
将方括号标记替换为尖括号标记：仅针对时间点上的声音事件使用尖括号，例如 <sigh>、<laugh> 或 <short pause>。直接在转写内容中写入不流畅的表达，例如“嗯”。
预先设计角色：使用在语音设计中创建的语音替换冗长的“音频配置文件”或“导演注释”提示，并使 style 保持简短或为空。
移除不受支持的参数：从请求中移除 temperature、topP、topK、candidateCount 和 systemInstruction。
处理来自一元请求的 WAV 输出：一元请求现在会返回完整的 WAV 文件，而不是原始 PCM。如果您的代码添加了 WAV 标头或串联了剪辑，请移除标头步骤，或将 generationConfig.responseFormat 设置为 AUDIO_L16 以保留原始 PCM 输出。
使用 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 会以 base64 编码音频的形式返回 audioContent。 Gemini Enterprise API 会在 candidates[0].content.parts[0].inlineData.data 中返回该值。

后续步骤

不妨试试 Gemini TTS 概览中的示例。
如需了解如何指导风格和声音，请参阅提示指南。