建立語音¶
此 API 為 Beta 版。端點位於 /v1beta/ 下。
POST https://generativelanguage.googleapis.com/v1beta/voices
透過自然語言提示詞(VOICE_TYPE_PROMPTED),或透過參考錄音與同意錄音(VOICE_TYPE_REPLICATED),建立自訂語音。
請求主體¶
voice: required Voice
要建立的語音。voice.model 為選填;若省略,服務會選取預設的語音建立模型。若設定了 Voice 上的僅供輸出欄位(id、key、expire_time、usage),將會被忽略。
store: boolean
選填。建立的語音是否由 Google 持久保存並管理。
- 當為
true時,Google 會儲存該語音並回傳Voice.id(例如voice_abc123def456),可透過GetVoice、ListVoices與DeleteVoice管理,並在合成請求中以 ID 參照。已儲存的語音在 1 年未使用後到期;在語音合成中使用已儲存的語音,或作為base_voice在CreateVoice中使用,都會延長其expire_time。每個專案都有使用中已儲存語音的配額上限;超過配額會回傳RESOURCE_EXHAUSTED。 - 當為
false(預設)時,Google 不會儲存該語音,而是回傳Voice.key(例如voicekey_...)供用戶端儲存與合成使用。voice上的選填探索中繼資料欄位,在store為false時不會被持久保存,也不會回傳。 - 必須為
true:當voice.type為"prompted"時(否則會以INVALID_ARGUMENT失敗)。
範例請求
curl -X POST https://generativelanguage.googleapis.com/v1beta/voices \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"store": true,
"voice": {
"type": "prompted",
"display_name": "Warm Narrator",
"language_code": "en-US",
"prompted": {
"input": "A warm, friendly narrator voice with a calm pace."
}
}
}'
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
voice = client.voices.create(
store=True,
voice={
"type": "prompted",
"display_name": "Warm Narrator",
"language_code": "en-US",
"prompted": {
"input": "A warm, friendly narrator voice with a calm pace.",
},
},
)
print(voice.id)
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiVersion: 'v1beta'});
const voice = await ai.voices.create({
store: true,
voice: {
type: 'prompted',
display_name: 'Warm Narrator',
language_code: 'en-US',
prompted: {
input: 'A warm, friendly narrator voice with a calm pace.',
},
},
});
console.log(voice.id);
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
gaos_voices "google.golang.org/genai/interactions/models/voices"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"},
})
if err != nil {
log.Fatal(err)
}
req := operations.CreateVoiceRequest{
Body: gaos_voices.CreateVoiceRequest{
Store: genai.Ptr(true),
Voice: gaos_voices.VoiceInput{
Type: gaos_voices.VoiceTypePrompted,
DisplayName: genai.Ptr("Warm Narrator"),
LanguageCode: genai.Ptr("en-US"),
Prompted: &gaos_voices.PromptedVoice{
Input: "A warm, friendly narrator voice with a calm pace.",
},
},
},
}
res, err := client.Voices.Create(ctx, req)
if err != nil {
log.Fatal(err)
}
if res.Voice != nil && res.Voice.ID != nil {
fmt.Println(*res.Voice.ID)
}
}
回應¶
**type**: required `VoiceType` 語音的類型。在 `CreateVoice` 中,必須為 `"replicated"` 或 `"prompted"`。在 `ListVoices` 回應中,也可以是 `"prebuilt"`。
可能的值: - `replicated`: 透過參考音訊範本與說話者同意錄音複製出的自訂語音。 - `prompted`: 透過自然語言文字提示詞產生的自訂語音(可選擇編輯或混音 `base_voice`)。 - `prebuilt`: Google 語音目錄中的內建系統語音(例如 `Puck`、`Charon`)。會在回應中回傳;無法在 `CreateVoice` 中指定為類型。id: string
僅供輸出。語音的唯一識別碼。
- 對於 Google 管理的自訂語音(
store = true),這是產生的 ID,帶有voice_前綴(例如voice_abc123def456)。將voices/{id}作為name,在GetVoice與DeleteVoice中傳入;在語音合成期間,將{id}直接傳入SpeechConfig.voice_config.voice(或SpeechConfig.voice)。 - 對於預建目錄語音(
"prebuilt",由ListVoices回傳),這是說話者名稱(例如Puck或Charon)。 CreateVoice以store = false呼叫時不會設定。
model: string
選填。用來設計或複製語音的模型。若在 CreateVoice 中省略,預設為最新支援的語音設計模型。對於自訂語音,會在 CreateVoice、GetVoice 與 ListVoices 回應中回傳("prompted" 與 "replicated");對於 "prebuilt" 語音則不會設定。建立的語音可在任何支援的 TTS 合成模型間合成。
key: string
僅供輸出。由用戶端管理的語音複製金鑰(帶有 voicekey_ 前綴)。僅由 CreateVoice 回傳,條件為 type 為 "replicated" 且 store 為 false。在語音合成期間,將此金鑰傳入 SpeechConfig.voice_config.voice(或 SpeechConfig.voice)。
expire_time: string
僅供輸出。自訂已儲存語音(store = true)或複製語音金鑰(store = false)到期的時間戳記。對於自訂已儲存語音(store = true),當語音用於語音合成,或作為 base_voice 在 CreateVoice 中使用時,此到期時間會延長。預建目錄語音("prebuilt")不會設定,因為它們不會到期。
display_name: string
選填。使用者為已儲存語音(store = true)提供的顯示名稱,或預建語音的目錄名稱。
**prompted**: `PromptedVoice` 提示詞語音產生的參數。在 `CreateVoice` 中,當 `type` 為 `"prompted"` 時必填。對於提示詞語音,會在 `CreateVoice`、`GetVoice` 與 `ListVoices` 回應中回傳。
**input**: required `string` 描述目標語音的自然語言提示詞,例如 "A deep, booming male voice of a massive evil ogre in his middle years." **base_voice**: `string` 選填。要編輯或混音的現有基礎語音的名稱或 ID。預建語音使用語音名稱(例如 `Puck`),先前建立的語音使用語音 ID(例如 `voice_abc123`)。可以是使用者有權存取的任何提示詞語音或複製語音。若有提供,`input` 描述要對基礎語音做的相對調整。language_code: string
選填。主要的 BCP-47 語言標籤(例如 "en-US"、"fr-FR")。
region_code: string
選填。ISO 3166-1 alpha-2 或 UN M.49 地理區碼(例如 "US"、"GB"、"001")。
accent: string
選填。地區口音描述(例如 "American"、"British")。
persona: string
選填。目標人設或角色原型(例如 "Warm, Friendly"、"Narrator")。
context: string
選填。最佳使用情境或領域(例如 "Conversational"、"Audiobook"、"News")。
gender: string
選填。感知到的語音性別呈現(例如 "female"、"male"、"neutral")。
**pitch**: `Pitch` 選填。語音音高分類。
可能的值: - `low`: 音高較低的語音。 - `medium`: 音高中等的語音。 - `high`: 音高較高的語音。description: string
選填。聲音音色、個性與語氣的描述摘要。
**usage**: `Usage` 僅供輸出。語音建立請求的權杖使用統計。僅在 `CreateVoice` 的回應中填入,條件為 `type` 為 `"prompted"`;對於 `"replicated"`,以及在 `GetVoice` 與 `ListVoices` 回應中,則不會設定。
**total_input_tokens**: `integer` 提示詞(上下文)中的權杖數量。 **initial_input_tokens**: `integer` 此互動第一輪使用的輸入權杖數量。**input_tokens_by_modality**: `ModalityTokens array` 依模態區分的輸入權杖使用量明細。
**modality**: `ResponseModality` 與權杖數量相關聯的模態。
可能的值: - `text`: 表示模型應回傳文字。 - `image`: 表示模型應回傳圖片。 - `audio`: 表示模型應回傳音訊。 - `video`: 表示模型應回傳影片。 - `document`: 表示模型應回傳文件。**cached_tokens_by_modality**: `ModalityTokens array` 依模態區分的快取權杖使用量明細。
**modality**: `ResponseModality` 與權杖數量相關聯的模態。
可能的值: - `text`: 表示模型應回傳文字。 - `image`: 表示模型應回傳圖片。 - `audio`: 表示模型應回傳音訊。 - `video`: 表示模型應回傳影片。 - `document`: 表示模型應回傳文件。**output_tokens_by_modality**: `ModalityTokens array` 依模態區分的輸出權杖使用量明細。
**modality**: `ResponseModality` 與權杖數量相關聯的模態。
可能的值: - `text`: 表示模型應回傳文字。 - `image`: 表示模型應回傳圖片。 - `audio`: 表示模型應回傳音訊。 - `video`: 表示模型應回傳影片。 - `document`: 表示模型應回傳文件。**tool_use_tokens_by_modality**: `ModalityTokens array` 依模態區分的工具使用權杖使用量明細。
**modality**: `ResponseModality` 與權杖數量相關聯的模態。
可能的值: - `text`: 表示模型應回傳文字。 - `image`: 表示模型應回傳圖片。 - `audio`: 表示模型應回傳音訊。 - `video`: 表示模型應回傳影片。 - `document`: 表示模型應回傳文件。**grounding_tool_count**: `GroundingToolCount array` 接地工具數量。
**type**: `string enum` 與數量相關聯的接地工具類型。
可能的值: - `google_search`: 使用 Google 網路搜尋與圖片搜尋接地,以及 Web Grounding for Enterprise。 - `google_maps`: 使用 Google Maps 接地。**sample_audio**: `AudioData` 僅供輸出。為提示詞語音產生的範例音訊(合成器提示詞音訊)。僅在 `CreateVoice` 與 `GetVoice` 回應中填入,條件為 `type` 為 `"prompted"`;在 `ListVoices` 回應中,以及對於 `"replicated"` 或 `"prebuilt"` 語音,則不會設定。
**mime_type**: required `string` 音訊資料的 IANA MIME 類型(例如 `audio/wav` 或 `audio/mpeg`)。 **data**: required `string` 原始音訊位元組。資源¶
Voice¶
語音資源,表示自訂語音(透過 CreateVoice 建立)或預建系統語音(由 ListVoices 回傳)。
屬性:
**type**: required `VoiceType` 語音的類型。在 `CreateVoice` 中,必須為 `"replicated"` 或 `"prompted"`。在 `ListVoices` 回應中,也可以是 `"prebuilt"`。
可能的值: - `replicated`: 透過參考音訊範本與說話者同意錄音複製出的自訂語音。 - `prompted`: 透過自然語言文字提示詞產生的自訂語音(可選擇編輯或混音 `base_voice`)。 - `prebuilt`: Google 語音目錄中的內建系統語音(例如 `Puck`、`Charon`)。會在回應中回傳;無法在 `CreateVoice` 中指定為類型。id: string
僅供輸出。語音的唯一識別碼。
- 對於 Google 管理的自訂語音(
store = true),這是產生的 ID,帶有voice_前綴(例如voice_abc123def456)。將voices/{id}作為name,在GetVoice與DeleteVoice中傳入;在語音合成期間,將{id}直接傳入SpeechConfig.voice_config.voice(或SpeechConfig.voice)。 - 對於預建目錄語音(
"prebuilt",由ListVoices回傳),這是說話者名稱(例如Puck或Charon)。 CreateVoice以store = false呼叫時不會設定。
model: string
選填。用來設計或複製語音的模型。若在 CreateVoice 中省略,預設為最新支援的語音設計模型。對於自訂語音,會在 CreateVoice、GetVoice 與 ListVoices 回應中回傳("prompted" 與 "replicated");對於 "prebuilt" 語音則不會設定。建立的語音可在任何支援的 TTS 合成模型間合成。
key: string
僅供輸出。由用戶端管理的語音複製金鑰(帶有 voicekey_ 前綴)。僅由 CreateVoice 回傳,條件為 type 為 "replicated" 且 store 為 false。在語音合成期間,將此金鑰傳入 SpeechConfig.voice_config.voice(或 SpeechConfig.voice)。
**replicated**: `ReplicatedVoice` 僅供輸入。複製語音產生的參數。當 `type` 為 `"replicated"` 時,輸入中必填。不會在回應中回傳。
**source_audio**: required `AudioData` 要複製的說話者語音參考音訊範本。必須是成人聲音的未修改錄音。
**mime_type**: required `string` 音訊資料的 IANA MIME 類型(例如 `audio/wav` 或 `audio/mpeg`)。 **data**: required `string` 原始音訊位元組。**consent_audio**: required `AudioData` 同一位說話者朗讀必要同意詞句的錄音,確認授權複製其語音。
**mime_type**: required `string` 音訊資料的 IANA MIME 類型(例如 `audio/wav` 或 `audio/mpeg`)。 **data**: required `string` 原始音訊位元組。expire_time: string
僅供輸出。自訂已儲存語音(store = true)或複製語音金鑰(store = false)到期的時間戳記。對於自訂已儲存語音(store = true),當語音用於語音合成,或作為 base_voice 在 CreateVoice 中使用時,此到期時間會延長。預建目錄語音("prebuilt")不會設定,因為它們不會到期。
display_name: string
選填。使用者為已儲存語音(store = true)提供的顯示名稱,或預建語音的目錄名稱。
**prompted**: `PromptedVoice` 提示詞語音產生的參數。在 `CreateVoice` 中,當 `type` 為 `"prompted"` 時必填。對於提示詞語音,會在 `CreateVoice`、`GetVoice` 與 `ListVoices` 回應中回傳。
**input**: required `string` 描述目標語音的自然語言提示詞,例如 "A deep, booming male voice of a massive evil ogre in his middle years." **base_voice**: `string` 選填。要編輯或混音的現有基礎語音的名稱或 ID。預建語音使用語音名稱(例如 `Puck`),先前建立的語音使用語音 ID(例如 `voice_abc123`)。可以是使用者有權存取的任何提示詞語音或複製語音。若有提供,`input` 描述要對基礎語音做的相對調整。language_code: string
選填。主要的 BCP-47 語言標籤(例如 "en-US"、"fr-FR")。
region_code: string
選填。ISO 3166-1 alpha-2 或 UN M.49 地理區碼(例如 "US"、"GB"、"001")。
accent: string
選填。地區口音描述(例如 "American"、"British")。
persona: string
選填。目標人設或角色原型(例如 "Warm, Friendly"、"Narrator")。
context: string
選填。最佳使用情境或領域(例如 "Conversational"、"Audiobook"、"News")。
gender: string
選填。感知到的語音性別呈現(例如 "female"、"male"、"neutral")。
**pitch**: `Pitch` 選填。語音音高分類。
可能的值: - `low`: 音高較低的語音。 - `medium`: 音高中等的語音。 - `high`: 音高較高的語音。description: string
選填。聲音音色、個性與語氣的描述摘要。