声音重混
语音重新混合可让您使用自然语言指令修改现有语音,以创建新的独立存储语音。
要实施,请使用 POST /v1beta/voices 使用 gemini-3.8-flash-tts 生成一个新的 voice_... 身份证。然后,您可以使用此 ID 来合成语音 Gemini 3.8 Flash TTS (gemini-3.8-flash-tts)和 Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).
您无需从头开始设计声音角色,而是提供一个 base_voice—例如预先构建的录音室声音、 扩展语音库 声音,或者习惯 声音设计 人物角色——以及相关提示 input 描述要做出的改变(例如改变音龄、音高、能量、音色或口音)。您可以交互地重新混合声音 Google AI Studio 或以编程方式使用 POST /v1beta/voices.
快速入门 #
以下示例重新混合了预构建的 "Puck" 语音转换为新存储的语音(voice_...),保存生成的 sample_audio WAV 预览,并用重新混合的声音合成语音:
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))
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);
# 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
语音混音的工作原理 #
语音混音使用相同的 POST /v1beta/voices 端点(type="prompted", store=True) 作为 声音设计,添加 prompted.base_voice 将生成锚定在现有语音上的字段:
- 选择基本声音并描述相关编辑: 致电
client.voices.create()(POST /v1beta/voices)与type="prompted",store=True,prompted.base_voice设置为现有的语音名称或 ID,以及prompted.input描述如何修改该声音。 - 生成并存储新的独立语音(
voice_...): 该模型将您的相关指令应用于声学剖面base_voice,在您的项目中存储新的自定义语音资源,而不改变原始语音资源base_voice,并返回其id(voice_...)以及 24kHz WAVsample_audio预览(mime_type: "audio/wav"). - 合成语音或进一步迭代: 通过新的
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. |
支持的基础声音 #
您可以在以下任何一个语音标识符中传递 prompted.base_voice:
- 预建和扩展语音库语音: 传递任何 30 预建的工作室语音名称(例如
"Puck","Kore", 或"Zephyr") 或返回的任何目录语音 IDclient.voices.list()(GET /v1beta/voices). - 设计或之前重新混合的声音(
voice_...): 通过id任何存储的"prompted"您的项目拥有的声音可以微调自定义角色,而无需从头开始重新生成。
跨自定义声音的迭代混音 #
因为每个混音声音本身就是一个存储的 voice_... 资源,您可以跨自定义声音链接混音 - 从设计的或之前混音的声音开始,逐步完善特定的声音特征:
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}")
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}`);
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."
}
}
}'
管理和检查混音 #
重新混合的声音存储在您的项目中 type="prompted"。当您检索或列出自定义语音时,重新混合的语音包括 voice.prompted.base_voice 和 voice.prompted.input 这样您就可以跟踪整个语音库的血统。呼唤 GetVoice 也返回 sample_audio (audio/wav)以便您可以随时重播预览音频。
- 配额等级要求: 语音混音需要 付费层级(1 或更高层级) Gemini API 项目(参见 速率限制).
- 项目配额: 最多 200 有状态语音 (
store=True) 每个项目,在设计、重新混合和存储的复制声音之间共享。 - 保留(TTL): 1 自上次使用起的年份(
expire_time)。每次您使用存储的语音合成语音或将其引用为base_voice在新的混音请求中,其 1 年到期窗口会自动重置。
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...")
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...");
# 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"
提示语音混音的最佳实践 #
- 描述相对调整而不是重复完整的角色: 因为该模型基于声学剖面
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." |
后续步骤 #
- 从头开始创建自定义声音角色 声音设计.
- 从参考音频中复制说话者的声音 声音复刻.
- 探索回合级别样式、内联声音标签和多扬声器对话 文本转语音指南.
- 比较型号规格 Gemini 3.8 Flash TTS 和 Gemini 3.8 Flash-Lite TTS 模型页面。