Gemini 中文指南
获取 API 密钥 ↗

声音设计

↓ 下载 Markdown

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

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

在 Google AI Studio 中体验

两者都 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)这样您就可以立即试听生成的语音:

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))

语音设计如何运作 #

  1. 创建提示声音: 致电 voices.create (POST /v1beta/voices)与 type="prompted" 和 store=True.
  2. 接收持久化 voice_id 和 sample_audio 预览: API 生成语音标识,将其存储在您的项目中,并返回永久 ID(例如, voice_abc123...)连同 sample_audio (mime_type: "audio/wav", base64 编码 data)包含生成的语音预览音频。
  3. 合成语音: 通过 voice_id 在 speechConfig.voiceConfig.voice 打电话时 generateContent.

用您设计的声音合成语音 #

通过返回的 id (voice_...) 在 voiceConfig.voice 打电话时 generateContent:

python
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)

管理你的声音 #

您可以使用语音 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" 声音)。
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)

提示语音设计的最佳实践 #

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

后续步骤 #

搜索标题、API 名称或正文内容