您可以使用语音混音功能修改现有语音,从而创建新的自定义语音。您无需从头开始描述语音,而是选择一个基础语音,然后描述要进行的更改,例如不同的年龄、音高、能量、音色或口音。Voices API 会将结果作为新声音存储在项目中,并返回一个可重复使用的 voice_... ID,供您在语音生成请求中传递。
您可以混剪以下语音:
改换风格的声音可与 Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) 和 Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) 搭配使用。
语音混音功能的运作方式
语音混音使用与语音设计相同的 Voices API create 方法,并添加了 voice.prompted.base_voice 字段:
- 选择基础语音并描述更改:调用 Voices API
create方法,将voice.type设置为VOICE_TYPE_PROMPTED,将store设置为true,将voice.prompted.base_voice设置为现有语音的名称或 ID,并将voice.prompted.input设置为更改的说明。 - 接收新的语音 ID 和样本:Voices API 会将您的更改应用于基础语音,将结果作为新语音存储在项目中,并在
id字段中返回其 ID(例如voice_abc123...),在sample_audio字段中返回语音样本。基础声音不会改变。 - 再次生成语音或重新合成:在调用
generateContent或streamGenerateContent时,在speechConfig.voiceConfig.voice中传递新的语音 ID。如需进一步优化语音,请将新语音 ID 作为另一个create请求的base_voice传递。
准备工作
-
安装 Google Cloud CLI。
-
配置 gcloud CLI 以使用您的联合身份。
如需了解详情,请参阅使用联合身份登录 gcloud CLI。
-
如需初始化 gcloud CLI,请运行以下命令:
gcloud init -
选择或创建项目所需的角色
- 选择项目:选择项目不需要特定的 IAM 角色,您可以选择已获授角色的任何项目。
-
创建项目:如需创建项目,您需要拥有 Project Creator 角色 (
roles/resourcemanager.projectCreator),该角色包含resourcemanager.projects.create权限。了解如何授予角色。
-
创建 Cloud de Confiance 项目:
gcloud projects create PROJECT_ID
将
PROJECT_ID替换为您要创建的 Cloud de Confiance 项目的名称。 -
选择您创建的 Cloud de Confiance 项目:
gcloud config set project PROJECT_ID
将
PROJECT_ID替换为您的 Cloud de Confiance 项目名称。
-
如果您要使用现有项目来完成本指南,请验证您是否拥有完成本指南所需的权限。如果您创建了新项目,则您已拥有所需的权限。
启用 Agent Platform API(如果尚未启用):
启用 API 所需的角色
如需启用 API,您需要拥有
serviceusage.services.enable权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。gcloud services enable aiplatform.googleapis.com
-
为您的用户账号创建本地身份验证凭证:
gcloud auth application-default login
如果返回身份验证错误,请确认您已使用联合身份登录 gcloud CLI。
如需使用 Python 示例,请安装 2.33.0 或更高版本的 Google Gen AI SDK:
pip install --upgrade "google-genai>=2.33.0"
Voices API 可在 global 位置通过 v1beta1 API 版本使用。
所需的角色
如需获得混音和生成语音所需的权限,请让管理员向您授予 Cloud de Confiance by S3NS 项目的以下 IAM 角色:
-
创建、列出、获取和删除语音,以及生成语音:
Agent Platform User (
roles/aiplatform.user)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
创建混音
在请求中设置以下字段:
store:必须为true。改换风格后的语音始终会存储在您的项目中。 使用store: false设置base_voice的请求会失败,并显示INVALID_ARGUMENT错误。voice.type:VOICE_TYPE_PROMPTED。voice.prompted.base_voice:要改换风格的声音。使用预构建语音的语音名称(例如Puck)、扩展语音库语音的语音 ID,或设计或混剪语音的voice_...ID。如果该语音不存在,则请求会失败并返回NOT_FOUND错误。voice.prompted.input:对基础语音所做更改的自然语言说明。voice.display_name、voice.gender、voice.language_code:新声音的可选元数据。
请勿设置 voice.model。同时设置模型和 store: true 的请求会失败,并显示 INVALID_ARGUMENT 错误。
改换声音风格可能需要几秒钟的时间。Python 示例将请求超时设置为 60 秒。
响应包含以下字段:
id:新声音的 ID。prompted.base_voice:您混音的基础声音。sample_audio:新语音的示例。data字段包含采用 base64 编码的音频,mime_type字段指定其编码。默认情况下,示例是一个带有 RIFF 标头的完整 WAV 文件 (audio/wav):16 位 PCM、24 kHz、单声道。某些语音可以返回无标头的 16 位 PCM (audio/l16; rate=24000; channels=1),因此请在保存音频之前检查mime_type。usage:请求使用的 token 数量。如需了解详情,请参阅价格。
以下示例对预构建的 Puck 声音进行了混音:
Python
安装
pip install --upgrade google-genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
import base64
import wave
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
voice = client.voices.create(
store=True,
voice={
"type": "VOICE_TYPE_PROMPTED",
"display_name": "Older British Puck",
"prompted": {
"base_voice": "Puck",
"input": (
"Make the voice sound slightly older and more grounded, with a"
" warm British accent and measured audiobook narration pacing."
),
},
},
timeout=60,
)
print(f"Created voice ID: {voice.id}")
# Save the voice sample. The SDK returns sample_audio.data as a base64
# string. By default, it's a complete WAV file (audio/wav). For
# compatibility, add a WAV header if the sample is raw 16-bit PCM
# (audio/l16).
sample = base64.b64decode(voice.sample_audio.data)
if voice.sample_audio.mime_type.lower().startswith("audio/l16"):
with wave.open("remixed_voice_sample.wav", "wb") as wf:
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
wf.writeframes(sample)
else:
with open("remixed_voice_sample.wav", "wb") as f:
f.write(sample)
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 ID。
HTTP 方法和网址:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
请求 JSON 正文:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"displayName": "Older British Puck",
"prompted": {
"baseVoice": "Puck",
"input": "Make the voice sound slightly older and more grounded, with a warm British accent and measured audiobook narration pacing."
}
}
}
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应。sample_audio.data 字段已被截断。
{
"id": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124",
"prompted": {
"base_voice": "Puck"
},
"usage": {
"total_tokens": 578,
"total_input_tokens": 297,
"input_tokens_by_modality": [
{"modality": "text", "tokens": 38},
{"modality": "audio", "tokens": 259}
],
"total_output_tokens": 281,
"output_tokens_by_modality": [
{"modality": "audio", "tokens": 281}
]
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRpTwAwBXQVZF..."
}
}
默认情况下,sample_audio.mime_type 为 audio/wav,sample_audio.data 包含一个采用 base64 编码的完整 WAV 文件。如果 mime_type 为 audio/l16,则解码后的数据是无标头的 16 位 PCM 音频,采样率为 24 kHz,单声道,需要添加 WAV 标头后,大多数播放器才能打开。
使用改换风格的声音生成语音
在 speechConfig.voiceConfig.voice 中传递语音 ID,就像传递设计的语音一样:
Python
安装
pip install --upgrade google-genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-3.8-flash-tts",
contents=[{
"role": "user",
"parts": [{
"text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
"speech_metadata": {"style": "calm and reflective"},
}],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {"voice_config": {"voice": "VOICE_ID"}},
},
)
# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("remixed_voice.wav", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 ID。
- VOICE_ID:Voices API
create方法返回的语音 ID。
HTTP 方法和网址:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent
请求 JSON 正文:
{
"contents": [{
"role": "user",
"parts": [{
"text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
"speechMetadata": {"style": "calm and reflective"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "VOICE_ID"}
}
}
}
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent"
PowerShell
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent" | Select-Object -Expand Content
响应包含 candidates[0].content.parts[0].inlineData.data 中采用 base64 编码的完整 WAV 文件形式的音频。data 字段已被截断。
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "audio/wav",
"data": "UklGRhRlBABXQVZF..."
}
}
]
},
"finishReason": "STOP"
}
]
}
在 Python 示例中,将 PROJECT_ID 替换为您的 Cloud de Confiance by S3NS项目 ID,并将 VOICE_ID 替换为 create 方法返回的语音 ID。
逐步优化声音
每个改换风格后的声音都是一个存储的 voice_... 声音,因此您可以将其用作另一个改换风格的声音的基础声音。通过此分步工作流,您可以一次更改一两个特征,并在进行下一次更改之前聆听每个结果。您也可以从设计好的声音开始。
以下示例对现有设计或改换风格的声音进行改换风格:
Python
安装
pip install --upgrade google-genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
voice = client.voices.create(
store=True,
voice={
"type": "VOICE_TYPE_PROMPTED",
"prompted": {
"base_voice": "BASE_VOICE_ID",
"input": (
"Keep the same speaker identity and accent, but make the"
" delivery calmer, softer, and slightly lower in pitch."
),
},
},
timeout=60,
)
print(f"Created voice ID: {voice.id}")
print(f"Remixed from: {voice.prompted.base_voice}")
REST
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Cloud de Confiance by S3NS 项目 ID。
- BASE_VOICE_ID:项目中设计或改换风格的声音的
voice_...ID。
HTTP 方法和网址:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
请求 JSON 正文:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"prompted": {
"baseVoice": "BASE_VOICE_ID",
"input": "Keep the same speaker identity and accent, but make the delivery calmer, softer, and slightly lower in pitch."
}
}
}
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应。sample_audio.data 字段已被截断。
{
"id": "voice_f70c942e-7d78-427d-8466-cae3cb9b0371",
"prompted": {
"base_voice": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124"
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRhT4AgBXQVZF..."
}
}
在 Python 示例中,将 BASE_VOICE_ID 替换为项目中设计或改换风格的声音的 voice_... ID。
管理改换风格的声音
改换风格的声音会以 VOICE_TYPE_PROMPTED 类型存储在项目中,该类型与设计的声音相同。如需列出、获取或删除改换风格的声音,请使用与设计的声音相同的方法。如需了解详情,请参阅管理存储的语音。
改换风格后的语音独立于其基础语音:
- 改换风格绝不会改变基础声音。
- 删除基础声音不会影响通过该声音重新合成的声音。
限制
- 存储的声音会在上次使用一年后过期。使用某个声音生成语音,或将其用作改换风格的
base_voice,都会重新开始计算此期限。删除不再需要的语音。 - Remix 请求与语音设计和语音复刻共享每个项目每分钟的语音创建配额。如果超出此限制,
create方法会返回RESOURCE_EXHAUSTED错误。请稍后重试。如需了解详情,请参阅配额和系统限制。
价格
改换声音风格时,系统会按照 Gemini 3.8 Flash TTS 费率对以下 token 计费:
voice.prompted.input中说明的文本输入 token。- 基础语音音频的音频输入 token。
- Voices API 生成的语音样本的音频输出 token。
create 响应中的 usage 字段会报告每个计数。例如,创建示例中的改换风格使用了大约 40 个文本输入 token、大约 260 个音频输入 token 和大约 280 个音频输出 token。
get、list 和 delete 方法不计费。您使用改换风格的声音生成的语音将按照您调用的模型的费率计费。
如需了解 token 费率,请参阅 Gemini Enterprise 价格。
提示撰写最佳实践
- 仅描述变化:模型会保留基础语音的声音,因此只需描述要变化的特征,例如年龄、音色、音高、语速或能量。请勿重复语音的完整说明。
- 明确说明新语言或口音:除非
voice.prompted.input要求使用其他语言或口音,否则改换风格后的语音会保留基础语音的语言和地区口音。 - 每步更改一两个特征:在通过多次改换风格来优化声音时,请在每个请求中更改一小部分特征,并在进行下一次更改之前先听一听
sample_audio。 - 使用混音功能设置永久特征,并为每个回合使用
speech_metadata.style:使用语音混音功能更改语音的基准,例如年龄、口音、音高或角色。使用简短的speech_metadata.style值(例如"whispered urgently"或"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_...) |
Adapt this voice for late-night meditation narration: lower the
vocal projection, slow the pacing, and soften the tone. |
| 提高精力水平 | 改换风格后的语音 (voice_...) |
Increase vocal energy and projection so the speaker sounds like
an upbeat live event announcer. |
后续步骤
- 使用语音设计根据文字说明创建自定义语音。
- 使用语音复刻功能复刻现有说话者的声音。
- 如需了解轮次级样式、内嵌标签和多说话者对话,请参阅使用 Gemini TTS 生成语音。