Gemini Voices API

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

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

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

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

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

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

仅限输出。自定义存储语音（`store = true`）或复制语音密钥（`store = false`）的过期时间戳。对于自定义存储的声音（`store = true`），当该声音用于语音合成或在 `CreateVoice` 中用作 `base_voice` 时，此过期时间会延长。对于预构建的目录声音（“prebuilt”），此属性处于未设置状态，因为这些声音不会过期。

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

仅限输出。语音的唯一标识符。 * 对于 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，则未设置。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

指定集合中的声音。

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

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

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

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

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

仅限输出。自定义存储语音（`store = true`）或复制语音密钥（`store = false`）的过期时间戳。对于自定义存储的声音（`store = true`），当该声音用于语音合成或在 `CreateVoice` 中用作 `base_voice` 时，此过期时间会延长。对于预构建的目录声音（“prebuilt”），此属性处于未设置状态，因为这些声音不会过期。

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

仅限输出。语音的唯一标识符。 * 对于 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，则未设置。

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

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

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

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

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

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