列出账户可用的数字人,包括平台公共数字人和自己创建的自定义数字人(最多 100 个)。响应不分页。
请求头
X-API-Keystring必填你的 VisionStory API Key(sk-vs-...),请仅保存在服务端。可在 API Key 管理 中创建或管理,需要 Pro 或更高方案。
响应
200请求成功
application/json
dataGetAvatarsResponse | null必填可为空当前接口的响应数据,字段定义见该接口的响应结构。仅当操作不返回数据时为 null。
my_avatarsAvatarDto[]必填当前账户创建的自定义数字人,最多返回 100 个。
aspect_ratiosstring[]此数字人已适配的宽高比(1:1 / 9:16 / 16:9)。生成视频时请选择匹配的 aspect_ratio。
avatar_idstring必填数字人的唯一标识符。生成数字人视频时,将其作为 avatar_id 传入。
created_atinteger数字人创建时的 Unix 时间戳,单位为秒;公共或平台数字人为 0。
default_voice_idstring数字人预设的声音。文本脚本中必须提供 voice_id;如需使用数字人自身的声音,请复制此值,不要猜测。未预设声音的数字人可能返回空值。
thumbnail_urlstring必填数字人预览缩略图的 URL。
public_avatarsAvatarDto[]必填平台提供的、所有账户均可使用的数字人。
aspect_ratiosstring[]此数字人已适配的宽高比(1:1 / 9:16 / 16:9)。生成视频时请选择匹配的 aspect_ratio。
avatar_idstring必填数字人的唯一标识符。生成数字人视频时,将其作为 avatar_id 传入。
created_atinteger数字人创建时的 Unix 时间戳,单位为秒;公共或平台数字人为 0。
default_voice_idstring数字人预设的声音。文本脚本中必须提供 voice_id;如需使用数字人自身的声音,请复制此值,不要猜测。未预设声音的数字人可能返回空值。
thumbnail_urlstring必填数字人预览缩略图的 URL。
total_cntinteger必填两个列表返回的数字人总数。
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必填便于阅读的错误原因说明,可安全记录到日志或展示给最终用户;此返回值未本地化。