# 声音重混

语音重新混合可让您使用自然语言指令修改现有语音，以创建新的独立存储语音。

要实施，请使用 `POST /v1beta/voices` 使用 `gemini-3.8-flash-tts` 生成一个新的 `voice_...` 身份证。然后，您可以使用此 ID 来合成语音 [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`).

您无需从头开始设计声音角色，而是提供一个 `base_voice`—例如预先构建的录音室声音、 [扩展语音库](/docs/speech-generation#voice-library) 声音，或者习惯 [声音设计](/docs/voice-design) 人物角色——以及相关提示 `input` 描述要做出的改变（例如改变音龄、音高、能量、音色或口音）。您可以交互地重新混合声音 [Google AI Studio](https://aistudio.google.com/generate-speech) 或以编程方式使用 `POST /v1beta/voices`.

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

## 快速入门  {% #get-started %}

以下示例重新混合了预构建的 `"Puck"` 语音转换为新存储的语音（`voice_...`），保存生成的 `sample_audio` WAV 预览，并用重新混合的声音合成语音：

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

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

# 1. Remix an existing base voice into a new stored custom voice
remixed_voice = client.voices.create(
    store=True,
    voice={
        "model": "gemini-3.8-flash-tts",
        "type": "prompted",
        "prompted": {
            "base_voice": "Puck",
            "input": (
                "Make the voice sound slightly older and more grounded, with a"
                " warm British accent and measured audiobook narration pacing."
            ),
        },
    },
)

print(f"Created remixed voice ID: {remixed_voice.id}")  # e.g., "voice_abc123..."

# Optional: Save the sample audio preview (24kHz WAV) returned by CreateVoice
if remixed_voice.sample_audio and remixed_voice.sample_audio.data:
    with open("remixed_voice_preview.wav", "wb") as f:
        f.write(base64.b64decode(remixed_voice.sample_audio.data))

# 2. Synthesize speech using the remixed voice ID
interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
            "annotations": [{
                "type": "speech_metadata",
                "style": "calm and reflective",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": remixed_voice.id},
        ]
    },
)

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

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

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

// 1. Remix an existing base voice into a new stored custom voice
const remixedVoice = await client.voices.create({
  store: true,
  voice: {
    model: "gemini-3.8-flash-tts",
    type: "prompted",
    prompted: {
      base_voice: "Puck",
      input:
        "Make the voice sound slightly older and more grounded, with a warm British accent and measured audiobook narration pacing.",
    },
  },
});

console.log(`Created remixed voice ID: ${remixedVoice.id}`); // e.g., "voice_abc123..."

// Optional: Save the sample audio preview (24kHz WAV) returned by CreateVoice
if (remixedVoice.sample_audio?.data) {
  fs.writeFileSync(
    "remixed_voice_preview.wav",
    Buffer.from(remixedVoice.sample_audio.data, "base64")
  );
}

// 2. Synthesize speech using the remixed voice ID
const interaction = await client.interactions.create({
  model: "gemini-3.8-flash-tts",
  input: [{
    type: "user_input",
    content: [{
      type: "text",
      text: "Chapter One. The fog rolled quietly across the harbor at dawn.",
      annotations: [{
        type: "speech_metadata",
        style: "calm and reflective",
      }],
    }],
  }],
  response_format: { type: "audio" },
  generation_config: {
    speech_config: [
      { voice: remixedVoice.id },
    ],
  },
});

const audioBuffer = Buffer.from(interaction.output_audio.data, "base64");
fs.writeFileSync("remixed_voice_output.wav", audioBuffer);
```
{% /tab %}

{% tab label="REST" %}
```bash
# 1. Remix an existing base voice into a new stored custom voice
curl -X POST "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "store": true,
    "voice": {
      "model": "gemini-3.8-flash-tts",
      "type": "prompted",
      "prompted": {
        "base_voice": "Puck",
        "input": "Make the voice sound slightly older and more grounded, with a warm British accent and measured audiobook narration pacing."
      }
    }
  }'

# The response returns "id": "voice_abc123...", "prompted": {"base_voice": "Puck", ...},
# and "sample_audio": {"mime_type": "audio/wav", "data": "<base64-wav>"}

# 2. Synthesize speech using the returned voice_... ID
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": "Chapter One. The fog rolled quietly across the harbor at dawn.",
        "annotations": [{
          "type": "speech_metadata",
          "style": "calm and reflective"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "voice_abc123..." }
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > remixed_voice_output.wav
```
{% /tab %}
{% /tabs %}

## 语音混音的工作原理  {% #how-voice-remixing-works %}

语音混音使用相同的 `POST /v1beta/voices` 端点（`type="prompted"`, `store=True`) 作为 [声音设计](/docs/voice-design)，添加 `prompted.base_voice` 将生成锚定在现有语音上的字段：

1. **选择基本声音并描述相关编辑：** 致电 `client.voices.create()` (`POST /v1beta/voices`）与 `type="prompted"`, `store=True`, `prompted.base_voice` 设置为现有的语音名称或 ID，以及 `prompted.input` 描述如何修改该声音。
1. **生成并存储新的独立语音（`voice_...`):** 该模型将您的相关指令应用于声学剖面 `base_voice`，在您的项目中存储新的自定义语音资源，而不改变原始语音资源 `base_voice`，并返回其 `id` (`voice_...`）以及 24kHz WAV `sample_audio` 预览（`mime_type: "audio/wav"`).
1. **合成语音或进一步迭代：** 通过新的 `voice_...` 身份证号在 `speech_config` 用于单扬声器合成，或将其传递为 `base_voice` 在随后的 `CreateVoice` 呼叫逐步细化语音。

| 参数                          | 类型     | 说明                                                                                                                             |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `store`                     | `bool` | 必填（`True` 用于 `"prompted"` 的声音）。将重新混合的声音存储在您的项目中并返回 `voice_...` 身份证。                                                            |
| `voice.model`               | `str`  | 可选。语音创作模型： `"gemini-3.8-flash-tts"` （省略时默认）。存储的结果 `voice_...` ID 可用于语音合成 `gemini-3.8-flash-tts` 和 `gemini-3.8-flash-lite-tts`. |
| `voice.type`                | `str`  | 必填。设置为 `"prompted"`.                                                                                                           |
| `voice.prompted.base_voice` | `str`  | 重新混合时需要。要重新混合的源语音的名称或 ID（预建语音名称、扩展语音库 ID 或存储的提示） `voice_...` 身份证）。                                                             |
| `voice.prompted.input`      | `str`  | 必填。描述要应用的相对修改的自然语言指令 `base_voice`.                                                                                             |

## 支持的基础声音  {% #supported-base-voices %}

您可以在以下任何一个语音标识符中传递 `prompted.base_voice`:

* **预建和扩展语音库语音：** 传递任何 30 预建的工作室语音名称（例如 `"Puck"`, `"Kore"`, 或 `"Zephyr"`) 或返回的任何目录语音 ID `client.voices.list()` (`GET /v1beta/voices`).
* **设计或之前重新混合的声音（`voice_...`):** 通过 `id` 任何存储的 `"prompted"` 您的项目拥有的声音可以微调自定义角色，而无需从头开始重新生成。

{% callout type="note" %}
混音总是创造一个新的、独立的 `voice_...` 资源。它永远不会修改或覆盖原始内容 `base_voice`，并删除 `base_voice`
稍后不会影响从中重新混合的任何声音。
{% /callout %}

## 跨自定义声音的迭代混音  {% #iterative-remixing %}

因为每个混音声音本身就是一个存储的 `voice_...` 资源，您可以跨自定义声音链接混音 - 从设计的或之前混音的声音开始，逐步完善特定的声音特征：

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

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

# Start from an existing prompted voice ID (designed or previously remixed)
source_voice_id = "voice_abc123..."

# Create a new variation while preserving the core vocal identity
remixed_variation = client.voices.create(
    store=True,
    voice={
        "model": "gemini-3.8-flash-tts",
        "type": "prompted",
        "prompted": {
            "base_voice": source_voice_id,
            "input": (
                "Keep the same speaker identity and accent, but make the"
                " delivery calmer, softer, and slightly lower in pitch."
            ),
        },
    },
)

print(f"New voice ID: {remixed_variation.id}")
print(f"Remixed from: {remixed_variation.prompted.base_voice}")
```
{% /tab %}

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

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

// Start from an existing prompted voice ID (designed or previously remixed)
const sourceVoiceId = "voice_abc123...";

// Create a new variation while preserving the core vocal identity
const remixedVariation = await client.voices.create({
  store: true,
  voice: {
    model: "gemini-3.8-flash-tts",
    type: "prompted",
    prompted: {
      base_voice: sourceVoiceId,
      input:
        "Keep the same speaker identity and accent, but make the delivery calmer, softer, and slightly lower in pitch.",
    },
  },
});

console.log(`New voice ID: ${remixedVariation.id}`);
console.log(`Remixed from: ${remixedVariation.prompted?.base_voice}`);
```
{% /tab %}

{% tab label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "store": true,
    "voice": {
      "model": "gemini-3.8-flash-tts",
      "type": "prompted",
      "prompted": {
        "base_voice": "voice_abc123...",
        "input": "Keep the same speaker identity and accent, but make the delivery calmer, softer, and slightly lower in pitch."
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## 管理和检查混音  {% #manage-remixed-voices %}

重新混合的声音存储在您的项目中 `type="prompted"`。当您检索或列出自定义语音时，重新混合的语音包括 `voice.prompted.base_voice` 和 `voice.prompted.input` 这样您就可以跟踪整个语音库的血统。呼唤 `GetVoice` 也返回 `sample_audio`
(`audio/wav`）以便您可以随时重播预览音频。

* **配额等级要求：** 语音混音需要 **付费层级（1 或更高层级）** Gemini API 项目（参见 [速率限制](/docs/rate-limits)).
* **项目配额：** 最多 **200 有状态语音 (`store=True`) 每个项目**，在设计、重新混合和存储的复制声音之间共享。
* **保留（TTL）：** **1 自上次使用起的年份（`expire_time`)**。每次您使用存储的语音合成语音或将其引用为 `base_voice` 在新的混音请求中，其 1 年到期窗口会自动重置。

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

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

# List all custom prompted voices (both designed and remixed)
response = client.voices.list(type_=["prompted"])
for v in response.voices or []:
    base = v.prompted.base_voice if v.prompted else None
    prompt = v.prompted.input if v.prompted else None
    print(f"{v.id} | base_voice={base} | expires={v.expire_time} | prompt={prompt}")

# Retrieve a specific remixed voice (including its sample_audio WAV preview)
voice_info = client.voices.get(id="voice_abc123...")
if voice_info.sample_audio and voice_info.sample_audio.data:
    with open("fetched_remix_preview.wav", "wb") as f:
        f.write(base64.b64decode(voice_info.sample_audio.data))

# Delete a remixed voice when no longer needed
client.voices.delete(id="voice_abc123...")
```
{% /tab %}

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

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

// List all custom prompted voices (both designed and remixed)
const response = await client.voices.list({ type: ["prompted"] });
for (const v of response.voices ?? []) {
  console.log(
    `${v.id} | base_voice=${v.prompted?.base_voice ?? "none"} | expires=${v.expire_time} | prompt=${v.prompted?.input}`
  );
}

// Retrieve a specific remixed voice (including its sample_audio WAV preview)
const voiceInfo = await client.voices.get("voice_abc123...");
if (voiceInfo.sample_audio?.data) {
  fs.writeFileSync(
    "fetched_remix_preview.wav",
    Buffer.from(voiceInfo.sample_audio.data, "base64")
  );
}

// Delete a remixed voice when no longer needed
await client.voices.delete("voice_abc123...");
```
{% /tab %}

{% tab label="REST" %}
```bash
# List all custom prompted voices (both designed and remixed)
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "type=prompted"

# Get metadata and sample_audio preview for a specific remixed voice
curl "https://generativelanguage.googleapis.com/v1beta/voices/voice_abc123..." \
  -H "x-goog-api-key: $GEMINI_API_KEY"

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

## 提示语音混音的最佳实践  {% #prompting-best-practices %}

* **描述相对调整而不是重复完整的角色：**
  因为该模型基于声学剖面 `base_voice`, 焦点 `prompted.input` 您想要改变的具体特征，例如年龄、音色、音高、节奏或声音能量。
* **依赖默认语言和口音保留：** 相对混音提示保留了基线语言和地区口音 `base_voice`
  除非您在中明确指定新语言或口音 `prompted.input`.
* **链接混音时每步骤修改一两个特征：** 在多次迭代中优化声音时，调整每次调用的一组重点属性并试听 `sample_audio` 在链接下一个编辑之前预览。
* **使用语音混音来实现永久的声音特征和 `speech_metadata.style`
  对于回合级表演：** 使用语音混音来永久改变角色的基线语音（例如年龄、口音、音调或默认角色）。使用 `speech_metadata.style` 在 TTS 合成期间提供临时的逐轮传递提示（例如 `"whispering"` 或 `"excited"`).

| 混音目标        | 示例 `base_voice`            | 示例 `prompted.input`                                                                                                         |
| ----------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **年龄和音色变化** | `"Puck"`                   | `"Make the voice sound 20 years older with a deeper, slightly gravelly baritone timbre while keeping the friendly warmth."` |
| **地区口音适应**  | `"Kore"`                   | `"Change the accent to Australian English while preserving the clear, confident studio delivery."`                          |
| **领域和节奏调整** | `"voice_abc123..."` （设计声音） | `"Adapt this voice for late-night meditation narration: lower the vocal projection, slow the pacing, and soften the tone."` |
| **能源和预测转变** | `"voice_def456..."` （重新混音） | `"Increase vocal energy and projection so the speaker sounds like an upbeat live event announcer."`                         |

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

* 从头开始创建自定义声音角色 [声音设计](/docs/voice-design).
* 从参考音频中复制说话者的声音 [声音复刻](/docs/voice-replication).
* 探索回合级别样式、内联声音标签和多扬声器对话 [文本转语音指南](/docs/speech-generation).
* 比较型号规格 [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) 模型页面。
