Gemini Voices API

您可以使用 Voices API，透過自然語言提示 (語音設計) 或參考音訊和說話者同意聲明錄音 (語音複製) 建立自訂語音，以及列出、擷取及管理 Text-to-Speech (TTS) 合成作業的自訂和預建語音。

以 Markdown 格式查看 查看 OpenAPI 規格

CreateVoice

post https://generativelanguage.googleapis.com/v1beta/voices

可透過自然語言提示 (`VOICE_TYPE_PROMPTED`) 或參考和同意聲明錄音 (`VOICE_TYPE_REPLICATED`) 建立自訂聲音。

要求主體

要求主體會包含結構如下的資料：

store boolean  (選填)

(選用步驟) 建立的聲音是否由 Google 保留及管理。 * 如果為 `true`，Google 會儲存語音並傳回 `Voice.id` (例如 `voice_abc123def456`)，可透過 `GetVoice`、`ListVoices` 和 `DeleteVoice` 管理，並在合成要求中依 ID 參照。專案的有效儲存語音配額有上限，超過配額會傳回 `RESOURCE_EXHAUSTED`。 * 如果為 `false` (預設值)，Google 不會儲存語音，且會傳回 `Voice.key` (例如 `voicekey_...`)，供用戶端儲存和合成。如果 `store` 為 `false`，系統不會保留或傳回 `voice` 的選用探索中繼資料欄位。 * 如果 `voice.type` 為 `"prompted"`，則必須為 `true` (否則會因 `INVALID_ARGUMENT` 而失敗)。

voice Voice  (必要)

必填。要建立的語音。 `voice.model` 為選用項目；如省略，服務會選取預設語音建立模型。如果設定 `Voice` (`id`、`key`、 `expire_time`、`usage`) 的唯輸出場地，系統會忽略這些設定。

回應

如果成功，回應主體會含有以下結構的資料：

accent string  (選填)

(選用步驟) 區域口音描述符 (例如「美式」、「英式」)。

context string  (選填)

(選用步驟) 最佳使用情境或網域 (例如「對話」、「有聲書」、「新聞」)。

description string  (選用)

(選用步驟) 描述聲音音色、特質和語氣的摘要。

display_name 字串  (選用)

(選用步驟) 儲存語音時使用者提供的顯示名稱 (`store = true`)， 或是預建語音的目錄名稱。

expire_time string  (optional)

僅供輸出。自訂儲存聲音 (`store = true`) 或複製聲音金鑰 (`store = false`) 的到期時間戳記。預建目錄語音 (`"prebuilt"`) 不會過期，因此無法取消設定。

gender string  (選填)

(選用步驟) 語音性別呈現方式 (例如「女性」、「男性」、「中性」)。

id string  (選用)

僅供輸出。語音的專屬 ID。 * 如果是 Google 管理的自訂語音 (`store = true`)，這是產生的 ID，前置字串為 `voice_` (例如 `voice_abc123def456`)。在 `GetVoice` 和 `DeleteVoice` 中，將 `voices/{id}` 做為 `name` 傳遞，並在語音合成期間，將 `{id}` 直接傳遞至 `SpeechConfig.voice_config.voice` (或 `SpeechConfig.voice`)。 * 如果是預先建構的目錄語音 (由 `ListVoices` 傳回的 `"prebuilt"`)，這是說話者名稱 (例如 `Puck` 或 `Charon`)。 * 使用 `store = false` 呼叫 `CreateVoice` 時，系統會取消設定。

key string  (選填)

僅供輸出。用戶端管理的語音複製金鑰 (前置字元為 `voicekey_`)。只有在 `type` 為 `"replicated"` 且 `store` 為 `false` 時，`CreateVoice` 才會傳回這項金鑰。在語音合成期間，請將這項金鑰傳遞至 `SpeechConfig.voice_config.voice` (或 `SpeechConfig.voice`)。

language_code string  (選用)

(選用步驟) 主要 BCP-47 語言標記 (例如「en-US」、「fr-FR」)。

model string  (選填)

(選用步驟) 用於設計或複製語音的模型。 如果 `CreateVoice` 中省略此欄位，系統會預設為最新支援的語音設計模型。在自訂語音 (`"prompted"` 和 `"replicated"`) 的 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中傳回；`"prebuilt"` 語音則未設定。建立的聲音可透過任何支援的文字轉語音合成模型合成。

persona string  (選填)

(選用步驟) 預期角色或人物原型 (例如「溫暖友善」、「旁白」)。

pitch 音調  (選填)

(選用步驟) 語音音調分類。

可能的值

  • low

    調低音調。

  • medium

    中音調。

  • high

    調高音調。

prompted PromptedVoice  (選填)

提示語音生成功能的參數。 如果 `type` 為 `"prompted"`，則 `CreateVoice` 中必須提供這項屬性。系統會在 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中，傳回提示語音的這項屬性。

提示語音生成功能所用的參數。 如果 `type` 為 `"prompted"`，則 `CreateVoice` 中必須提供這項屬性。系統會在 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中，傳回提示語音的這項屬性。

欄位

input string  (選用)

必填。描述所需語音的自然語言提示，例如「中年邪惡食人魔的低沉男聲」。

region_code string  (選用)

(選用步驟) ISO 3166-1 alpha-2 或 UN M.49 地理區域代碼 (例如「US」、「GB」、「001」)。

sample_audio AudioData  (選填)

僅供輸出。根據提示詞生成的語音樣本 (合成器提示詞音訊)。只有在 `type` 為 `"prompted"` 時，才會在 `CreateVoice` 和 `GetVoice` 回應中填入；在 `ListVoices` 回應中，以及 `"replicated"` 或 `"prebuilt"` 語音中，則會取消設定。

用於語音建立的音訊有效負載。

欄位

資料 字串  (選填)

必填。原始音訊位元組。

mime_type string  (optional)

必填。音訊資料的 IANA MIME 類型 (例如 `audio/wav` 或 `audio/mpeg`)。

type VoiceType  (選用)

必填。語音類型。在 `CreateVoice` 中，必須是 `"replicated"` 或 `"prompted"`。在 `ListVoices` 回應中，也可能是 `"prebuilt"`。

可能的值

  • replicated

    從參考音訊樣本和說話者同意聲明錄音複製的自訂聲音。

  • prompted

    根據自然語言文字提示詞生成的自訂語音。

  • prebuilt

    Google 語音目錄中的內建系統語音 (例如 `Puck`、`Charon`)。會顯示在回覆中，但無法在 `CreateVoice` 中指定為類型。

usage Usage  (選填)

僅供輸出。語音建立要求的權杖用量統計資料。 只有在 `type` 為 `"prompted"` 時，才會在 `CreateVoice` 的回應中填入值；如果是 `"replicated"`，以及在 `GetVoice` 和 `ListVoices` 回應中，則不會填入值。

互動要求的權杖用量統計資料。

欄位

cached_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分快取權杖使用情形。

單一回覆模態的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

grounding_tool_count array (GroundingToolCount)  (optional)

基礎工具數量。

接地工具的數量。

欄位

count integer  (選填)

接地工具的數量。

類型 enum (string)  (選填)

與計數相關聯的基礎工具類型。

可能的值：

  • google_search

    以 Google 網頁搜尋和圖片搜尋建立基準，以及以企業適用的網路內容建立基準。

  • google_maps

    利用 Google 地圖建立基準。

input_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分的輸入權杖用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

output_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分的輸出內容詞元用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

tool_use_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分工具使用權杖用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

total_cached_tokens integer  (optional)

提示快取部分 (快取內容) 中的權杖數量。

total_input_tokens 整數  (選用)

提示 (脈絡) 中的權杖數量。

total_output_tokens 整數  (選用)

所有生成回覆的詞元總數。

total_thought_tokens integer  (optional)

思考模型思考時的權杖數量。

total_tokens 整數  (選用)

互動要求 (提示 + 回覆 + 其他內部權杖) 的權杖總數。

total_tool_use_tokens 整數  (選填)

工具使用提示中的權杖數量。

範例

回應範例

{
  "accent": "string",
  "context": "string",
  "description": "string",
  "display_name": "string",
  "expire_time": "string",
  "gender": "string",
  "id": "string",
  "key": "string",
  "language_code": "string",
  "model": "string",
  "persona": "string",
  "pitch": "low",
  "prompted": {
    "input": "string"
  },
  "region_code": "string",
  "replicated": {
    "consent_audio": {
      "data": "string",
      "mime_type": "string"
    },
    "source_audio": {
      "data": "string",
      "mime_type": "string"
    }
  },
  "sample_audio": {
    "data": "string",
    "mime_type": "string"
  },
  "type": "replicated",
  "usage": {
    "cached_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "grounding_tool_count": [
      {
        "count": 0,
        "type": "google_search"
      }
    ],
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "output_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "tool_use_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "total_thought_tokens": 0,
    "total_tokens": 0,
    "total_tool_use_tokens": 0
  }
}

ListVoices

get https://generativelanguage.googleapis.com/v1beta/voices

清單會先列出通話者擁有的自訂儲存語音 (依最新順序排列)， 接著列出 Google 語音目錄中的預建系統語音。

路徑 / 查詢參數

accent array (string)  (optional)

(選用步驟) 依口音說明篩選 (例如「美國」、「英國」)。 不區分大小寫的完全比對。如果指定多個值，系統會比對任何指定口音的語音 (OR)。

context array (string)  (optional)

(選用步驟) 依據預期脈絡或網域篩選 (例如「新聞、商業」)。不區分大小寫的完全比對。如果指定多個值，系統會比對語音與任何指定情境 (OR)。

gender array (string)  (選填)

(選用步驟) 依性別表現篩選 (例如「女性」、「男性」、「中性」)。 不區分大小寫的完全比對。如果指定多個值，系統會比對指定性別的聲音 (OR)。

language_code array (string)  (optional)

(選用步驟) 依 BCP-47 語言代碼篩選 (例如「en-US」)。 不區分大小寫的完全比對。如果指定多個值，系統會比對任何指定語言代碼的語音 (OR)。

page_size 整數  (選填)

(選用步驟) 每頁傳回的語音數量上限。服務傳回的產品數量可能會少於這個值。如未指定，最多將傳回 50 個語音。許可的最大值為 1000；超出的數值將一律指定為 1000。

page_token string  (選用)

(選用步驟) 先前 `ListVoices` 呼叫傳回的網頁符記。提供此項目即可擷取後續網頁。分頁時，所有篩選器查詢參數 (`language_code`、`region_code`、`accent`、`persona`、`context`、`gender`、`pitch`、`type` 和 `search`) 都必須與傳回這個權杖的呼叫相符，否則要求會因 `INVALID_ARGUMENT` 而失敗。`page_size` 可能會在不同頁面之間變更。

persona array (string)  (optional)

(選用步驟) 依據聲音特徵篩選 (例如「溫暖、友善」)。 不區分大小寫的完全比對。如果指定多個值，系統會比對任何指定角色 (OR) 的聲音。

pitch array (string)  (optional)

(選用步驟) 依音高篩選。可接受「low」、「medium」、「high」或「PITCH_LOW」、「PITCH_MEDIUM」、「PITCH_HIGH」(不區分大小寫)。如果指定多個值，系統會比對符合任一指定音調的聲音 (OR)。

region_code 陣列 (字串)  (選用)

(選用步驟) 依 ISO 3166-1 alpha-2 或 UN M.49 地區代碼篩選 (例如「US」、「001」)。不區分大小寫的完全比對。如果指定多個值，系統會比對語音與任何指定的區域代碼 (OR)。

search string  (選填)

(選用步驟) 不區分大小寫，針對 `display_name` 和 `description` 進行自由文字子字串搜尋查詢。最多 2048 個位元組。

type array (string)  (optional)

(選用步驟) 依語音類型篩選。接受「prebuilt」、「replicated」、「prompted」或「VOICE_TYPE_PREBUILT」、「VOICE_TYPE_REPLICATED」、「VOICE_TYPE_PROMPTED」(不區分大小寫)。如果指定多個值，系統會比對任何指定類型的聲音 (OR)。

回應

如果成功，回應主體會含有以下結構的資料：

next_page_token string  (選用)

可做為 `page_token` 傳送的權杖，用於擷取後續網頁。如果留空，表示沒有後續網頁。

voices 陣列 (Voice)  (選用)

指定集合中的語音。

範例

回應範例

{
  "next_page_token": "string",
  "voices": [
    {
      "accent": "string",
      "context": "string",
      "description": "string",
      "display_name": "string",
      "expire_time": "string",
      "gender": "string",
      "id": "string",
      "key": "string",
      "language_code": "string",
      "model": "string",
      "persona": "string",
      "pitch": "low",
      "prompted": {
        "input": "string"
      },
      "region_code": "string",
      "replicated": {
        "consent_audio": {
          "data": "string",
          "mime_type": "string"
        },
        "source_audio": {
          "data": "string",
          "mime_type": "string"
        }
      },
      "sample_audio": {
        "data": "string",
        "mime_type": "string"
      },
      "type": "replicated",
      "usage": {
        "cached_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "grounding_tool_count": [
          {
            "count": 0,
            "type": "google_search"
          }
        ],
        "input_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "output_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "tool_use_tokens_by_modality": [
          {
            "modality": "...",
            "tokens": 0
          }
        ],
        "total_cached_tokens": 0,
        "total_input_tokens": 0,
        "total_output_tokens": 0,
        "total_thought_tokens": 0,
        "total_tokens": 0,
        "total_tool_use_tokens": 0
      }
    }
  ]
}

GetVoice

get https://generativelanguage.googleapis.com/v1beta/voices/{voicesId}

依資源名稱取得自訂儲存語音 (`store = true`)。無法透過 `GetVoice` 擷取預建目錄語音 (`VOICE_TYPE_PREBUILT`)，請改用 `ListVoices`。

路徑 / 查詢參數

voicesId string  (必要)

必填。要擷取的自訂儲存語音資源名稱 (例如 `voices/voice_abc123def456`)。

回應

如果成功，回應主體會含有以下結構的資料：

accent string  (選填)

(選用步驟) 區域口音描述符 (例如「美式」、「英式」)。

context string  (選填)

(選用步驟) 最佳使用情境或網域 (例如「對話」、「有聲書」、「新聞」)。

description string  (選用)

(選用步驟) 描述聲音音色、特質和語氣的摘要。

display_name 字串  (選用)

(選用步驟) 儲存語音時使用者提供的顯示名稱 (`store = true`)， 或是預建語音的目錄名稱。

expire_time string  (optional)

僅供輸出。自訂儲存聲音 (`store = true`) 或複製聲音金鑰 (`store = false`) 的到期時間戳記。預建目錄語音 (`"prebuilt"`) 不會過期，因此無法取消設定。

gender string  (選填)

(選用步驟) 語音性別呈現方式 (例如「女性」、「男性」、「中性」)。

id string  (選用)

僅供輸出。語音的專屬 ID。 * 如果是 Google 管理的自訂語音 (`store = true`)，這是產生的 ID，前置字串為 `voice_` (例如 `voice_abc123def456`)。在 `GetVoice` 和 `DeleteVoice` 中，將 `voices/{id}` 做為 `name` 傳遞，並在語音合成期間，將 `{id}` 直接傳遞至 `SpeechConfig.voice_config.voice` (或 `SpeechConfig.voice`)。 * 如果是預先建構的目錄語音 (由 `ListVoices` 傳回的 `"prebuilt"`)，這是說話者名稱 (例如 `Puck` 或 `Charon`)。 * 使用 `store = false` 呼叫 `CreateVoice` 時，系統會取消設定。

key string  (選填)

僅供輸出。用戶端管理的語音複製金鑰 (前置字元為 `voicekey_`)。只有在 `type` 為 `"replicated"` 且 `store` 為 `false` 時，`CreateVoice` 才會傳回這項金鑰。在語音合成期間，請將這項金鑰傳遞至 `SpeechConfig.voice_config.voice` (或 `SpeechConfig.voice`)。

language_code string  (選用)

(選用步驟) 主要 BCP-47 語言標記 (例如「en-US」、「fr-FR」)。

model string  (選填)

(選用步驟) 用於設計或複製語音的模型。 如果 `CreateVoice` 中省略此欄位，系統會預設為最新支援的語音設計模型。在自訂語音 (`"prompted"` 和 `"replicated"`) 的 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中傳回；`"prebuilt"` 語音則未設定。建立的聲音可透過任何支援的文字轉語音合成模型合成。

persona string  (選填)

(選用步驟) 預期角色或人物原型 (例如「溫暖友善」、「旁白」)。

pitch 音調  (選填)

(選用步驟) 語音音調分類。

可能的值

  • low

    調低音調。

  • medium

    中音調。

  • high

    調高音調。

prompted PromptedVoice  (選填)

提示語音生成功能的參數。 如果 `type` 為 `"prompted"`，則 `CreateVoice` 中必須提供這項屬性。系統會在 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中，傳回提示語音的這項屬性。

提示語音生成功能所用的參數。 如果 `type` 為 `"prompted"`，則 `CreateVoice` 中必須提供這項屬性。系統會在 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中，傳回提示語音的這項屬性。

欄位

input string  (選用)

必填。描述所需語音的自然語言提示，例如「中年邪惡食人魔的低沉男聲」。

region_code string  (選用)

(選用步驟) ISO 3166-1 alpha-2 或 UN M.49 地理區域代碼 (例如「US」、「GB」、「001」)。

sample_audio AudioData  (選填)

僅供輸出。根據提示詞生成的語音樣本 (合成器提示詞音訊)。只有在 `type` 為 `"prompted"` 時，才會在 `CreateVoice` 和 `GetVoice` 回應中填入；在 `ListVoices` 回應中，以及 `"replicated"` 或 `"prebuilt"` 語音中，則會取消設定。

用於語音建立的音訊有效負載。

欄位

資料 字串  (選填)

必填。原始音訊位元組。

mime_type string  (optional)

必填。音訊資料的 IANA MIME 類型 (例如 `audio/wav` 或 `audio/mpeg`)。

type VoiceType  (選用)

必填。語音類型。在 `CreateVoice` 中，必須是 `"replicated"` 或 `"prompted"`。在 `ListVoices` 回應中，也可能是 `"prebuilt"`。

可能的值

  • replicated

    從參考音訊樣本和說話者同意聲明錄音複製的自訂聲音。

  • prompted

    根據自然語言文字提示詞生成的自訂語音。

  • prebuilt

    Google 語音目錄中的內建系統語音 (例如 `Puck`、`Charon`)。會顯示在回覆中，但無法在 `CreateVoice` 中指定為類型。

usage Usage  (選填)

僅供輸出。語音建立要求的權杖用量統計資料。 只有在 `type` 為 `"prompted"` 時，才會在 `CreateVoice` 的回應中填入值；如果是 `"replicated"`，以及在 `GetVoice` 和 `ListVoices` 回應中，則不會填入值。

互動要求的權杖用量統計資料。

欄位

cached_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分快取權杖使用情形。

單一回覆模態的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

grounding_tool_count array (GroundingToolCount)  (optional)

基礎工具數量。

接地工具的數量。

欄位

count integer  (選填)

接地工具的數量。

類型 enum (string)  (選填)

與計數相關聯的基礎工具類型。

可能的值：

  • google_search

    以 Google 網頁搜尋和圖片搜尋建立基準，以及以企業適用的網路內容建立基準。

  • google_maps

    利用 Google 地圖建立基準。

input_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分的輸入權杖用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

output_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分的輸出內容詞元用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

tool_use_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分工具使用權杖用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

total_cached_tokens integer  (optional)

提示快取部分 (快取內容) 中的權杖數量。

total_input_tokens 整數  (選用)

提示 (脈絡) 中的權杖數量。

total_output_tokens 整數  (選用)

所有生成回覆的詞元總數。

total_thought_tokens integer  (optional)

思考模型思考時的權杖數量。

total_tokens 整數  (選用)

互動要求 (提示 + 回覆 + 其他內部權杖) 的權杖總數。

total_tool_use_tokens 整數  (選填)

工具使用提示中的權杖數量。

範例

回應範例

{
  "accent": "string",
  "context": "string",
  "description": "string",
  "display_name": "string",
  "expire_time": "string",
  "gender": "string",
  "id": "string",
  "key": "string",
  "language_code": "string",
  "model": "string",
  "persona": "string",
  "pitch": "low",
  "prompted": {
    "input": "string"
  },
  "region_code": "string",
  "replicated": {
    "consent_audio": {
      "data": "string",
      "mime_type": "string"
    },
    "source_audio": {
      "data": "string",
      "mime_type": "string"
    }
  },
  "sample_audio": {
    "data": "string",
    "mime_type": "string"
  },
  "type": "replicated",
  "usage": {
    "cached_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "grounding_tool_count": [
      {
        "count": 0,
        "type": "google_search"
      }
    ],
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "output_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "tool_use_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 0
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "total_thought_tokens": 0,
    "total_tokens": 0,
    "total_tool_use_tokens": 0
  }
}

DeleteVoice

delete https://generativelanguage.googleapis.com/v1beta/voices/{voicesId}

依資源名稱刪除自訂儲存語音 (`store = true`)。無法刪除預建目錄語音 (`VOICE_TYPE_PREBUILT`)。

路徑 / 查詢參數

voicesId string  (必要)

必填。要刪除的自訂儲存語音資源名稱 (例如 `voices/voice_abc123def456`)。

回應

如果成功，回應會空白。

範例

資源

語音

語音資源，代表自訂語音 (透過 `CreateVoice` 建立) 或預建系統語音 (由 `ListVoices` 傳回)。

欄位

accent string  (選填)

(選用步驟) 區域口音描述符 (例如「美式」、「英式」)。

context string  (選填)

(選用步驟) 最佳使用情境或網域 (例如「對話」、「有聲書」、「新聞」)。

description string  (選用)

(選用步驟) 描述聲音音色、特質和語氣的摘要。

display_name 字串  (選用)

(選用步驟) 儲存語音時使用者提供的顯示名稱 (`store = true`)， 或是預建語音的目錄名稱。

expire_time string  (optional)

僅供輸出。自訂儲存聲音 (`store = true`) 或複製聲音金鑰 (`store = false`) 的到期時間戳記。預建目錄語音 (`"prebuilt"`) 不會過期，因此無法取消設定。

gender string  (選填)

(選用步驟) 語音性別呈現方式 (例如「女性」、「男性」、「中性」)。

id string  (選用)

僅供輸出。語音的專屬 ID。 * 如果是 Google 管理的自訂語音 (`store = true`)，這是產生的 ID，前置字串為 `voice_` (例如 `voice_abc123def456`)。在 `GetVoice` 和 `DeleteVoice` 中，將 `voices/{id}` 做為 `name` 傳遞，並在語音合成期間，將 `{id}` 直接傳遞至 `SpeechConfig.voice_config.voice` (或 `SpeechConfig.voice`)。 * 如果是預先建構的目錄語音 (由 `ListVoices` 傳回的 `"prebuilt"`)，這是說話者名稱 (例如 `Puck` 或 `Charon`)。 * 使用 `store = false` 呼叫 `CreateVoice` 時，系統會取消設定。

key string  (選填)

僅供輸出。用戶端管理的語音複製金鑰 (前置字元為 `voicekey_`)。只有在 `type` 為 `"replicated"` 且 `store` 為 `false` 時，`CreateVoice` 才會傳回這項金鑰。在語音合成期間，請將這項金鑰傳遞至 `SpeechConfig.voice_config.voice` (或 `SpeechConfig.voice`)。

language_code string  (選用)

(選用步驟) 主要 BCP-47 語言標記 (例如「en-US」、「fr-FR」)。

model string  (選填)

(選用步驟) 用於設計或複製語音的模型。 如果 `CreateVoice` 中省略此欄位，系統會預設為最新支援的語音設計模型。在自訂語音 (`"prompted"` 和 `"replicated"`) 的 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中傳回；`"prebuilt"` 語音則未設定。建立的聲音可透過任何支援的文字轉語音合成模型合成。

persona string  (選填)

(選用步驟) 預期角色或人物原型 (例如「溫暖友善」、「旁白」)。

pitch 音調  (選填)

(選用步驟) 語音音調分類。

可能的值

  • low

    調低音調。

  • medium

    中音調。

  • high

    調高音調。

prompted PromptedVoice  (選填)

提示語音生成功能的參數。 如果 `type` 為 `"prompted"`，則 `CreateVoice` 中必須提供這項屬性。系統會在 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中，傳回提示式語音的這項屬性。

提示語音生成功能所用的參數。 如果 `type` 為 `"prompted"`，則 `CreateVoice` 中必須提供這項屬性。系統會在 `CreateVoice`、`GetVoice` 和 `ListVoices` 回應中，傳回提示語音的這項屬性。

欄位

input string  (選用)

必填。描述所需語音的自然語言提示，例如「中年邪惡食人魔的低沉男聲」。

region_code string  (選用)

(選用步驟) ISO 3166-1 alpha-2 或 UN M.49 地理區域代碼 (例如「US」、「GB」、「001」)。

sample_audio AudioData  (選填)

僅供輸出。根據提示詞生成的語音樣本 (合成器提示詞音訊)。只有在 `type` 為 `"prompted"` 時，才會在 `CreateVoice` 和 `GetVoice` 回應中填入；在 `ListVoices` 回應中，以及 `"replicated"` 或 `"prebuilt"` 語音中，則會取消設定。

用於語音建立的音訊有效負載。

欄位

資料 字串  (選填)

必填。原始音訊位元組。

mime_type string  (optional)

必填。音訊資料的 IANA MIME 類型 (例如 `audio/wav` 或 `audio/mpeg`)。

type VoiceType  (選用)

必填。語音類型。在 `CreateVoice` 中，必須是 `"replicated"` 或 `"prompted"`。在 `ListVoices` 回應中，也可能是 `"prebuilt"`。

可能的值

  • replicated

    從參考音訊樣本和說話者同意聲明錄音複製的自訂聲音。

  • prompted

    根據自然語言文字提示詞生成的自訂語音。

  • prebuilt

    Google 語音目錄中的內建系統語音 (例如 `Puck`、`Charon`)。會顯示在回覆中，但無法在 `CreateVoice` 中指定為類型。

usage Usage  (選填)

僅供輸出。語音建立要求的權杖用量統計資料。 只有在 `type` 為 `"prompted"` 時，才會在 `CreateVoice` 的回應中填入值；如果是 `"replicated"`，則不會填入值，且 `GetVoice` 和 `ListVoices` 回應中也不會填入值。

互動要求的權杖用量統計資料。

欄位

cached_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分快取權杖使用情形。

單一回覆模態的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

grounding_tool_count array (GroundingToolCount)  (optional)

基礎工具數量。

接地工具的數量。

欄位

count integer  (選填)

接地工具的數量。

類型 enum (string)  (選填)

與計數相關聯的基礎工具類型。

可能的值：

  • google_search

    以 Google 網頁搜尋和圖片搜尋建立基準，以及以企業適用的網路內容建立基準。

  • google_maps

    利用 Google 地圖建立基準。

input_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分的輸入權杖用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

output_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分的輸出內容詞元用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

tool_use_tokens_by_modality array (ModalityTokens)  (optional)

依模式細分工具使用權杖用量。

單一回覆模式的詞元數。

欄位

modality ResponseModality  (optional)

與詞元數相關的模態。

可能的值

  • text

    表示模型應傳回文字。

  • image

    表示模型應傳回圖片。

  • audio

    表示模型應傳回音訊。

  • video

    表示模型應傳回影片。

  • document

    表示模型應傳回文件。

tokens 整數  (選填)

模態的權杖數量。

total_cached_tokens integer  (optional)

提示快取部分 (快取內容) 中的權杖數量。

total_input_tokens 整數  (選用)

提示 (脈絡) 中的權杖數量。

total_output_tokens 整數  (選用)

所有生成回覆的詞元總數。

total_thought_tokens integer  (optional)

思考模型思考時的權杖數量。

total_tokens 整數  (選用)

互動要求 (提示 + 回覆 + 其他內部權杖) 的權杖總數。

total_tool_use_tokens 整數  (選填)

工具使用提示中的權杖數量。