# 声音设计

语音设计可让您使用 Gemini API 语音端点 (`POST /v1beta/voices`）。您可以描述角色的年龄、音色、口音和基线传递，并获得可重复使用的声音，而不是局限于预先构建的声音或录制参考音频。 `voice_...` ID已保存到您的项目中。

设计、试听和迭代自定义声音的最快方法是使用交互式 **声音设计** 工作室在 [Google AI Studio](https://aistudio.google.com/generate-speech)。您可以根据文本提示生成自定义角色，使用示例脚本对其进行测试，然后复制生成的结果 `voice_...` ID 直接添加到您的应用程序代码中。

{% button href="https://aistudio.google.com/generate-speech" variant="primary" %}在 Google AI Studio 中体验{% /button %}

两者都 [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`）支持语音设计。

## 创建设计好的声音  {% #create-a-designed-voice %}

使用 Google GenAI SDK (`google-genai` 2.25.0+ / `@google/genai` 2.24.0+) 或 REST API 根据文本描述创建自定义语音。对于 `"prompted"` 声音，两者 `voices.create` (`CreateVoice`）和 `voices.get` (`GetVoice`) 仅返回输出 `sample_audio` 场（`mime_type: "audio/wav"`, base64 编码 `data`）这样您就可以立即试听生成的语音：

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

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

# 1. Design a custom voice persona from natural language
created_voice = client.voices.create(
    store=True,
    voice={
        "model": "gemini-3.8-flash-tts",
        "type": "prompted",
        "display_name": "Warm British Astronomer",
        "gender": "male",
        "language_code": "en-GB",
        "prompted": {
            "input": (
                "A warm, thoughtful astronomer in his late 60s with a gentle"
                " British accent, speaking with quiet wonder."
            )
        },
    },
)

print(f"Created voice ID: {created_voice.id}")

# Save the generated sample_audio preview (audio/wav) returned by CreateVoice
if created_voice.sample_audio and created_voice.sample_audio.data:
    with open("voice_preview.wav", "wb") as f:
        f.write(base64.b64decode(created_voice.sample_audio.data))
```
{% /tab %}

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

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

// 1. Design a custom voice persona from natural language
const createdVoice = await ai.voices.create({
  store: true,
  voice: {
    model: "gemini-3.8-flash-tts",
    type: "prompted",
    display_name: "Warm British Astronomer",
    gender: "male",
    language_code: "en-GB",
    prompted: {
      input:
        "A warm, thoughtful astronomer in his late 60s with a gentle British accent, speaking with quiet wonder.",
    },
  },
});

console.log(`Created voice ID: ${createdVoice.id}`);

// Save the generated sample_audio preview (audio/wav) returned by CreateVoice
if (createdVoice.sample_audio?.data) {
  fs.writeFileSync(
    "voice_preview.wav",
    Buffer.from(createdVoice.sample_audio.data, "base64")
  );
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "store": true,
    "voice": {
      "model": "gemini-3.8-flash-tts",
      "type": "prompted",
      "display_name": "Warm British Astronomer",
      "gender": "male",
      "language_code": "en-GB",
      "prompted": {
        "input": "A warm, thoughtful astronomer in his late 60s with a gentle British accent, speaking with quiet wonder."
      }
    }
  }' | tee created_voice.json | jq -r '.sample_audio.data' | base64 --decode > voice_preview.wav
```
{% /tab %}
{% /tabs %}

## 语音设计如何运作  {% #how-voice-design-works %}

1. **创建提示声音：** 致电 `voices.create` (`POST /v1beta/voices`）与 `type="prompted"` 和 `store=True`.
1. **接收持久化 `voice_id` 和 `sample_audio` 预览：** API 生成语音标识，将其存储在您的项目中，并返回永久 ID（例如， `voice_abc123...`）连同 `sample_audio`
   (`mime_type: "audio/wav"`, base64 编码 `data`）包含生成的语音预览音频。
1. **合成语音：** 通过 `voice_id` 合成请求中接受语音名称的任何地方。

## 用您设计的声音合成语音  {% #synthesize-speech-with-your-designed-voice %}

创建声音后，将其传递给 `id` (`voice_...`) 到 Interactions API 以生成语音：

{% 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": (
                "Look out past the rings of Saturn. Those faint photons left"
                " their source millions of years ago."
            ),
            "annotations": [{
                "type": "speech_metadata",
                "style": "reflective and awe-inspired",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": created_voice.id},
        ]
    },
)

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

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

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

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash-tts",
  input: [{
    type: "user_input",
    content: [{
      type: "text",
      text: "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
      annotations: [{
        type: "speech_metadata",
        style: "reflective and awe-inspired",
      }],
    }],
  }],
  response_format: { type: "audio" },
  generation_config: {
    speech_config: [
      { voice: createdVoice.id },
    ],
  },
});

if (interaction.output_audio?.data) {
  fs.writeFileSync("designed_voice.wav", Buffer.from(interaction.output_audio.data, "base64"));
}
```
{% /tab %}

{% tab label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
        "annotations": [{
          "type": "speech_metadata",
          "style": "reflective and awe-inspired"
        }]
      }]
    }],
    "response_format": {"type": "audio"},
    "generation_config": {
      "speech_config": [
        {"voice": "voice_YOUR_DESIGNED_VOICE_ID"}
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav
```
{% /tab %}
{% /tabs %}

## 管理你的声音  {% #manage-your-voices %}

您可以使用语音 API 随时列出、过滤、检查和删除存储的语音（请参阅 [扩展语音库和过滤](/docs/speech-generation#voice-library)
对于所有过滤器参数）。

* **存储限制和 TTL：** 有状态的声音（`store=True`，在提示和复制的声音之间共享）有一个限制 **200 每个项目的声音**
  和一个 **1年TTL** （生存时间）。
* **`sample_audio` 可用性：** `voices.create()` (`CreateVoice`）和 `voices.get()` (`GetVoice`）填充 `sample_audio` (`mime_type: "audio/wav"`, base64 编码 `data`）对于 `"prompted"` 的声音。为了保持列表轻量化， `voices.list()` (`ListVoices`) 省略 `sample_audio`
  （和 `sample_audio` 未设置为 `"replicated"` 和 `"prebuilt"` 声音）。

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

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

# List stored prompted voices in your project filtered by language
response = client.voices.list(
    type_=["prompted"],
    language_code=["en-US", "en-GB"],
)
for voice in response.voices or []:
    print(voice.id, voice.display_name, voice.type)

# Retrieve a specific voice by ID
voice_details = client.voices.get(id=created_voice.id)

# Delete a stored custom voice
client.voices.delete(id=created_voice.id)
```
{% /tab %}

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

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

// List stored prompted voices in your project filtered by language
const response = await ai.voices.list({
  type: ["prompted"],
  language_code: ["en-US", "en-GB"],
});
for (const voice of response.voices ?? []) {
  console.log(voice.id, voice.display_name, voice.type);
}

// Retrieve a specific voice by ID
const voiceDetails = await ai.voices.get(createdVoice.id);

// Delete a stored custom voice
await ai.voices.delete(createdVoice.id);
```
{% /tab %}

{% tab label="REST" %}
```bash
# List stored prompted voices filtered by language
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "type=prompted" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB"

# Retrieve a specific voice by ID
curl "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# Delete a stored custom voice
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## 提示语音设计的最佳实践  {% #prompting-best-practices-for-voice-design %}

* **将永久的声音特征放入声音设计中，而不是 `style`:** 在创建声音时定义不可变的特征，例如年龄、性别、音色、声音质感和地区口音 `voices.create`.
* **储备 `speech_metadata.style` 对于情境情绪：** 创建自定义语音后，请使用简短的 `style` 提示（例如， `"whispered urgently"` 或 `"cheerful and energetic"`）在不改变说话者核心身份的情况下引导逐轮表演。
* **具体而简洁：** 清晰的 1–2 句子描述（例如 *“一位 30 多岁、干脆利落、充满活力的体育播音员，略带中西部口音”*）比矛盾或过长的段落产生更清晰、更一致的结果。

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

* 了解如何复制现有说话者的声音 [声音复刻](/docs/voice-replication).
* 使用自然语言指令编辑和优化预构建或自定义语音 [声音重混](/docs/voice-remixing).
* 探索轮流样式、内联标签和多发言者对话 [文本转语音指南](/docs/speech-generation).
