# 文本转语音（TTS）

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

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

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

## 开始之前  {% class="hide-from-toc" #before-you-begin %}

确保您使用中列出的 Gemini TTS 型号 [支持的模型](/docs/speech-generation#supported-models) 部分，并升级到最新的Google GenAI SDK（`google-genai >= 2.25.0` 对于 Python 或 `@google/genai >= 2.24.0` 对于 JavaScript/TypeScript）或使用 REST API。为了获得最佳结果，请查看 [何时使用哪种型号](/docs/speech-generation#when-to-use-which-model) 为您的工作负载选择最佳模型。

您可能会发现它很有用 [在 AI Studio 中测试 Gemini TTS 模型](https://aistudio.google.com/generate-speech)
在开始构建之前。

{% callout type="note" %}
TTS 模型接受纯文本输入并生成纯音频输出。有关特定于 TTS 模型的限制的完整列表，请查看 [限制](/docs/speech-generation#limitations) 部分。
{% /callout %}

## 单人 TTS  {% #single-speaker %}

要使用 Gemini 3.8 TTS 模型将文本转换为单扬声器音频，请将逐字记录传递到 `input`，使用 `speech_metadata` 注释，并在中配置您的声音 `generation_config.speech_config`。您可以从预先构建的声音中选择一个声音 [语音选项](/docs/speech-generation#voices)，扩展语音库（`GET /v1beta/voices`），一个自定义 [声音设计](/docs/voice-design) 或 [声音重混](/docs/voice-remixing) 身份证号（`voice_...`），或一个 [声音复刻](/docs/voice-replication) 身份证号（`voice_...`，或可选的无状态 `voicekey_...`).

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

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import {GoogleGenAI} from '@google/genai';
import * as fs from 'node:fs';

async function main() {
   const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}
await main();
```
{% /tab %}

{% tab label="REST" %}
```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
       "type": "audio"
     },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav
```
{% /tab %}

{% tab label="CLI" %}
```bash
# Note: tts does not send speech_metadata style annotations.
gemini-api tts 'Have a wonderful day!' --voice Kore --out out.wav
```
{% /tab %}
{% /tabs %}

在Python和JavaScript SDK中，您可以使用以下方法检索生成的音频数据 `interaction.output_audio` 便利属性，它返回最后生成的音频块（在原始 REST JSON 响应中，base64 编码的音频存储在 `steps[].content[].data`).

## 多扬声器 TTS  {% #multi-speaker %}

对于多扬声器对话，请配置两个扬声器 `speech_config.speakers`
并将每个回合作为一个单独的文本项传递 `speech_metadata` 注释指定 `speaker` 和可选的转动级别 `style`。请注意 `speech_config` 接受一个数组 (`[{"voice": "..."}]`）用于单扬声器生成和对象（`{"speakers": [...]}`) 对于多说话者生成：

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "How's it going today Jane?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                }],
            },
            {
                "type": "text",
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Joe", "voice": "Puck"},
                {"speaker": "Jane", "voice": "Kore"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import {GoogleGenAI} from '@google/genai';
import * as fs from 'node:fs';

async function main() {
   const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: "How's it going today Jane?",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Joe',
                  style: 'cheerful and friendly',
               }],
            },
            {
               type: 'text',
               text: 'Not too bad, how about you? Ready to test these new voices?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Jane',
                  style: 'calm and relaxed',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Joe', voice: 'Puck' },
               { speaker: 'Jane', voice: 'Kore' },
            ],
         },
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}

await main();
```
{% /tab %}

{% tab label="REST" %}
```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gemini-3.8-flash-tts",
  "input": [{
    "type": "user_input",
    "content": [
      {
        "type": "text",
        "text": "How'\''s it going today Jane?",
        "annotations": [{
          "type": "speech_metadata",
          "speaker": "Joe",
          "style": "cheerful and friendly"
        }]
      },
      {
        "type": "text",
        "text": "Not too bad, how about you? Ready to test these new voices?",
        "annotations": [{
          "type": "speech_metadata",
          "speaker": "Jane",
          "style": "calm and relaxed"
        }]
      }
    ]
  }],
  "response_format": {
       "type": "audio"
     },
  "generation_config": {
    "speech_config": {
      "speakers": [
        { "speaker": "Joe", "voice": "Puck" },
        { "speaker": "Jane", "voice": "Kore" }
      ]
    }
  }
}'
```
{% /tab %}

{% tab label="CLI" %}
```bash
# Note: tts does not send per-turn speech_metadata style annotations.
gemini-api tts "Joe: How's it going today Jane? Jane: Not too bad, how about you? Ready to test these new voices?" \
  --multi-speaker "Joe=Puck,Jane=Kore" --out out.wav
```
{% /tab %}
{% /tabs %}

## 使用元数据和标签控制语音风格  {% #controllable %}

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

* **持续的周转级交付（`speech_metadata.style`):** 将适用于整个回合的情感、表达风格、韵律、节奏和音量放入 `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..."`).

请参阅 [提示指南](/docs/speech-generation#prompting-guide) 以获得全面的最佳实践。

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Dr. Anya",
                    "style": "whispered urgently",
                }],
            },
            {
                "type": "text",
                "text": "<gasp> No way! <laugh> We've been searching for this species all season!",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Liam",
                    "style": "warm and enthusiastic",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Dr. Anya", "voice": "Kore"},
                {"speaker": "Liam", "voice": "Puck"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: 'Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Dr. Anya',
                  style: 'whispered urgently',
               }],
            },
            {
               type: 'text',
               text: "<gasp> No way! <laugh> We've been searching for this species all season!",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Liam',
                  style: 'warm and enthusiastic',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Dr. Anya', voice: 'Kore' },
               { speaker: 'Liam', voice: 'Puck' },
            ],
         },
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}

await main();
```
{% /tab %}

{% tab label="REST" %}
```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Dr. Anya",
            "style": "whispered urgently"
          }]
        },
        {
          "type": "text",
          "text": "<gasp> No way! <laugh> We'\''ve been searching for this species all season!",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Liam",
            "style": "warm and enthusiastic"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "speakers": [
          { "speaker": "Dr. Anya", "voice": "Kore" },
          { "speaker": "Liam", "voice": "Puck" }
        ]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## 流式语音生成  {% #streaming %}

您可以通过设置在合成时流式传输生成的音频 `stream: true`。与一元请求（返回带有 RIFF 标头的完整 WAV 文件）不同， **流请求返回无标头原始 16 位签名小端线性 PCM（`audio/l16`，24 kHz，单声道）默认块** 因此音频块可以连续播放或连接，而无需容器标头。

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

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

stream = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "audio":
            audio_data = base64.b64decode(event.delta.data)
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

   const stream = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
      stream: true,
   });

   for await (const event of stream) {
      if (event.event_type === 'step.delta') {
         if (event.delta.type === 'audio' && event.delta.data) {
            const audioBuffer = Buffer.from(event.delta.data, 'base64');
            // Process the audio buffer
         }
      }
   }
}
await main();
```
{% /tab %}

{% tab label="REST" %}
```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    },
    "stream": true
  }'
```
{% /tab %}
{% /tabs %}

## 音频输出格式  {% #audio-output-formats %}

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

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

您可以覆盖输出音频编码和采样率 `response_format`:

| `mime_type` 值           | 格式    | 说明                                         |
| ----------------------- | ----- | ------------------------------------------ |
| `"audio/wav"` *（一元默认值）* | WAV   | 带有 RIFF 标头的完整 WAV 文件（24 kHz、单声道、16 位 PCM）。 |
| `"audio/l16"` *（默认流媒体）* | 线性PCM | 无标头原始 16 位有符号小端线性 PCM（24 kHz，单声道）。流请求的默认值。 |
| `"audio/mulaw"`         | μ律    | G.711 µ 律压扩音频。常用于北美和日本电话 (8 kHz)。          |
| `"audio/alaw"`          | A律    | G.711 A 律压扩音频。常用于欧洲和国际电话 (8 kHz)。          |

您还可以选择指定 `sample_rate` （例如， `24000`, `16000`, 或 `8000` 赫兹；默认为 `24000` 赫兹）。

以下示例请求无标头原始 16 位 PCM（`audio/l16`) 在 24 kHz 处：

{% tabs %}
{% tab label="Python" %}
```python
import base64
from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={
        "type": "audio",
        "mime_type": "audio/l16",
        "sample_rate": 24000,
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.pcm", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import {GoogleGenAI} from '@google/genai';
import * as fs from 'node:fs';

async function main() {
   const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: {
         type: 'audio',
         mime_type: 'audio/l16',
         sample_rate: 24000,
      },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.pcm', audioBuffer);
   }
}
await main();
```
{% /tab %}

{% tab label="REST" %}
```sh
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio",
      "mime_type": "audio/l16",
      "sample_rate": 24000
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'
```
{% /tab %}
{% /tabs %}

## 语音选项  {% #voices %}

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

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

### 自定义语音限制和 TTL  {% #custom-voice-limits %}

| 语音类型                            | 存储方式          | 配额/限额                           | 保留（TTL）                           |
| ------------------------------- | ------------- | ------------------------------- | --------------------------------- |
| **充满状态的声音** (`voice_...`、提示或重复） | `store=True`  | **200 每个项目的声音** （在提示和复制的声音之间共享） | **1 上次使用年份**{% sup %}\*{% /sup %} |
| **无状态语音键** (`voicekey_...`，复制）  | `store=False` | 客户管理                            | **7天**                            |

{% sup %}\*{% /sup %} **TTL 扩展：** 每次主动使用语音（通过将语音与语音合成或将其用作重新混音的基础语音）时，1 年保留窗口都会重置。 1 年没有活动的语音将被自动删除。

### 预建声音  {% #prebuilt-voices %}

{% doc-table %}
{% doc-row header="true" %}
{% doc-cell %}
**和风** -- *明亮*
{% /doc-cell %}

{% doc-cell %}
**冰球** -- *乐观*
{% /doc-cell %}

{% doc-cell %}
**卡戎** -- *信息丰富*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**科雷** -- *公司*
{% /doc-cell %}

{% doc-cell %}
**芬里尔** -- *兴奋的*
{% /doc-cell %}

{% doc-cell %}
**勒达** -- *青春活力*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**奥鲁斯** -- *公司*
{% /doc-cell %}

{% doc-cell %}
**奥德** -- *微风*
{% /doc-cell %}

{% doc-cell %}
**卡里罗** -- *随和*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**奥托诺埃** -- *明亮*
{% /doc-cell %}

{% doc-cell %}
**土卫二** -- *呼吸*
{% /doc-cell %}

{% doc-cell %}
**土卫八** -- *清除*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**翁布里埃尔** -- *随和*
{% /doc-cell %}

{% doc-cell %}
**阿尔吉巴** -- *光滑*
{% /doc-cell %}

{% doc-cell %}
**德斯皮纳** -- *光滑*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**Erinome** -- *清除*
{% /doc-cell %}

{% doc-cell %}
**阿尔吉尼布** -- *碎石*
{% /doc-cell %}

{% doc-cell %}
**拉萨尔盖蒂** -- *信息丰富*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**劳梅迪亚** -- *乐观*
{% /doc-cell %}

{% doc-cell %}
**阿赫纳尔** -- *软*
{% /doc-cell %}

{% doc-cell %}
**阿尔尼拉姆** -- *公司*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**调度器** -- *甚至*
{% /doc-cell %}

{% doc-cell %}
**伽克鲁斯** -- *成熟*
{% /doc-cell %}

{% doc-cell %}
**普切里玛** -- *前进*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**阿希尔德** -- *友善*
{% /doc-cell %}

{% doc-cell %}
**氐宿一** -- *休闲*
{% /doc-cell %}

{% doc-cell %}
**温德米亚特里克斯** -- *温柔*
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**萨达奇比亚** -- *热闹*
{% /doc-cell %}

{% doc-cell %}
**萨达尔塔格** -- *知识渊博*
{% /doc-cell %}

{% doc-cell %}
**苏拉法特** -- *温暖*
{% /doc-cell %}
{% /doc-row %}
{% /doc-table %}

### 扩展语音库和过滤  {% #voice-library %}

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

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

| 参数                         | 类型          | 说明                                                                                                                                                 |
| -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `language_code`            | `list[str]` | BCP-47 语言标签（例如， `["en-US", "en-GB"]`）。不区分大小写的精确匹配。                                                                                                 |
| `region_code`              | `list[str]` | ISO 3166-1 alpha-2 或 UN M.49 区域代码（例如， `["US", "GB"]`).                                                                                             |
| `accent`                   | `list[str]` | 地区口音描述符（例如， `["American", "British"]`).                                                                                                            |
| `gender`                   | `list[str]` | 感知的性别表现（`"female"`, `"male"`, 或 `"neutral"`).                                                                                                      |
| `pitch`                    | `list[str]` | 音调分类（`"low"`, `"medium"`, 或 `"high"`).                                                                                                             |
| `persona`                  | `list[str]` | 声音角色或角色原型（例如， `["Warm, Friendly"]`, `["Narrator"]`).                                                                                               |
| `contexts` (`context` 休息时） | `list[str]` | 最佳使用域（例如， `["Audiobook", "Conversational", "News"]`).                                                                                              |
| `type` (`type_` 在Python中）  | `list[str]` | 按语音源过滤： `"prebuilt"`, `"prompted"` ([声音设计](/docs/voice-design) 和 [声音重混](/docs/voice-remixing)），或 `"replicated"` ([声音复刻](/docs/voice-replication)). |
| `search`                   | `str`       | 自由文本子字符串搜索不区分大小写地与两者匹配 `display_name` 和 `description`.                                                                                             |
| `page_size`                | `int`       | 每页返回的最大语音数（默认 `50`, 最大 `1000`).                                                                                                                    |
| `page_token`               | `str`       | 代币来自 `response.next_page_token` 获取下一页结果。                                                                                                           |

{% tabs %}
{% tab label="Python" %}
```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}"
    )
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

// Filter the Voice Library by language, gender, pitch, domain context, and keyword
const response = await ai.voices.list({
  language_code: ["en-US", "en-GB"],
  gender: ["female"],
  pitch: ["medium", "low"],
  contexts: ["Audiobook", "Conversational"],
  type: ["prebuilt"],
  search: "warm",
  page_size: 50,
});

for (const voice of response.voices ?? []) {
  console.log(
    `${voice.id} | ${voice.display_name} (${voice.language_code}, ${voice.accent}, ${voice.gender}, pitch=${voice.pitch}): ${voice.description}`
  );
}
```
{% /tab %}

{% tab label="REST" %}
```sh
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB" \
  --data-urlencode "gender=female" \
  --data-urlencode "pitch=medium" \
  --data-urlencode "context=Audiobook" \
  --data-urlencode "type=prebuilt" \
  --data-urlencode "search=warm" \
  --data-urlencode "page_size=50"
```
{% /tab %}
{% /tabs %}

## 支持的语言  {% #languages %}

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

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

## 支持的模型  {% #supported-models %}

| 模型                                                                                                | 单扬声器 | 多扬声器 | 声音设计 | 声音复刻 | 声音重混 |
| ------------------------------------------------------------------------------------------------- | ---- | ---- | ---- | ---- | ---- |
| [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts) (`gemini-3.8-flash-tts`)                | ✔️   | ✔️   | ✔️   | ✔️   | ✔️   |
| [Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts) (`gemini-3.8-flash-lite-tts`) | ✔️   | ✔️   | ✔️   | ✔️   | ✔️   |
| [Gemini 3.1 Flash TTS Preview](/docs/models/gemini-3.1-flash-tts-preview)                         | ✔️   | ✔️   | —    | —    | —    |
| [Gemini 2.5 Pro Preview TTS](/docs/models/gemini-2.5-pro-preview-tts)                             | ✔️   | ✔️   | —    | —    | —    |

### 何时使用哪种型号  {% #when-to-use-which-model %}

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

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

### 迁移指南  {% #migration %}

从早期预览模型升级时（`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` 严格按照逐字记录加上内联声音标签。
1. **使用语音设计预先设计角色：** 替换多段 `"Audio Profile"` 或 `"Director's Notes"` 具有在以下位置创建的自定义语音的块 [声音设计](/docs/voice-design)，然后携带它 `voice_...` 通过 TTS 请求的 ID 最少或为空 `style` 字符串。
1. **使用结构化对话轮流：** 对于多发言者对话，请传递一位 `content` 每个扬声器转动的项目 `speech_metadata.speaker` 而不是嵌入 `Speaker: ...` 单个文本块内的前缀。
1. **使用尖括号作为内联语音标签：** 使用尖括号 (`<laugh>`, `<sigh>`, `<cough>`, `<breath>`, `<short pause>`）用于人类发声和停顿的时间点。避免使用非声音音效标签（例如掌声或重击声）。
1. **默认 WAV 帐户（`audio/wav`) 一元请求的输出：** 不像 `gemini-3.1-flash-tts-preview` （返回无标头原始 PCM `audio/l16` 默认），Gemini 3.8 TTS模型返回完整 **音频文件（`audio/wav`)** 根据一元请求，带有 RIFF 标头（24 kHz、单声道、16 位 PCM）的音频。您可以将解码后的音频字节直接写入 `.wav` 文件，无需用 Python 手动包装它们 `wave` 模块或节点 `wav`
   包。如果您现有的管道需要无头原始 PCM、mu-law 或 A-law 音频，请显式设置 `response_format.mime_type` 到 `"audio/l16"`, `"audio/mulaw"`, 或 `"audio/alaw"` （例如， `{"response_format": {"type": "audio", "mime_type": "audio/l16"}}` 在 Interactions API 中，或 `AUDIO_L16` 在 `generateContent`;看到 [音频输出格式](/docs/speech-generation#audio-output-formats)).

## 提示指南  {% #prompting-guide %}

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

### 样式字段与内联标签  {% #style-vs-inline-tags %}

按范围划分绩效说明：

* **轮级交付（`speech_metadata.style`):** 添加持续交付属性，例如情感、韵律、整体节奏或交付风格（例如 `"whispering"`, `"out of breath"`, `"muttering"`, 或 `"sarcastic"`)——进入 `style` 的领域 `speech_metadata`。为了在回合中创造稳定的角色和表现，请预先设计角色 [声音设计](/docs/voice-design) 并使用 `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..."`   |

### 节奏和停顿  {% #pacing-and-pauses %}

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

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

* **内联暂停标签：** 插入 `<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` 控制整个回合的语速。

### 韵律和音高  {% #prosody-and-pitch %}

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

### 强调  {% #emphasis %}

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

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

### 突发声音和非语音  {% #vocal-bursts %}

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

{% doc-table %}
{% doc-row header="true" %}
{% doc-cell %}
`<argh>`
{% /doc-cell %}

{% doc-cell %}
`<breath>`
{% /doc-cell %}

{% doc-cell %}
`<heavy breath>`
{% /doc-cell %}

{% doc-cell %}
`<exhales>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<cackle>`
{% /doc-cell %}

{% doc-cell %}
`<cheer>`
{% /doc-cell %}

{% doc-cell %}
`<chuckle>` / `<chuckles>`
{% /doc-cell %}

{% doc-cell %}
`<cough>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<cry>`
{% /doc-cell %}

{% doc-cell %}
`<gasp>`
{% /doc-cell %}

{% doc-cell %}
`<giggle>`
{% /doc-cell %}

{% doc-cell %}
`<groan>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<growl>`
{% /doc-cell %}

{% doc-cell %}
`<grunt>`
{% /doc-cell %}

{% doc-cell %}
`<grr>`
{% /doc-cell %}

{% doc-cell %}
`<hiss>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<laugh>` / `<laughter>`
{% /doc-cell %}

{% doc-cell %}
`<moan>`
{% /doc-cell %}

{% doc-cell %}
`<pant>`
{% /doc-cell %}

{% doc-cell %}
`<pff>` / `<phew>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<scream>`
{% /doc-cell %}

{% doc-cell %}
`<shout>`
{% /doc-cell %}

{% doc-cell %}
`<shriek>`
{% /doc-cell %}

{% doc-cell %}
`<sigh>` / `<sighs>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<sneeze>`
{% /doc-cell %}

{% doc-cell %}
`<snicker>`
{% /doc-cell %}

{% doc-cell %}
`<snort>`
{% /doc-cell %}

{% doc-cell %}
`<sob>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<throat-clearing>`
{% /doc-cell %}

{% doc-cell %}
`<tsk>`
{% /doc-cell %}

{% doc-cell %}
`<whimper>`
{% /doc-cell %}

{% doc-cell %}
`<whispers>` / `<whispering>`
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
`<yawn>`
{% /doc-cell %}

{% doc-cell %}
`<short pause>`
{% /doc-cell %}

{% doc-cell %}
`<long pause>`
{% /doc-cell %}
{% /doc-row %}
{% /doc-table %}

{% callout type="note" %}
如果您的成绩单是非英语语言，请继续使用英语内嵌标签以获得最佳效果。
{% /callout %}

### 反向通道和重叠语音  {% #backchannels %}

在多发言者对话中，将听众的反应包装在管道字符中（`|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"`

### 各代人的一致性以及应避免的事情  {% #consistency-and-what-to-avoid %}

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

* **在语音设计中预先设计角色，而不是冗长的样式块：**
  长篇 `"Audio Profile"` 段落和多项目符号 `"Director's Notes"`
  早期型号遗留下来的问题是语音漂移的最常见原因。预先使用相同的创意直觉 [声音设计](/docs/voice-design) 生成持久的自定义 `voice_...` 人物角色，然后通过 TTS 呼叫携带该语音 ID。
* **依靠语音参考来获得稳定性（省略元指令）：**
  Gemini 3.8 TTS 模型首先经过训练以锚定音频参考。请勿包含告诉模型保持声音稳定的说明（例如 `"do not switch speaker identity"` 或 `"maintain identical timbre"`)—额外的提示文本会增加漂移。删除不必要的样式指令，让模型围绕语音参考提供的稳定点自然变化。
* **不要尝试改变不可变的说话者特征 `style`:** 避免将年龄、性别、姓名或永久性口音变化纳入其中 `speech_metadata.style`。相反，从扩展语音库中选择一种区域语音或使用以下命令创建一个 [声音设计](/docs/voice-design).

### 推荐的工作流程  {% #recommended-workflow %}

1. **构建角色一次：** 创建你的角色 [声音设计](/docs/voice-design) 或者从扩展语音库中选择与您的目标语言和角色相匹配的区域语音。
1. **写出自然但不流利的口语记录：** 为了获得最大的自然度，请写下 `text` 作为真实的口语记录——包括自然的对话不流畅和犹豫（例如， `"Oh uh yeah I think... hm, so that's interesting"`).
1. **首先测试纯 TTS：** 用空的合成你的成绩单 `style`
   字段优先——大多数请求不需要 `style` 根本没有指导。
1. **添加短 `style` 仅提示进行调整：** 添加一个简洁的 `style` 字符串（例如 `"casual, friendly"` 或 `"muttering, then reassuring"`）仅适用于需要特定传递调整的转弯，并且当您需要一致的基线时，可以在转弯之间重复使用该确切的短字符串。

### 多轮对话和语音智能体  {% #multi-turn-and-voice-agents %}

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

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

## 限制  {% #limitations %}

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

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

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

* **无状态语音键（`store=False`, `voicekey_...`):** **7 天 TTL**
  （生存时间）。

* 回顾 [支持的语言](/docs/speech-generation#languages) 语言覆盖部分。

## 后续步骤  {% #whats-next %}

* 从自然语言创建自定义声音角色 [声音设计](/docs/voice-design).
* 复制现有说话者的声音 [声音复刻](/docs/voice-replication).
* 编辑和优化预建或自定义声音 [声音重混](/docs/voice-remixing).
* 比较型号规格 [Gemini 3.8 Flash TTS](/docs/models/gemini-3.8-flash-tts) 和 [Gemini 3.8 Flash-Lite TTS](/docs/models/gemini-3.8-flash-lite-tts) 模型页面。
* 探索交互式双向音频 [Live API](/docs/live-api).
