[{"data":1,"prerenderedAt":178},["ShallowReactive",2],{"reference-detail-zh-get_avatars_api_v1_avatars_get":3,"developer-code-13m4xe0":176,"developer-code-5chppk":177},{"tag":4,"sourceTag":4,"tagSlug":5,"method":6,"path":7,"slug":8,"summary":9,"description":10,"operationId":11,"groupOrder":12,"descriptionHtml":13,"parameters":14,"responses":22,"security":163,"codeSamples":166},"Avatars","avatars","GET","\u002Fapi\u002Fv1\u002Favatars","get-avatars","列出数字人","列出账户可用的数字人，包括平台公共数字人和自己创建的自定义数字人（最多 100 个）。响应不分页。","get_avatars_api_v1_avatars_get",20,"\u003Cp>列出账户可用的数字人，包括平台公共数字人和自己创建的自定义数字人（最多 100 个）。响应不分页。\u003C\u002Fp>",[15],{"name":16,"in":17,"required":18,"description":19,"type":20,"example":21},"X-API-Key","header",true,"你的 VisionStory API Key（`sk-vs-...`），请仅保存在服务端。可在 [API Key 管理](\u002Fapi-keys) 中创建或管理，需要 Pro 或更高方案。","string","sk-vs-your-api-key",[23,133],{"status":24,"description":25,"contentType":26,"schema":27,"example":107,"examples":121,"headers":132},"200","请求成功","application\u002Fjson",{"type":28,"description":29,"nullable":30,"properties":31},"BaseSuccessResponse_GetAvatarsResponse_","",false,[32,97,102],{"name":33,"required":18,"type":34,"description":35,"nullable":18,"properties":36},"data","GetAvatarsResponse | null","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[37,74,93],{"name":38,"required":18,"type":39,"description":40,"nullable":30,"properties":41,"items":42},"my_avatars","AvatarDto[]","当前账户创建的自定义数字人，最多返回 100 个。",[],{"type":43,"description":29,"nullable":30,"properties":44},"AvatarDto",[45,56,60,66,70],{"name":46,"required":30,"type":47,"description":48,"nullable":30,"properties":49,"items":50},"aspect_ratios","string[]","此数字人已适配的宽高比（`1:1` \u002F `9:16` \u002F `16:9`）。生成视频时请选择匹配的 `aspect_ratio`。",[],{"type":20,"description":29,"nullable":30,"enum":51,"properties":55},[52,53,54],"9:16","16:9","1:1",[],{"name":57,"required":18,"type":20,"description":58,"nullable":30,"properties":59},"avatar_id","数字人的唯一标识符。生成数字人视频时，将其作为 `avatar_id` 传入。",[],{"name":61,"required":30,"type":62,"description":63,"nullable":30,"default":64,"properties":65},"created_at","integer","数字人创建时的 Unix 时间戳，单位为秒；公共或平台数字人为 0。",0,[],{"name":67,"required":30,"type":20,"description":68,"nullable":30,"default":29,"properties":69},"default_voice_id","数字人预设的声音。文本脚本中必须提供 `voice_id`；如需使用数字人自身的声音，请复制此值，不要猜测。未预设声音的数字人可能返回空值。",[],{"name":71,"required":18,"type":20,"description":72,"nullable":30,"properties":73},"thumbnail_url","数字人预览缩略图的 URL。",[],{"name":75,"required":18,"type":39,"description":76,"nullable":30,"properties":77,"items":78},"public_avatars","平台提供的、所有账户均可使用的数字人。",[],{"type":43,"description":29,"nullable":30,"properties":79},[80,85,87,89,91],{"name":46,"required":30,"type":47,"description":48,"nullable":30,"properties":81,"items":82},[],{"type":20,"description":29,"nullable":30,"enum":83,"properties":84},[52,53,54],[],{"name":57,"required":18,"type":20,"description":58,"nullable":30,"properties":86},[],{"name":61,"required":30,"type":62,"description":63,"nullable":30,"default":64,"properties":88},[],{"name":67,"required":30,"type":20,"description":68,"nullable":30,"default":29,"properties":90},[],{"name":71,"required":18,"type":20,"description":72,"nullable":30,"properties":92},[],{"name":94,"required":18,"type":62,"description":95,"nullable":30,"properties":96},"total_cnt","两个列表返回的数字人总数。",[],{"name":98,"required":30,"type":20,"description":99,"nullable":30,"default":100,"properties":101},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":103,"required":18,"type":104,"description":105,"nullable":30,"properties":106},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。",[],{"data":108,"message":100,"server_time":120},{"my_avatars":109,"public_avatars":116,"total_cnt":119},[110],{"aspect_ratios":111,"avatar_id":112,"created_at":113,"default_voice_id":114,"thumbnail_url":115},[52,53,54],"example_avatar_id",1788480000,"example_voice_id","https:\u002F\u002Fexample.com\u002Favatar.jpg",[117],{"aspect_ratios":118,"avatar_id":112,"created_at":64,"default_voice_id":114,"thumbnail_url":115},[52,53,54],2,"2026-09-04T00:00:00Z",[122],{"name":100,"description":123,"summary":25,"value":124},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":125,"message":100,"server_time":120},{"my_avatars":126,"public_avatars":129,"total_cnt":119},[127],{"aspect_ratios":128,"avatar_id":112,"created_at":113,"default_voice_id":114,"thumbnail_url":115},[52,53,54],[130],{"aspect_ratios":131,"avatar_id":112,"created_at":64,"default_voice_id":114,"thumbnail_url":115},[52,53,54],[],{"status":134,"description":135,"contentType":26,"schema":136,"example":159,"headers":162},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":137,"description":29,"nullable":30,"properties":138},"ErrorResponse",[139],{"name":140,"required":18,"type":141,"description":29,"nullable":30,"properties":142},"error","ErrorDetail",[143,147,152,156],{"name":144,"required":18,"type":62,"description":145,"nullable":30,"properties":146},"code","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":148,"required":30,"type":149,"description":150,"nullable":18,"properties":151},"details","string | null","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":153,"required":30,"type":149,"description":154,"nullable":18,"properties":155},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":98,"required":18,"type":20,"description":157,"nullable":30,"properties":158},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":160},{"code":161,"message":20,"details":20,"hint":20},1,[],[164],{"APIKeyHeader":165},[],[167,170,173],{"lang":168,"source":169},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\navatars = client.list_avatars()\nprint(avatars)",{"lang":171,"source":172},"REST","import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nresponse = requests.get(\n    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars', headers=headers, timeout=10\n)\nresp_data = response.json()\nprint(len(resp_data['data']['public_avatars']))\nprint(len(resp_data['data']['my_avatars']))",{"lang":174,"source":175},"cURL","curl -X 'GET' \\\n      'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars' \\\n      -H 'accept: application\u002Fjson' \\\n      -H 'X-API-Key: $VISIONSTORY_API_KEY'","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient.from_env()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">avatars \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.list_avatars()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(avatars)\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"my_avatars\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: [\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"aspect_ratios\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: [\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">          \"9:16\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">          \"16:9\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">          \"1:1\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">        ],\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"example_avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"created_at\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1788480000\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"default_voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"example_voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"thumbnail_url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Favatar.jpg\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      }\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    ],\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"public_avatars\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: [\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"aspect_ratios\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: [\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">          \"9:16\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">          \"16:9\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">          \"1:1\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">        ],\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"example_avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"created_at\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">0\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"default_voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"example_voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"thumbnail_url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Favatar.jpg\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">      }\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    ],\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"total_cnt\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">2\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">  },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"message\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"success\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"server_time\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"2026-09-04T00:00:00Z\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788547143932]