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 布尔值  （选填）

可选。所创建的声音是否由 Google 持久保存和管理。 * 如果为 `true`，Google 会存储语音并返回 `Voice.id`（例如 `voice_abc123def456`），该 ID 可通过 `GetVoice`、`ListVoices` 和 `DeleteVoice` 进行管理，并在合成请求中通过 ID 进行引用。项目受有效存储语音配额上限的限制；超出配额会返回 `RESOURCE_EXHAUSTED`。 * 如果为 `false`（默认值），Google 不会存储语音，而是返回 `Voice.key`（例如 `voicekey_…`）以供客户端存储和合成。当 `store` 为 `false` 时，不会保留或返回 `voice` 上的可选发现元数据字段。 * 当 `voice.type` 为 `"prompted"` 时，必须为 `true`（否则会因 `INVALID_ARGUMENT` 而失败）。

语音 语音  （必需）

必需。要创建的声音。 `voice.model` 是可选的；如果省略，服务会选择默认的语音创建模型。如果设置了“Voice”上的仅输出字段（“id”“key”“expire_time”“usage”），系统会忽略这些字段。

响应

如果成功，响应正文将包含结构如下的数据：

accent string  （选填）

可选。地区口音描述符（例如“美式”“英式”）。

context string  （选填）

可选。最佳使用情境或网域（例如“对话”“有声读物”“新闻”）。

说明 字符串  （可选）

可选。对声音音色、个性和语气的描述性总结。

display_name 字符串  （选填）

可选。用户为存储的语音提供的显示名称（<code>store = true</code>），或预建语音的目录名称。

expire_time string  （选填）

仅限输出。自定义存储语音（`store = true`）或复制语音密钥（`store = false`）的过期时间戳。针对不会过期的预构建目录语音（“预构建”）取消设置。

gender string  （选填）

可选。感知到的声音性别呈现（例如“女性”“男性”“中性”）。

id string  （选填）

仅限输出。语音的唯一标识符。 * 对于 Google 管理的自定义声音（`store = true`），这是一个带有前缀 `voice_` 的生成 ID（例如，`voice_abc123def456`）。在 `GetVoice` 和 `DeleteVoice` 中，将 `voices/{id}` 作为 `name` 传递；在语音合成期间，将 `{id}` 直接传递给 `SpeechConfig.voice_config.voice`（或 `SpeechConfig.voice`）。 * 对于预构建的目录语音（由 `ListVoices` 返回的 `"prebuilt"`），这是说话人名称（例如 `Puck` 或 `Charon`）。 * 如果在调用 `CreateVoice` 时将 `store` 设置为 `false`，则未设置。

key string  （选填）

仅限输出。客户端管理的语音复刻密钥（带有前缀“voicekey_”）。仅当“type”为“replicated”且“store”为“false”时，由“CreateVoice”返回。在语音合成期间，将此密钥传递给“SpeechConfig.voice_config.voice”（或“SpeechConfig.voice”）。

language_codelanguage_code 字符串  （可选）

可选。主要 BCP-47 语言标记（例如“en-US”“fr-FR”）。

model string  （选填）

可选。用于设计或复制语音的模型。 如果 `CreateVoice` 中省略了此参数，则默认为最新支持的语音设计模型。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对自定义语音（“prompted”和“replicated”）返回；对于“prebuilt”语音，则未设置。创建的语音可以跨任何受支持的 TTS 合成模型进行合成。

角色 字符串  （选填）

可选。预期的人设或角色原型（例如“热情友好”“旁白”）。

音调 音调  （选填）

可选。语音音调分类。

可能的值

  • low

    调低音调。

  • medium

    中等音调的声音。

  • high

    调高音调。

提示 PromptedVoice  （可选）

提示式语音生成的参数。 当 `type` 为 `"prompted"` 时，在 `CreateVoice` 中是必需的。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对提示的语音返回。

提示式语音生成的参数。 当 `type` 为 `"prompted"` 时，在 `CreateVoice` 中是必需的。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对提示的语音返回。

字段

输入 字符串  （可选）

必需。描述所需声音的自然语言提示，例如“一个中年邪恶巨魔的低沉洪亮的男声”。

region_code 字符串  （可选）

可选。ISO 3166-1 alpha-2 或联合国 M.49 地理区域代码（例如“US”“GB”“001”）。

sample_audio AudioData  （可选）

仅限输出。为提示的语音生成的音频样本（合成器提示音频）。 仅在 `CreateVoice` 和 `GetVoice` 响应中填充（当 `type` 为“prompted”时）；在 `ListVoices` 响应中以及对于“replicated”或“prebuilt”语音，此字段处于未设置状态。

用于语音创建的音频载荷。

字段

data string  （选填）

必需。原始音频字节。

mime_type 字符串  （选填）

必需。音频数据的 IANA MIME 类型（例如 `audio/wav` 或 `audio/mpeg`）。

type VoiceType  （可选）

必需。语音类型。在 `CreateVoice` 中，必须为 `"replicated"` 或 `"prompted"`。在 `ListVoices` 响应中，也可以为 `"prebuilt"`。

可能的值

  • replicated

    根据参考音频样本和发言者同意书录制内容复制的自定义语音。

  • prompted

    根据自然语言文本提示生成的自定义语音。

  • prebuilt

    Google 语音目录中的内置系统语音（例如 `Puck`、`Charon`）。在响应中返回；无法在 `CreateVoice` 中指定为类型。

用法 用法  （可选）

仅限输出。语音创建请求的令牌使用情况统计信息。 仅在 `CreateVoice` 的响应中填充（当 `type` 为 `"prompted"` 时）；对于 `"replicated"` 以及 `GetVoice` 和 `ListVoices` 响应，则未设置。

互动请求的令牌使用情况统计信息。

字段

cached_tokens_by_modality array (ModalityTokens)  （可选）

按模态划分的缓存 token 使用情况细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

grounding_tool_count 数组 (GroundingToolCount)  （可选）

接地工具数量。

接地工具数量。

字段

数量 整数  （可选）

接地工具数量。

type enum (string)  (optional)

与数量关联的接地工具类型。

可能的值：

  • google_search

    依托 Google 网页搜索和图片搜索进行接地，以及适用于企业的 Web 接地。

  • google_maps

    Grounding with Google Maps

input_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的输入 token 使用情况细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

output_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的输出 token 用量细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

tool_use_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的工具使用情况令牌用量细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

total_cached_tokens integer  （可选）

提示的缓存部分（缓存内容）中的 token 数量。

total_input_tokens integer  （可选）

提示（上下文）中的 token 数量。

total_output_tokens integer  （可选）

所有生成的回答中的 token 总数。

total_thought_tokens integer  （可选）

思考模型的想法的 token 数量。

total_tokens integer  （可选）

互动请求（提示 + 回答 + 其他内部 token）的总 token 数量。

total_tool_use_tokens integer  （可选）

工具使用提示中的 token 数量。

示例

示例响应

{
  "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 数组（字符串）  （选填）

可选。按口音说明（例如“美式”“英式”）过滤。 不区分大小写的完全匹配。如果指定了多个值，则匹配具有任意指定口音的语音（OR）。

context array (string)  （选填）

可选。按预期上下文或网域（例如“新闻、商业”）过滤。 不区分大小写的完全匹配。如果指定了多个值，则匹配具有任意指定上下文的语音（OR）。

适用性别 数组（字符串）  （选填）

可选。按性别表达过滤（例如“女性”“男性”“中性”）。 不区分大小写的完全匹配。如果指定了多个值，则匹配具有任意指定性别的声音 (OR)。

language_code 数组（字符串）  （可选）

可选。按 BCP-47 语言代码（例如“en-US”）过滤。 不区分大小写的完全匹配。如果指定了多个值，则匹配具有任何指定语言代码的声音 (OR)。

page_size integer  （可选）

可选。每页返回的最大声音数量。服务返回的值可能小于此值。如果未指定，则最多返回 50 个声音。最大值为 1000；大于 1000 的值会强制转换为 1000。

page_token string  （可选）

可选。从之前的 `ListVoices` 调用接收的页面令牌。提供此令牌可检索后续页面。 进行分页时，所有过滤查询参数（`language_code`、`region_code`、`accent`、`persona`、`context`、`gender`、`pitch`、`type` 和 `search`）都必须与返回此令牌的调用相匹配；否则，请求会因 `INVALID_ARGUMENT` 而失败。`page_size` 在不同页面之间可能会发生变化。

角色 数组（字符串）  （选填）

可选。按声音角色过滤（例如“温暖、友好”）。 不区分大小写的完全匹配。如果指定了多个值，则匹配具有任意指定角色特征的声音（OR）。

音调 数组（字符串）  （选填）

可选。按人声音调过滤。接受“低”“中”“高”或“PITCH_LOW”“PITCH_MEDIUM”“PITCH_HIGH”（不区分大小写）。如果指定了多个值，则匹配具有任何指定音高的声音（OR）。

region_code 数组（字符串）  （可选）

可选。按 ISO 3166-1 alpha-2 或联合国 M.49 地区代码（例如“US”“001”）过滤。 不区分大小写的完全匹配。如果指定了多个值，则匹配具有任何指定区域代码（OR）的语音。

搜索 字符串  （选填）

可选。自由文本子字符串搜索查询，不区分大小写地与 `display_name` 和 `description` 进行匹配。长度上限为 2048 字节。

类型 数组（字符串）  （选填）

可选。按语音类型过滤。接受“prebuilt”“replicated”“prompted”或“VOICE_TYPE_PREBUILT”“VOICE_TYPE_REPLICATED”“VOICE_TYPE_PROMPTED”（不区分大小写）。如果指定了多个值，则匹配具有任意指定类型的声音（OR）。

响应

如果成功，响应正文将包含结构如下的数据：

next_page_token 字符串  （可选）

可作为 `page_token` 发送并用于检索下一页的令牌。 如果为空，则表示没有后续页面。

声音 数组 (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  （选填）

可选。最佳使用情境或网域（例如“对话”“有声读物”“新闻”）。

说明 字符串  （可选）

可选。对声音音色、个性和语气的描述性总结。

display_name 字符串  （选填）

可选。用户为存储的语音提供的显示名称（<code>store = true</code>），或预建语音的目录名称。

expire_time string  （选填）

仅限输出。自定义存储语音（`store = true`）或复制语音密钥（`store = false`）的过期时间戳。针对不会过期的预构建目录语音（“预构建”）取消设置。

gender string  （选填）

可选。感知到的声音性别呈现（例如“女性”“男性”“中性”）。

id string  （选填）

仅限输出。语音的唯一标识符。 * 对于 Google 管理的自定义声音（`store = true`），这是一个带有前缀 `voice_` 的生成 ID（例如，`voice_abc123def456`）。在 `GetVoice` 和 `DeleteVoice` 中，将 `voices/{id}` 作为 `name` 传递；在语音合成期间，将 `{id}` 直接传递给 `SpeechConfig.voice_config.voice`（或 `SpeechConfig.voice`）。 * 对于预构建的目录语音（由 `ListVoices` 返回的 `"prebuilt"`），这是说话人名称（例如 `Puck` 或 `Charon`）。 * 如果在调用 `CreateVoice` 时将 `store` 设置为 `false`，则未设置。

key string  （选填）

仅限输出。客户端管理的语音复刻密钥（带有前缀“voicekey_”）。仅当“type”为“replicated”且“store”为“false”时，由“CreateVoice”返回。在语音合成期间，将此密钥传递给“SpeechConfig.voice_config.voice”（或“SpeechConfig.voice”）。

language_codelanguage_code 字符串  （可选）

可选。主要 BCP-47 语言标记（例如“en-US”“fr-FR”）。

model string  （选填）

可选。用于设计或复制语音的模型。 如果 `CreateVoice` 中省略了此参数，则默认为最新支持的语音设计模型。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对自定义语音（“prompted”和“replicated”）返回；对于“prebuilt”语音，则未设置。创建的语音可以跨任何受支持的 TTS 合成模型进行合成。

角色 字符串  （选填）

可选。预期的人设或角色原型（例如“热情友好”“旁白”）。

音调 音调  （选填）

可选。语音音调分类。

可能的值

  • low

    调低音调。

  • medium

    中等音调的声音。

  • high

    调高音调。

提示 PromptedVoice  （可选）

提示式语音生成的参数。 当 `type` 为 `"prompted"` 时，在 `CreateVoice` 中是必需的。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对提示的语音返回。

提示式语音生成的参数。 当 `type` 为 `"prompted"` 时，在 `CreateVoice` 中是必需的。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对提示的语音返回。

字段

输入 字符串  （可选）

必需。描述所需声音的自然语言提示，例如“一个中年邪恶巨魔的低沉洪亮的男声”。

region_code 字符串  （可选）

可选。ISO 3166-1 alpha-2 或联合国 M.49 地理区域代码（例如“US”“GB”“001”）。

sample_audio AudioData  （可选）

仅限输出。为提示的语音生成的音频样本（合成器提示音频）。 仅在 `CreateVoice` 和 `GetVoice` 响应中填充（当 `type` 为“prompted”时）；在 `ListVoices` 响应中以及对于“replicated”或“prebuilt”语音，此字段处于未设置状态。

用于语音创建的音频载荷。

字段

data string  （选填）

必需。原始音频字节。

mime_type 字符串  （选填）

必需。音频数据的 IANA MIME 类型（例如 `audio/wav` 或 `audio/mpeg`）。

type VoiceType  （可选）

必需。语音类型。在 `CreateVoice` 中，必须为 `"replicated"` 或 `"prompted"`。在 `ListVoices` 响应中，也可以为 `"prebuilt"`。

可能的值

  • replicated

    根据参考音频样本和发言者同意书录制内容复制的自定义语音。

  • prompted

    根据自然语言文本提示生成的自定义语音。

  • prebuilt

    Google 语音目录中的内置系统语音（例如 `Puck`、`Charon`）。在响应中返回；无法在 `CreateVoice` 中指定为类型。

用法 用法  （可选）

仅限输出。语音创建请求的令牌使用情况统计信息。 仅在 `CreateVoice` 的响应中填充（当 `type` 为 `"prompted"` 时）；对于 `"replicated"` 以及 `GetVoice` 和 `ListVoices` 响应，则未设置。

互动请求的令牌使用情况统计信息。

字段

cached_tokens_by_modality array (ModalityTokens)  （可选）

按模态划分的缓存 token 使用情况细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

grounding_tool_count 数组 (GroundingToolCount)  （可选）

接地工具数量。

接地工具数量。

字段

数量 整数  （可选）

接地工具数量。

type enum (string)  (optional)

与数量关联的接地工具类型。

可能的值：

  • google_search

    依托 Google 网页搜索和图片搜索进行接地，以及适用于企业的 Web 接地。

  • google_maps

    Grounding with Google Maps

input_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的输入 token 使用情况细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

output_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的输出 token 用量细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

tool_use_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的工具使用情况令牌用量细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

total_cached_tokens integer  （可选）

提示的缓存部分（缓存内容）中的 token 数量。

total_input_tokens integer  （可选）

提示（上下文）中的 token 数量。

total_output_tokens integer  （可选）

所有生成的回答中的 token 总数。

total_thought_tokens integer  （可选）

思考模型的想法的 token 数量。

total_tokens integer  （可选）

互动请求（提示 + 回答 + 其他内部 token）的总 token 数量。

total_tool_use_tokens integer  （可选）

工具使用提示中的 token 数量。

示例

示例响应

{
  "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}

按资源名称删除自定义存储的声音（<code>store = true</code>）。 无法删除预构建的目录语音 (`VOICE_TYPE_PREBUILT`)。

路径 / 查询参数

voicesId string  （必需）

必需。要删除的自定义存储语音的资源名称（例如，`voices/voice_abc123def456`）。

响应

如果成功，则响应为空。

示例

资源

语音

一种语音资源，表示自定义语音（通过 `CreateVoice` 创建）或预构建的系统语音（由 `ListVoices` 返回）。

字段

accent string  （选填）

可选。地区口音描述符（例如“美式”“英式”）。

context string  （选填）

可选。最佳使用情境或网域（例如“对话”“有声读物”“新闻”）。

说明 字符串  （可选）

可选。对声音音色、个性和语气的描述性总结。

display_name 字符串  （选填）

可选。用户为存储的语音提供的显示名称（<code>store = true</code>），或预建语音的目录名称。

expire_time string  （选填）

仅限输出。自定义存储语音（`store = true`）或复制语音密钥（`store = false`）的过期时间戳。针对不会过期的预构建目录语音（“预构建”）取消设置。

gender string  （选填）

可选。感知到的声音性别呈现（例如“女性”“男性”“中性”）。

id string  （选填）

仅限输出。语音的唯一标识符。 * 对于 Google 管理的自定义声音（`store = true`），这是一个带有前缀 `voice_` 的生成 ID（例如，`voice_abc123def456`）。在 `GetVoice` 和 `DeleteVoice` 中，将 `voices/{id}` 作为 `name` 传递；在语音合成期间，将 `{id}` 直接传递给 `SpeechConfig.voice_config.voice`（或 `SpeechConfig.voice`）。 * 对于预构建的目录语音（由 `ListVoices` 返回的 `"prebuilt"`），这是说话人名称（例如 `Puck` 或 `Charon`）。 * 如果在调用 `CreateVoice` 时将 `store` 设置为 `false`，则未设置。

key string  （选填）

仅限输出。客户端管理的语音复刻密钥（带有前缀“voicekey_”）。仅当“type”为“replicated”且“store”为“false”时，由“CreateVoice”返回。在语音合成期间，将此密钥传递给“SpeechConfig.voice_config.voice”（或“SpeechConfig.voice”）。

language_codelanguage_code 字符串  （可选）

可选。主要 BCP-47 语言标记（例如“en-US”“fr-FR”）。

model string  （选填）

可选。用于设计或复制语音的模型。 如果 `CreateVoice` 中省略了此参数，则默认为最新支持的语音设计模型。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对自定义语音（“prompted”和“replicated”）返回；对于“prebuilt”语音，则未设置。创建的语音可以跨任何受支持的 TTS 合成模型进行合成。

角色 字符串  （选填）

可选。预期的人设或角色原型（例如“热情友好”“旁白”）。

音调 音调  （选填）

可选。语音音调分类。

可能的值

  • low

    调低音调。

  • medium

    中等音调的声音。

  • high

    调高音调。

提示 PromptedVoice  （可选）

提示语音生成的参数。 当 `type` 为 `"prompted"` 时，在 `CreateVoice` 中是必需的。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对提示的语音返回。

提示式语音生成的参数。 当 `type` 为 `"prompted"` 时，在 `CreateVoice` 中是必需的。在 `CreateVoice`、`GetVoice` 和 `ListVoices` 响应中针对提示的语音返回。

字段

输入 字符串  （可选）

必需。描述所需声音的自然语言提示，例如“一个中年邪恶巨魔的低沉洪亮的男声”。

region_code 字符串  （可选）

可选。ISO 3166-1 alpha-2 或联合国 M.49 地理区域代码（例如“US”“GB”“001”）。

sample_audio AudioData  （可选）

仅限输出。为提示的语音生成的音频样本（合成器提示音频）。 仅在 `CreateVoice` 和 `GetVoice` 响应中填充（当 `type` 为“prompted”时）；在 `ListVoices` 响应中以及对于“replicated”或“prebuilt”语音，此字段处于未设置状态。

用于语音创建的音频载荷。

字段

data string  （选填）

必需。原始音频字节。

mime_type 字符串  （选填）

必需。音频数据的 IANA MIME 类型（例如 `audio/wav` 或 `audio/mpeg`）。

type VoiceType  （可选）

必需。语音类型。在 `CreateVoice` 中，必须为 `"replicated"` 或 `"prompted"`。在 `ListVoices` 响应中，也可以为 `"prebuilt"`。

可能的值

  • replicated

    根据参考音频样本和发言者同意书录制内容复制的自定义语音。

  • prompted

    根据自然语言文本提示生成的自定义语音。

  • prebuilt

    Google 语音目录中的内置系统语音（例如 `Puck`、`Charon`）。在响应中返回；无法在 `CreateVoice` 中指定为类型。

用法 用法  （可选）

仅限输出。语音创建请求的令牌使用情况统计信息。 仅在 `CreateVoice` 的响应中填充（当 `type` 为 `"prompted"` 时）；对于 `"replicated"` 以及 `GetVoice` 和 `ListVoices` 响应，则未设置。

互动请求的令牌使用情况统计信息。

字段

cached_tokens_by_modality array (ModalityTokens)  （可选）

按模态划分的缓存 token 使用情况细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

grounding_tool_count 数组 (GroundingToolCount)  （可选）

接地工具数量。

接地工具数量。

字段

数量 整数  （可选）

接地工具数量。

type enum (string)  (optional)

与数量关联的接地工具类型。

可能的值：

  • google_search

    依托 Google 网页搜索和图片搜索进行接地，以及适用于企业的 Web 接地。

  • google_maps

    Grounding with Google Maps

input_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的输入 token 使用情况细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

output_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的输出 token 用量细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

tool_use_tokens_by_modality array (ModalityTokens)  (optional)

按模态划分的工具使用情况令牌用量细分。

单个回答模态的 token 数量。

字段

modality ResponseModality  （可选）

与 token 数量关联的模态。

可能的值

  • text

    表示模型应返回文本。

  • image

    表示模型应返回图片。

  • audio

    表示模型应返回音频。

  • video

    表示模型应返回视频。

  • document

    表示模型应返回文档。

token 整数  （选填）

模态的 token 数量。

total_cached_tokens integer  （可选）

提示的缓存部分（缓存内容）中的 token 数量。

total_input_tokens integer  （可选）

提示（上下文）中的 token 数量。

total_output_tokens integer  （可选）

所有生成的回答中的 token 总数。

total_thought_tokens integer  （可选）

思考模型的想法的 token 数量。

total_tokens integer  （可选）

互动请求（提示 + 回答 + 其他内部 token）的总 token 数量。

total_tool_use_tokens integer  （可选）

工具使用提示中的 token 数量。