遷移至 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)。先前的模型記錄在 Cloud de Confiance by S3NS「Text-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 總覽中的範例。
請參閱提示指南，瞭解如何引導風格和聲音。