使用語音混音功能建立自訂語音

您可以使用語音混音功能編輯現有語音,建立新的自訂語音。您不必從頭描述語音,而是選擇基礎語音,並描述要變更的部分,例如不同的年齡、音高、能量、音色或口音。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 角色,只要您在專案中獲派角色,即可選取該專案。
    • 建立專案:如要建立專案,您必須具備專案建立者角色 (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 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (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 角色:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

建立改造語音

在要求中設定下列欄位:

  • 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.

後續步驟