語音設計

語音設計功能可讓您使用 Gemini API Voices 端點 (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()

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

JavaScript

import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

// 1. Design a custom voice persona from natural language
const createdVoice = await ai.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.",
    },
  },
});

console.log(`Created voice ID: ${createdVoice.id}`);

// Save the generated sample_audio preview (audio/wav) returned by CreateVoice
if (createdVoice.sample_audio?.data) {
  fs.writeFileSync(
    "voice_preview.wav",
    Buffer.from(createdVoice.sample_audio.data, "base64")
  );
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "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."
      }
    }
  }' | tee created_voice.json | jq -r '.sample_audio.data' | base64 --decode > voice_preview.wav

語音設計的運作方式

建立提示語音：呼叫 voices.create (POST /v1beta/voices) 搭配 type="prompted" 和 store=True。
接收永久 voice_id 和 sample_audio 預覽：API 會生成聲音身分，並將其儲存在專案中，然後傳回永久 ID (例如 voice_abc123...) 和 sample_audio (mime_type: "audio/wav"，以 Base64 編碼的 data)，其中包含生成的聲音預覽音訊。
合成語音：在合成要求中，將 voice_id 傳遞至接受語音名稱的任何位置。

以設計的聲音合成語音

建立語音後，請將其 id (voice_...) 傳遞至 Interactions API，以生成語音：

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": (
                "Look out past the rings of Saturn. Those faint photons left"
                " their source millions of years ago."
            ),
            "annotations": [{
                "type": "speech_metadata",
                "style": "reflective and awe-inspired",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": created_voice.id},
        ]
    },
)

with open("designed_voice.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash-tts",
  input: [{
    type: "user_input",
    content: [{
      type: "text",
      text: "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
      annotations: [{
        type: "speech_metadata",
        style: "reflective and awe-inspired",
      }],
    }],
  }],
  response_format: { type: "audio" },
  generation_config: {
    speech_config: [
      { voice: createdVoice.id },
    ],
  },
});

fs.writeFileSync("designed_voice.wav", Buffer.from(interaction.output_audio.data, "base64"));

REST

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
        "annotations": [{
          "type": "speech_metadata",
          "style": "reflective and awe-inspired"
        }]
      }]
    }],
    "response_format": {"type": "audio"},
    "generation_config": {
      "speech_config": [
        {"voice": "voice_YOUR_DESIGNED_VOICE_ID"}
      ]
    }
  }'

管理語音

您隨時可以使用 Voices API 列出、篩選、檢查及刪除儲存的聲音 (如需所有篩選器參數，請參閱「擴充語音庫和篩選」)。

儲存空間限制和存留時間：有狀態語音 (store=True，在提示和複製語音之間共用) 的限制為每個專案 200 個語音，且存留時間為 1 年。
sample_audio 支援情形： voices.create() (CreateVoice) 和 voices.get() (GetVoice) 會為 "prompted" 語音填入 sample_audio (mime_type: "audio/wav"，採用 Base64 編碼的 data)。為保持產品資訊輕量化，voices.list() (ListVoices) 會省略 sample_audio (且 sample_audio 會針對 "replicated" 和 "prebuilt" 語音取消設定)。

Python

from google import genai

client = genai.Client()

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

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

// List stored prompted voices in your project filtered by language
const response = await ai.voices.list({
  type: ["prompted"],
  language_code: ["en-US", "en-GB"],
});
for (const voice of response.voices ?? []) {
  console.log(voice.id, voice.display_name, voice.type);
}

// Retrieve a specific voice by ID
const voiceDetails = await ai.voices.get(createdVoice.id);

// Delete a stored custom voice
await ai.voices.delete(createdVoice.id);

REST

# List stored prompted voices filtered by language
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "type=prompted" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB"

# Retrieve a specific voice by ID
curl "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# Delete a stored custom voice
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

語音設計的提示最佳做法

將永久性聲音特徵放在 Voice 設計中，而非 style：在 voices.create 中建立語音時，定義不可變更的特徵，例如年齡、性別、音色、音質和地域口音。
保留 speech_metadata.style，用於表達情緒：建立自訂聲音後，使用簡短的 style 提示 (例如 "whispered urgently" 或 "cheerful and energetic") 逐步引導演出，同時保留說話者的核心特徵。
具體簡潔：清楚的 1 至 2 句描述 (例如「30 多歲的體育播報員，聲音清脆有活力，帶有中西部口音」) 比矛盾或過長的段落，更能產生清晰一致的結果。

後續步驟

瞭解如何使用語音複製功能，複製現有音箱的聲音。
如要瞭解回合層級樣式、內嵌標記和多說話者對話，請參閱文字轉語音指南。