声音设计
语音设计可让您使用 Gemini API 语音端点 (POST /v1beta/voices)。您可以描述角色的年龄、音色、口音和基线传递,并获得可重复使用的声音,而不是局限于预先构建的声音或录制参考音频。 voice_... ID已保存到您的项目中。
设计、试听和迭代自定义声音的最快方法是使用交互式 声音设计 工作室在 Google AI Studio。您可以根据文本提示生成自定义角色,使用示例脚本对其进行测试,然后复制生成的结果 voice_... ID 直接添加到您的应用程序代码中。
两者都 Gemini 3.8 Flash TTS (gemini-3.8-flash-tts)和 Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts)支持语音设计。
创建设计好的声音 #
使用 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)这样您就可以立即试听生成的语音:
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))
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")
);
}
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
语音设计如何运作 #
- 创建提示声音: 致电
voices.create(POST /v1beta/voices)与type="prompted"和store=True. - 接收持久化
voice_id和sample_audio预览: API 生成语音标识,将其存储在您的项目中,并返回永久 ID(例如,voice_abc123...)连同sample_audio(mime_type: "audio/wav", base64 编码data)包含生成的语音预览音频。 - 合成语音: 通过
voice_id在speechConfig.voiceConfig.voice打电话时generateContent.
用您设计的声音合成语音 #
通过返回的 id (voice_...) 在 voiceConfig.voice 打电话时 generateContent:
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": (
"Look out past the rings of Saturn. Those faint photons left"
" their source millions of years ago."
),
"speech_metadata": {"style": "reflective and awe-inspired"},
}],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {
"voice_config": {"voice": created_voice.id}
},
},
)
audio_bytes = response.candidates[0].content.parts[0].inline_data.data
with open("designed_voice.wav", "wb") as f:
f.write(audio_bytes)
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const response = await ai.models.generateContent({
model: "gemini-3.8-flash-tts",
contents: [{
role: "user",
parts: [{
text: "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
speechMetadata: { style: "reflective and awe-inspired" },
}],
}],
config: {
responseModalities: ["AUDIO"],
speechConfig: {
voiceConfig: { voice: createdVoice.id },
},
},
});
const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
if (data) {
fs.writeFileSync("designed_voice.wav", Buffer.from(data, "base64"));
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
"speech_metadata": {
"style": "reflective and awe-inspired"
}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {
"voice": "voice_YOUR_DESIGNED_VOICE_ID"
}
}
}
}'
管理你的声音 #
您可以使用语音 API 随时列出、过滤、检查和删除存储的语音(请参阅 扩展语音库和过滤 对于所有过滤器参数)。
- 存储限制和 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"声音)。
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)
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);
# 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"
提示语音设计的最佳实践 #
- 将永久的声音特征放入声音设计中,而不是
style: 在创建声音时定义不可变的特征,例如年龄、性别、音色、声音质感和地区口音voices.create. - 储备
speech_metadata.style对于情境情绪: 创建自定义语音后,请使用简短的style提示(例如,"whispered urgently"或"cheerful and energetic")在不改变说话者核心身份的情况下引导逐轮表演。 - 具体而简洁: 清晰的 1–2 句子描述(例如 “一位 30 多岁、干脆利落、充满活力的体育播音员,略带中西部口音”)比矛盾或过长的段落产生更清晰、更一致的结果。