列出可用于语音合成的声音，包括公共声音库和自己克隆的声音。可选按 locale 和/或 provider 筛选。传入 limit，并使用返回的 next_cursor 对筛选后的公共声音库分页；不传 limit 时，在一次响应中返回完整列表。
请求头
X-API-Keystring必填你的 VisionStory API Key（sk-vs-...），请仅保存在服务端。可在 API Key 管理 中创建或管理，需要 Pro 或更高方案。
查询参数
cursorintegerpublic_voices 的分页游标，取自上一页的 next_cursor。省略或传入 0 时查询第一页。
默认值： 0
limitinteger | null每页最多返回的 public_voices 数量，范围为 1–500。省略时不分页，返回完整声音库；my_voices 始终在第一页完整返回。
localestring | null按 BCP 47 语言区域标记筛选，不区分大小写。单独的语言代码（例如 en 或 zh）匹配该语言的所有区域变体；en-GB / zh-TW / zh-HK 仅匹配相应区域。请参阅每个声音的 locale 字段。
providerstring | null按声音引擎筛选，不区分大小写：elevenlabs / seed / gemini / minimax。
响应
200请求成功
application/json
dataGetVoicesResponse | null必填可为空当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。
my_voicesVoiceDto[]必填当前账户克隆的声音。使用分页时仅在第一页返回。
accentstring口音，例如 american / british / mandarin；可能为空。
agestring听感年龄段，例如 young / middle-aged / old；可能为空。
genderstring声音性别，例如 male / female；可能为空。
is_freeboolean必填此声音是否可在免费方案中使用；高级声音需要付费方案。
languagestring必填便于阅读的主要语言名称，例如 english。机器可读的语言标记请使用 locale。
localestring此声音的 BCP 47 语言区域标记，例如 en-US / en-GB / zh-TW / zh-HK。区域未知时仅返回语言代码；由提示词驱动的声音（gemini）为空。使用 locale 筛选，并将相同值作为 POST /api/v1/tts 的 locale 传入，以指定发音。
preview_audio_urlstring必填用于试听该声音的短音频片段 URL。
providerstring此声音所属的语音引擎（例如 elevenlabs / gemini / minimax），便于按引擎选择声音。使用 provider 筛选。此信息仅供参考，并非保证：合成时可能回退到其他引擎。
tagsstring | null可为空用于辅助选择声音的自由文本描述。已由下方结构化字段替代，但为兼容保留，可能为空。
use_casesstring[]建议使用场景，例如 narration / conversational；可能为空。
voice_idstring必填声音标识符。在文本脚本中作为 voice_id 传入，或在转换上传音频时作为目标声音。
next_cursorintegerpublic_voices 下一页的游标，将其作为 cursor 传回。0 表示没有更多页面；未使用分页时始终为 0。
public_voicesVoiceDto[]必填平台提供的可用于文本转语音的声音。
accentstring口音，例如 american / british / mandarin；可能为空。
agestring听感年龄段，例如 young / middle-aged / old；可能为空。
genderstring声音性别，例如 male / female；可能为空。
is_freeboolean必填此声音是否可在免费方案中使用；高级声音需要付费方案。
languagestring必填便于阅读的主要语言名称，例如 english。机器可读的语言标记请使用 locale。
localestring此声音的 BCP 47 语言区域标记，例如 en-US / en-GB / zh-TW / zh-HK。区域未知时仅返回语言代码；由提示词驱动的声音（gemini）为空。使用 locale 筛选，并将相同值作为 POST /api/v1/tts 的 locale 传入，以指定发音。
preview_audio_urlstring必填用于试听该声音的短音频片段 URL。
providerstring此声音所属的语音引擎（例如 elevenlabs / gemini / minimax），便于按引擎选择声音。使用 provider 筛选。此信息仅供参考，并非保证：合成时可能回退到其他引擎。
tagsstring | null可为空用于辅助选择声音的自由文本描述。已由下方结构化字段替代，但为兼容保留，可能为空。
use_casesstring[]建议使用场景，例如 narration / conversational；可能为空。
voice_idstring必填声音标识符。在文本脚本中作为 voice_id 传入，或在转换上传音频时作为目标声音。
messagestring便于阅读的状态消息；调用成功时为 "success"。
server_timestring · date-time必填服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。
default错误响应。所有失败均使用统一结构：error 对象包含数字错误码 code、便于阅读的 message、可选的 details 字符串，以及提供后续处理建议的可选 hint（便于 AI Agent 使用）。
application/json
errorErrorDetail必填codeinteger必填机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。
detailsstring | null可为空可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。
hintstring | null可为空供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。
messagestring必填便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。