使用语音混音功能创建自定义语音

您可以使用语音混音功能修改现有语音,从而创建新的自定义语音。您无需从头开始描述语音,而是选择一个基础语音,然后描述要进行的更改,例如不同的年龄、音高、能量、音色或口音。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 字段:

  1. 选择基础语音并描述更改:调用 Voices API create 方法,将 voice.type 设置为 VOICE_TYPE_PROMPTED,将 store 设置为 true,将 voice.prompted.base_voice 设置为现有语音的名称或 ID,并将 voice.prompted.input 设置为更改的说明。
  2. 接收新的语音 ID 和样本:Voices API 会将您的更改应用于基础语音,将结果作为新语音存储在项目中,并在 id 字段中返回其 ID(例如 voice_abc123...),在 sample_audio 字段中返回语音样本。基础声音不会改变。
  3. 再次生成语音或重新合成:在调用 generateContent 或 streamGenerateContent 时,在 speechConfig.voiceConfig.voice 中传递新的语音 ID。如需进一步优化语音,请将新语音 ID 作为另一个 create 请求的 base_voice 传递。

准备工作

  1. 安装 Google Cloud CLI。

  2. 配置 gcloud CLI 以使用您的联合身份。

    如需了解详情,请参阅使用联合身份登录 gcloud CLI。

  3. 如需初始化 gcloud CLI,请运行以下命令:

    gcloud init
  4. 创建或选择 Cloud de Confiance 项目。

    选择或创建项目所需的角色

    • 选择项目:选择项目不需要特定的 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 项目名称。

  5. 如果您要使用现有项目来完成本指南,请验证您是否拥有完成本指南所需的权限。如果您创建了新项目,则您已拥有所需的权限。

  6. 验证是否已为您的 Cloud de Confiance 项目启用结算功能。

  7. 启用 Agent Platform API(如果尚未启用):

    启用 API 所需的角色

    如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    gcloud services enable aiplatform.googleapis.com
  8. 为您的用户账号创建本地身份验证凭证:

    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.

后续步骤