Gemini 中文指南
获取 API 密钥 ↗

文本转语音(TTS)

↓ 下载 Markdown

Gemini API 可以使用 Gemini 文本转语音 (TTS) 生成功能将文本输入转换为单扬声器或多扬声器音频。文本到语音的生成是 可控的,这意味着您可以结合结构化转弯元数据(speech_metadata)和内联语音标签来指导 风格, 口音, 步伐, 和 语气 的音频。

在 Google AI Studio 中体验

TTS 功能不同于通过 Live API,专为交互式、非结构化音频以及多模态输入和输出而设计。虽然 Live API 在动态对话环境中表现出色,但 Gemini API 的 TTS 专为需要精确文本背诵以及对风格和声音进行细粒度控制的场景而定制,例如播客或有声读物生成。

本指南向您展示如何使用文本生成单扬声器和多扬声器音频 Gemini 3.8 Flash TTS (gemini-3.8-flash-tts)和 Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

开始之前 #

确保您使用中列出的 Gemini TTS 型号 支持的模型 部分。为了获得最佳结果,请查看 何时使用哪种型号 为您的工作负载选择最佳模型。

您可能会发现它很有用 在 AI Studio 中测试 Gemini TTS 模型 在开始构建之前。

单人 TTS #

要使用 Gemini 3.8 TTS 模型将文本转换为单扬声器音频,请将逐字记录传递到 parts[].text,附加转弯级别样式 parts[].speech_metadata,并在中配置您的声音 speechConfig.voiceConfig。您可以传递预构建的语音名称、扩展语音库 ID、自定义语音 声音设计 或 声音重混 身份证号(voice_...),或一个 声音复刻 身份证号(voice_...,或可选的无状态 voicekey_...).

此示例将模型的输出音频保存在 WAV 文件中:

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.wav", "wb") as f:
    f.write(data)

多扬声器 TTS #

对于多扬声器对话,请配置两个扬声器 multiSpeakerVoiceConfig.speakerVoiceConfigs 使用 prebuiltVoiceConfig 并将每个对话回合作为单独的对话传递 part 使用 speech_metadata 指定两者 speaker 和可选的转动级别 style:

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [
            {
                "text": "How's it going today Jane?",
                "speech_metadata": {
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                },
            },
            {
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "speech_metadata": {
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                },
            },
        ],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "multi_speaker_voice_config": {
                "speaker_voice_configs": [
                    {
                        "speaker": "Joe",
                        "voice_config": {
                            "prebuilt_voice_config": {"voice_name": "Puck"}
                        },
                    },
                    {
                        "speaker": "Jane",
                        "voice_config": {
                            "prebuilt_voice_config": {"voice_name": "Kore"}
                        },
                    },
                ]
            }
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.wav", "wb") as f:
    f.write(data)

使用元数据和标签控制语音风格 #

Gemini 3.8 TTS 对待 text 字段严格作为逐字记录。要在不大声朗读阶段指示的情况下控制交付,请按范围拆分您的指示:

  • 持续的周转级交付(speech_metadata.style): 将适用于整个回合的情感、表达风格、韵律、节奏和音量融入其中 speech_metadata.style (例如, "style": "whispered urgently", "style": "out of breath", 或 "style": "warm and enthusiastic").
  • 时间点事件(内联标签): 使用尖括号将瞬时非语音爆发或停顿直接放置在文字记录中(例如, "Wait... <short pause> did you hear that? <sigh>" 或 "Excuse me <cough> as I was saying...").

请参阅 提示指南 以获得全面的最佳实践。

流式语音生成 #

您可以在模型合成生成的音频块时对它们进行流式传输,以最大限度地缩短实时语音应用程序中的首个音频时间。

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response_stream = client.models.generate_content_stream(
    model="gemini-3.8-flash-lite-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

for chunk in response_stream:
    try:
        data = chunk.candidates[0].content.parts[0].inline_data.data
        # data contains raw PCM bytes (24kHz, 1-channel, 16-bit)
    except (IndexError, AttributeError):
        pass

语音选项 #

Gemini 3.8 TTS 支持五种方式选择或创建语音:

  1. 预建工作室声音: 30 策划的语音如下表所示。
  2. 扩展语音库: 数百种跨语言、口音和角色原型的额外声音可使用 client.voices.list() (GET /v1beta/voices).
  3. 声音设计: 从自然语言描述生成自定义声音角色 Google AI Studio 或使用 POST /v1beta/voices (type="prompted",它返回一个持久的 voice_... 身份证和 sample_audio WAV 预览在 CreateVoice 和 GetVoice).
  4. 声音复刻: 从参考和同意音频中复制说话者的声音 Google AI Studio 或使用 POST /v1beta/voices (type="replicated", 坚持不懈 store=True 默认或可选无状态 store=False).
  5. 声音重混: 修改预建或设计的 base_voice 使用自然语言指令 Google AI Studio 或使用 POST /v1beta/voices (type="prompted", prompted.base_voice,其中存储了一个新的独立的 voice_... 资源并返回 sample_audio WAV 预览)。

自定义语音限制和 TTL #

语音类型存储方式配额/限额保留(TTL)
充满状态的声音 (voice_...、提示或重复)store=True200 每个项目的声音 (在提示和复制的声音之间共享)1 上次使用年份*
无状态语音键 (voicekey_...,复制)store=False客户管理7天

* TTL 扩展: 每次主动使用语音(通过将语音与语音合成或将其用作重新混音的基础语音)时,1 年保留窗口都会重置。 1 年没有活动的语音将被自动删除。

预建声音 #

和风 ——光明冰球 ——乐观卡戎 -- 信息丰富
科雷 -- 公司芬里尔 -- 兴奋勒达 ——青春洋溢
奥鲁斯 -- 公司奥德 ——微风卡里罗 ——随和
奥托诺埃 ——光明土卫二 ——有呼吸土卫八 -- 清除
翁布里埃尔 ——随和阿尔吉巴 -- 光滑德斯皮纳 -- 光滑
Erinome -- 清除阿尔吉尼布 ——碎石拉萨尔盖蒂 -- 信息丰富
劳梅迪亚 ——乐观阿赫纳尔 -- 软阿尔尼拉姆 -- 公司
调度器 ——甚至伽克鲁斯 -- 成熟普切里玛 -- 转发
阿希尔德 -- 友善氐宿一 -- 休闲温德米亚特里克斯 ——温柔
萨达奇比亚 ——活泼萨达尔塔格 ——知识渊博苏拉法特 ——温暖

扩展语音库和过滤 #

除了上表中的 30 特色录音室声音之外, 扩展语音库 提供数百种跨语言、地区口音、角色角色和领域的额外声音。您可以以交互方式浏览、过滤和试听完整的语音库 Google AI Studio,或使用编程方式查询 client.voices.list() (GET /v1beta/voices,使用 google-genai 2.25.0+ / @google/genai 2.24.0+).

ListVoices 返回您自定义存储的语音(按最新顺序排列),然后是符合您的过滤条件的预构建目录语音。当为列表过滤器传递多个值时,语音匹配 任何 返回该过滤器中的值(OR),而不同的过滤器参数结合 AND:

参数类型说明
language_codelist[str]BCP-47 语言标签(例如, ["en-US", "en-GB"])。不区分大小写的精确匹配。
region_codelist[str]ISO 3166-1 alpha-2 或 UN M.49 区域代码(例如, ["US", "GB"]).
accentlist[str]地区口音描述符(例如, ["American", "British"]).
genderlist[str]感知的性别表现("female", "male", 或 "neutral").
pitchlist[str]音调分类("low", "medium", 或 "high").
personalist[str]声音角色或角色原型(例如, ["Warm, Friendly"], ["Narrator"]).
contexts (context 休息时)list[str]最佳使用域(例如, ["Audiobook", "Conversational", "News"]).
type (type_ 在Python中)list[str]按语音源过滤: "prebuilt", "prompted" (声音设计 和 声音重混),或 "replicated" (声音复刻).
searchstr自由文本子字符串搜索不区分大小写地与两者匹配 display_name 和 description.
page_sizeint每页返回的最大语音数(默认 50, 最大 1000).
page_tokenstr代币来自 response.next_page_token 获取下一页结果。
python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

# Filter the Voice Library by language, gender, pitch, domain context, and keyword
response = client.voices.list(
    language_code=["en-US", "en-GB"],
    gender=["female"],
    pitch=["medium", "low"],
    contexts=["Audiobook", "Conversational"],
    type_=["prebuilt"],
    search="warm",
    page_size=50,
)

for voice in response.voices or []:
    print(
        f"{voice.id} | {voice.display_name} ({voice.language_code},"
        f" {voice.accent}, {voice.gender}, pitch={voice.pitch}):"
        f" {voice.description}"
    )

支持的语言 #

TTS 模型自动检测输入语言。 Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) 支持 超过 130 语言, 和 Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) 支持 超过 100 语言:

语言Gemini 3.8 Flash TTSGemini 3.8 Flash-Lite TTS
亚齐语(阿拉伯文字)✔️✔️
南非荷兰语✔️✔️
阿寒✔️✔️
阿姆哈拉语✔️✔️
亚美尼亚语✔️✔️
阿萨姆语✔️✔️
阿瓦迪✔️✔️
巴厘岛人✔️✔️
孟加拉语✔️✔️
班贾尔(阿拉伯文字)✔️—
Banjar(拉丁文字)✔️✔️
巴什基尔语✔️—
巴斯克语✔️✔️
白俄罗斯语✔️✔️
本巴✔️—
博杰普尔✔️✔️
波斯尼亚语✔️✔️
布吉语✔️✔️
保加利亚语✔️✔️
缅甸语✔️—
粤语✔️✔️
加泰罗尼亚语✔️✔️
宿务语✔️✔️
中库尔德语✔️✔️
恰蒂斯加尔邦✔️✔️
中文(汉文)✔️✔️
中文(汉文)✔️✔️
克里米亚鞑靼人✔️—
克罗地亚语✔️✔️
捷克语✔️✔️
丹麦语✔️✔️
荷兰语✔️✔️
迪乌拉✔️—
宗卡✔️—
埃及阿拉伯语✔️✔️
英语✔️✔️
爱沙尼亚语✔️✔️
菲律宾人✔️✔️
芬兰语✔️—
法语✔️✔️
加利西亚语✔️✔️
干达✔️✔️
格鲁吉亚语✔️✔️
德语✔️✔️
希腊语✔️✔️
瓜拉尼语✔️—
古吉拉特语✔️✔️
海地克里奥尔语✔️✔️
哈尔蒙古语✔️✔️
豪萨语✔️✔️
希伯来语✔️✔️
印地语✔️✔️
匈牙利语✔️✔️
冰岛语✔️✔️
伊博语✔️—
伊洛科✔️✔️
印度尼西亚语✔️✔️
伊朗波斯语✔️✔️
意大利语✔️✔️
日语✔️✔️
爪哇语✔️✔️
卡比尔✔️—
康巴✔️✔️
卡纳达语✔️✔️
克什米尔语(阿拉伯文字)✔️✔️
克什米尔语(德瓦文字)✔️✔️
哈萨克语✔️✔️
高棉语✔️✔️
基库尤语✔️✔️
基尼亚卢旺达语✔️✔️
刚果✔️✔️
韩语✔️✔️
吉尔吉斯斯坦✔️✔️
老挝✔️✔️
拉特加利安✔️—
林加拉语✔️✔️
立陶宛语✔️—
卢森堡语✔️—
马其顿语✔️✔️
马加希✔️✔️
迈蒂利✔️✔️
马拉雅拉姆语✔️✔️
马耳他语✔️✔️
曼尼普里✔️✔️
马拉地语✔️✔️
米南加保语(阿拉伯文字)✔️✔️
米南加保语(拉丁文)✔️—
米佐✔️✔️
尼泊尔语(个人语言)✔️✔️
尼日利亚富尔福德✔️✔️
北阿塞拜疆语✔️✔️
北索托✔️✔️
北乌兹别克语✔️✔️
挪威博克马尔语✔️✔️
挪威尼诺斯克语✔️✔️
尼亚尼亚✔️✔️
奥克语✔️—
奥迪亚语(个人语言)✔️✔️
邦阿西南✔️—
波斯语(阿富汗)✔️✔️
波兰语✔️✔️
葡萄牙语✔️✔️
旁遮普语✔️✔️
罗马尼亚语✔️✔️
俄语✔️✔️
桑塔利✔️✔️
塞尔维亚语✔️✔️
信德语✔️—
僧伽罗语✔️✔️
斯洛伐克语✔️✔️
斯洛文尼亚语✔️—
索马里语✔️—
南阿塞拜疆语✔️✔️
南普什图语✔️✔️
南索托语✔️—
西班牙语✔️✔️
标准阿拉伯语(阿拉伯文字)✔️✔️
标准阿拉伯语(拉丁字母)✔️✔️
标准拉脱维亚语✔️✔️
标准马来语✔️✔️
斯瓦希里语(个人语言)✔️—
斯瓦蒂✔️—
瑞典语✔️—
塔吉克族✔️—
泰米尔语✔️✔️
泰卢固语✔️✔️
泰语✔️—
提格里尼亚✔️—
托斯克阿尔巴尼亚语✔️—
土耳其语✔️✔️
维吾尔族✔️—
越南语✔️✔️

支持的模型 #

模型单扬声器多扬声器声音设计声音复刻声音重混
Gemini 3.8 Flash TTS (gemini-3.8-flash-tts)✔️✔️✔️✔️✔️
Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts)✔️✔️✔️✔️✔️
Gemini 3.1 Flash TTS Preview✔️✔️———
Gemini 2.5 Pro Preview TTS✔️✔️———

何时使用哪种型号 #

两个 Gemini 3.8 TTS 模型共享完全相同的 API 架构和提示格式,允许您通过单个参数更改在它们之间切换:

  • 使用 Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) 当最大的声音保真度、细致的表演和表现力的控制是重中之重时。它非常适合工作室级的创意工作、复杂的多发言者对话、沉重的突发声音标签、困难的发音、地方或少数民族方言,以及需要坚如磐石的声音和房间音调稳定性的长篇叙述。
  • 使用 Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) 作为您快速、经济高效的主力替代品 gemini-3.1-flash-tts-preview。它针对大批量批量生产、会话语音智能体级联、朗读功能、可靠的语音复制以及跨主要语言的日常单人语音进行了优化。

迁移指南 #

从早期预览模型升级时(gemini-3.1-flash-tts-preview 或 gemini-2.5-pro-preview-tts) 至 Gemini 3.8 TTS (gemini-3.8-flash-tts 或 gemini-3.8-flash-lite-tts),回顾这五个关键变化:

  1. 将样式与文字记录分开: 移动持续的表演、语气、韵律和节奏指令(例如 "whispering", "out of breath", 或 "speaking slowly") 从纯文本中转换成 speech_metadata.style。保留 text 严格按照逐字记录加上内联声音标签。
  2. 使用语音设计预先设计角色: 替换多段 "Audio Profile" 或 "Director's Notes" 具有在以下位置创建的自定义语音的块 声音设计,然后携带它 voice_... 通过 TTS 请求的 ID 最少或为空 style 字符串。
  3. 使用结构化对话轮流: 对于多发言者对话,请传递一位 part 每个扬声器转动 speech_metadata.speaker 而不是嵌入 Speaker: ... 单个文本块内的前缀。
  4. 使用尖括号作为内联语音标签: 使用尖括号 (<laugh>, <sigh>, <cough>, <breath>, <short pause>)用于人类发声和停顿的时间点。避免使用非声音音效标签(例如掌声或重击声)。
  5. 默认 WAV 帐户(AUDIO_WAV) 一元请求的输出: 不像 gemini-3.1-flash-tts-preview (返回无标头原始 PCM AUDIO_L16 默认),Gemini 3.8 TTS模型返回完整 音频文件(AUDIO_WAV) 在一元请求上带有 RIFF 标头(24 kHz、单声道、16 位 PCM)的音频: * 如果您的代码之前将原始 PCM 字节包装在 WAV 标头中(例如,使用 Python 的 wave 模块或节点 wav 包),删除手动标头包装器并将解码的音频字节直接写入 .wav 文件。
  • 如果您现有的管道需要无头原始 PCM、mu-law 或 A-law 音频,请显式设置 generationConfig.responseFormat.audio.mimeType 到 "AUDIO_L16", "AUDIO_MULAW", 或 "AUDIO_ALAW" 使用 REST API(例如, {"responseFormat": {"audio": {"mimeType": "AUDIO_L16"}}} 在 generateContent;定制 responseFormat 覆盖 generateContent 使用 REST API 支持,而 Python 和 JavaScript SDK 支持 response_format 在 GenerateContentConfig 正在等待,或使用 {"response_format": {"type": "audio", "mime_type": "audio/l16"}} 在 Interactions API 中)。参见 音频输出格式.

提示指南 #

Gemini 3.8 TTS 模型将输入文本严格视为 逐字记录。与以纯文本形式嵌入舞台方向的早期预览模型不同,Gemini 3.8 TTS 将持续的转弯水平方向分开(speech_metadata)来自时间点内联声音标签。

样式字段与内联标签 #

按范围划分绩效说明:

  • 轮级交付(speech_metadata.style): 添加持续交付属性,例如情感、韵律、整体节奏或交付风格(例如 "whispering", "out of breath", "muttering", 或 "sarcastic")——进入 style 的领域 speech_metadata。为了在回合中创造稳定的角色和表现,请预先设计角色 声音设计 并使用 style 仅用于可选的转弯级别调整。
  • 时间点事件(内联标签): 使用尖括号 (<cough>, <breath>, <sigh>, <short pause>)。使用尖括号 (<...>)以获得最高音频质量,并坚持人类发声而不是非声音效果。
适用范围放置在哪里示例
转弯级别 (在转弯时持续)speech_metadata.style"angry tone", "speaking rapidly", "out of breath", "whispers", "sarcastic"
时间点 (出现在特定单词处)内联输入 text (<...>)"<cough> Thank you all for coming tonight! <throat-clearing> As I was saying..."

节奏和停顿 #

您可以在三个粒度级别控制节奏和静音:

  • 标点符号和省略号: 使用逗号、破折号 (--) 和省略号 (...)用于自然对话的犹豫。

  • 内联暂停标签: 插入 <short pause> 或 <long pause> 在脚本中演讲者应该暂停的确切位置:

    text
    Hold on, let me think... <short pause> Alright, I've got it.
    
  • 转弯速度: 套装 "style": "speaking rapidly" 或 "style": "speaking slowly" 在 speech_metadata 控制整个回合的语速。

韵律和音高 #

使用 speech_metadata.style 控制韵律、音调和音调变化(例如, "style": "high pitch, cheerful and excited inflection" 或 "style": "monotone and flat")。如果情感或韵律在对话中发生变化,请将脚本分成单独的回合,并具有不同的回合 style 每回合的值。

强调 #

将文字记录中的特定单词大写,并结合标点符号和内联声音标签,对关键词施加自然的声音重音:

text
This is a VERY important point!
It was a VERY long day <sigh> ... nobody listens anymore.

突发声音和非语音 #

使用尖括号 (<...>)在声音应该出现的确切位置。推荐的声音标签包括:

<argh>

<breath>

<heavy breath>

<exhales>

<cackle>

<cheer>

<chuckle> / <chuckles>

<cough>

<cry>

<gasp>

<giggle>

<groan>

<growl>

<grunt>

<grr>

<hiss>

<laugh> / <laughter>

<moan>

<pant>

<pff> / <phew>

<scream>

<shout>

<shriek>

<sigh> / <sighs>

<sneeze>

<snicker>

<snort>

<sob>

<throat-clearing>

<tsk>

<whimper>

<whispers> / <whispering>

<yawn>

<short pause>

<long pause>

反向通道和重叠语音 #

在多发言者对话中,将听众的反应包装在管道字符中(|reaction|)在发言者的轮次内创建自然的反向通道或重叠语音,而不会根据每个反应中断单独的轮次。

  • 短的反向渠道交换: 分层简短的听众反应(|oh hmm|, |oh really?|, |absolutely|) 在当前发言者的回合内:* 转动1(扬声器A): "So the launch is Thursday |oh hmm| Are we actually ready?"

  • 转动2(扬声器B): "Ready enough |oh really?| The last blocker cleared this morning."

  • 转动3(扬声器A): "Then let's ship it |absolutely| and watch the dashboards."

  • 重叠和交错的语音: 使用多个管道段来模拟两个扬声器之间的同时或交错语音(最适合使用 gemini-3.8-flash-tts): * 同时倒计时/合唱: "Let's surprise him on three |ok| ready?" 随后 "one. two. three. |happy| happy |birthday| birthday!"

  • 扬声器完全重叠: "Hello |oh| there |my| it |goodness| must |gracious| be |would| almost |you| time |look| for |at that| dinner"

各代人的一致性以及应避免的事情 #

请遵循以下准则,以保持声音特性在各个回合中保持稳定:

  • 在语音设计中预先设计角色,而不是冗长的样式块: 长篇 "Audio Profile" 段落和多项目符号 "Director's Notes" 早期型号遗留下来的问题是语音漂移的最常见原因。预先使用相同的创意直觉 声音设计 生成持久的自定义 voice_... 人物角色,然后通过 TTS 呼叫携带该语音 ID。
  • 依靠语音参考来获得稳定性(省略元指令): Gemini 3.8 TTS 模型首先经过训练以锚定音频参考。请勿包含告诉模型保持声音稳定的说明(例如 "do not switch speaker identity" 或 "maintain identical timbre")—额外的提示文本会增加漂移。删除不必要的样式指令,让模型围绕语音参考提供的稳定点自然变化。
  • 不要尝试改变不可变的说话者特征 style: 避免将年龄、性别、姓名或永久性口音变化纳入其中 speech_metadata.style。相反,从扩展语音库中选择一种区域语音或使用以下命令创建一个 声音设计.
  1. 构建角色一次: 创建你的角色 声音设计 或者从扩展语音库中选择与您的目标语言和角色相匹配的区域语音。
  2. 写出自然但不流利的口语记录: 为了获得最大的自然度,请写下 text 作为真实的口语记录——包括自然的对话不流畅和犹豫(例如, "Oh uh yeah I think... hm, so that's interesting").
  3. 首先测试纯 TTS: 用空的合成你的成绩单 style 字段优先——大多数请求不需要 style 根本没有指导。
  4. 添加短 style 仅提示进行调整: 添加一个简洁的 style 字符串(例如 "casual, friendly" 或 "muttering, then reassuring")仅适用于需要特定传递调整的转弯,并且当您需要一致的基线时,可以在转弯之间重复使用该确切的短字符串。

多轮对话和语音智能体 #

构建实时会话语音智能体或多轮应用程序时:

  • 制造 每回合一次 TTS 通话 当 LLM 文本块到达时。
  • 让配置好的 voice (预建、设计 voice_...,或复制 voice_... / voicekey_...)在各个回合中携带说话者的身份 - 切勿在每个回合中重新发送长字符角色。
  • 离开每回合 style 字段为空,或者发送一个短常量字符串(例如 "casual, friendly") 整个对话。
  • 将较长的智能体响应拆分为较短的回合,而不是寻求更强的风格提示。

音频输出格式 #

Gemini 3.8 TTS 模型根据请求是一元还是流式传输而使用不同的默认音频格式:

  • 一元请求 (models.generate_content): 返回完成 音频文件(AUDIO_WAV) 带有 RIFF 标头的音频(24 kHz、单声道、16 位签名的小端 PCM)。您可以将解码后的音频字节直接写入 .wav 文件,无需手动添加 WAV 容器。
  • 流式传输请求(models.generate_content_stream / streamGenerateContent): 返回 无标头原始线性 PCM (AUDIO_L16) 默认情况下,块(24 kHz、单声道、16 位签名的小端 PCM)因此可以连续流式传输或连接块,每个块上没有容器标头。

您可以使用以下命令覆盖输出音频编码和采样率 generationConfig.responseFormat.audio:

mimeType 值格式说明
"AUDIO_WAV" (一元默认值)音频文件(audio/wav)带有 RIFF 标头的完整 WAV 文件(24 kHz、单声道、16 位 PCM)。
"AUDIO_L16" (默认流媒体)线性PCM(audio/l16)无标头原始 16 位签名小端线性 PCM。最适合流式传输、自定义音频管道或连接多轮剪辑。
"AUDIO_MULAW"μ 律 (audio/basic / audio/mulaw)G.711 µ 律压扩音频。常用于北美和日本电话 (8 kHz)。
"AUDIO_ALAW"A 律 (audio/alaw)G.711 A 律压扩音频。常用于欧洲和国际电话 (8 kHz)。

您还可以选择指定 sampleRate (例如, 24000, 16000, 或 8000 赫兹;默认为 24000 赫兹)。

以下 REST 示例请求无标头原始 16 位 PCM(AUDIO_L16) 在 24 kHz 处:

sh
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "contents": [{
          "role": "user",
          "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {
              "style": "cheerful and friendly"
            }
          }]
        }],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "responseFormat": {
            "audio": {
              "mimeType": "AUDIO_L16",
              "sampleRate": 24000
            }
          },
          "speechConfig": {
            "voiceConfig": {
              "voice": "Kore"
            }
          }
        }
    }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
          base64 --decode > out.pcm

限制 #

  • TTS 模型接受纯文本输入并生成纯音频输出。

  • 单请求多扬声器生成(multiSpeakerVoiceConfig)支持使用预建语音的最多 2 扬声器。结合定制设计(voice_...) 或复制 (voice_... / voicekey_...)多角色对话中的声音,单独合成每个说话者的回合。因为一元请求返回 audio/wav 默认情况下,带有 44 字节 RIFF 标头,请求原始 PCM (AUDIO_L16)或在连接 24kHz PCM 音频帧之前从每个回合中剥离 WAV 标头。

  • 自定义语音存储限制和 TTL: * 有状态的声音(store=True,提示或复制): 最多为 200 每个项目的声音 与一个 1年TTL (生存时间)。

  • 无状态语音键(store=False, voicekey_...): 7 天 TTL (生存时间)。

  • 回顾 支持的语言 语言覆盖部分。

后续步骤 #

搜索标题、API 名称或正文内容