列出音色

通过搜索、筛选和分页获取用户所有可用音色的列表。

请求头

xi-api-keystring可选

查询参数

next_page_tokenstring or null可选

用于分页的下一页令牌。由上一个请求返回。请结合 has_more 标志使用,以实现可靠分页。

page_sizeinteger可选默认为 10

最多返回的音色数量。不能超过 100,默认为 10。由于包含默认音色,第 0 页可能包含更多音色。

searchstring or null可选

用于筛选音色的搜索词。搜索名称、描述、标签和类别。

sortstring or null可选

用于排序的字段,‘created_at_unix’ 或 ‘name’ 之一。较早创建的音色可能没有 ‘created_at_unix’。

sort_directionstring or null可选

音色排序方向:‘asc’ 或 ‘desc’。

voice_typestring or null可选
用于筛选的音色类型。可选值为 'personal'、'community'、'default'、'workspace'、'non-default'、'non-community'、'saved'。'non-default' 表示除 'default' 外的所有类型。'non-community' 表示 'personal' 和 'workspace' 的组合(不包括声音库副本)。'saved' 等同于 non-default,但也包含已添加到收藏集的默认音色。
categorystring or null可选
Category of the voice to filter by. One of 'premade', 'cloned', 'generated', 'professional'
fine_tuning_statestring or null可选

用于筛选的音色微调状态。仅适用于专业语音克隆。可选值:‘draft’、‘not_verified’、‘not_started’、‘queued’、‘fine_tuning’、‘fine_tuned’、‘failed’、‘delayed’。

collection_idstring or null可选
Collection ID to filter voices by.
genderstring or null可选

基于音色的 ‘gender’ 标签,用于筛选的性别。

agestring or null可选

根据音色的 ‘age’ 标签筛选年龄。

languagelist of strings or null可选

根据音色的“language”标签筛选所用的语言。将返回匹配任一指定语言的音色。

accentstring or null可选

根据音色的 ‘accent’ 标签进行筛选的口音。

use_caseslist of strings or null可选

基于音色的 ‘use_case’ 标签进行筛选的使用场景。返回符合任一给定使用场景的音色。

min_notice_period_daysinteger or null可选

仅筛选共享通知期不少于指定天数的音色。

include_custom_ratesboolean or null可选

是否包含设置了自定义共享费率的音色。默认包含。

include_live_moderatedboolean or null可选

是否包含启用了实时审核的音色。默认包含。

high_qualityboolean or null可选

设为 true 时,仅返回录音室品质音色(类别为 ‘high_quality’ 的音色)。

include_total_countboolean可选默认为 true

是否在响应中包含找到的音色总数。注意:total_count 值是实时快照,用户创建、修改或删除音色后,该值可能在请求之间发生变化。分页时请使用 has_more 标志。仅在确实需要总数时启用此项(例如用于展示),因为会影响性能。

voice_idslist of strings or null可选

要查询的音色 ID。最多 100 个音色 ID。

响应

成功响应

voiceslist of objects

与查询匹配的音色列表。

has_moreboolean

指示后续页面是否还有更多可用音色。请使用此标记(以及 next_page_token)进行可靠分页,而非依赖 total_count。

total_countinteger

符合查询条件的音色总数。此值是反映数据库当前状态的实时快照,用户创建、修改或删除音色时,可能在请求之间发生变化。为确保分页可靠,请使用 has_more 标志,而非依赖此值。仅在确实需要总数时才请求此字段(例如用于显示),因为计算它会产生性能开销。

next_page_tokenstring or null可选

用于获取下一页结果的令牌。将此值传入下一次请求以继续分页。没有更多结果时为 Null。

错误

422
Unprocessable Entity Error