遷移至 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>。直接在轉錄稿中寫下不流暢的語句，例如「嗯」。
  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 中傳回。

後續步驟