您可以使用語音混音功能編輯現有語音,建立新的自訂語音。您不必從頭描述語音,而是選擇基礎語音,並描述要變更的部分,例如不同的年齡、音高、能量、音色或口音。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 角色,只要您在專案中獲派角色,即可選取該專案。
-
建立專案:如要建立專案,您必須具備專案建立者角色 (
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權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (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 使用者 (
roles/aiplatform.user)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
建立改造語音
在要求中設定下列欄位:
store:必須是true。改造後的語音一律會儲存在專案中。 如果要求將base_voice設為store: false,則會失敗並顯示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欄位則會指定編碼名稱。根據預設,樣本是完整的 WAV 檔案 (audio/wav),具有 RIFF 標頭:16 位元 PCM、24 kHz、單聲道。部分語音可能會改為傳回無標頭的 16 位元 PCM (audio/l16; rate=24000; channels=1),因此請先檢查mime_type,再儲存音訊。usage:要求使用的權杖數量。詳情請參閱「定價」。
下列範例會改造預先建立的 Puck 語音:
Python
安裝
pip install --upgrade google-genai
詳情請參閱 SDK 參考文件。
設定環境變數,以便透過 Vertex AI 使用 Google Gen AI SDK:
# 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 參考文件。
設定環境變數,以便透過 Vertex AI 使用 Google Gen AI SDK:
# 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 參考文件。
設定環境變數,以便透過 Vertex AI 使用 Google Gen AI SDK:
# 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,這段期間就會重新計算。刪除不再需要的語音。 - 改造要求與語音設計和語音複製功能,共用每項專案每分鐘的語音建立配額。如果超過上限,
create方法會傳回RESOURCE_EXHAUSTED錯誤。請稍後再試。詳情請參閱「配額和系統限制」。
定價
改造語音時,系統會依 Gemini 3.8 Flash TTS 費率,針對下列詞元計費:
voice.prompted.input中說明的文字輸入詞元。- 基本語音音訊的音訊輸入詞元。
- Voices API 生成的語音樣本音訊輸出詞元。
create 回應中的 usage 欄位會回報各項計數。舉例來說,建立範例中的混音使用了約 40 個文字輸入詞元、約 260 個音訊輸入詞元,以及約 280 個音訊輸出詞元。
get、list 和 delete 方法不會產生費用。使用混音語音生成的語音,會按照您呼叫的模型費率計費。
如要瞭解權杖費率,請參閱「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 生成語音」。