[{"data":1,"prerenderedAt":158},["ShallowReactive",2],{"reference-detail-zh-create_avatar_api_v1_avatar_post":3,"developer-code-1afxccj":156,"developer-code-1ihupkz":157},{"tag":4,"sourceTag":4,"tagSlug":5,"method":6,"path":7,"slug":8,"summary":9,"description":10,"operationId":11,"groupOrder":12,"descriptionHtml":13,"parameters":14,"requestBody":22,"responses":49,"security":143,"codeSamples":146},"Avatars","avatars","POST","\u002Fapi\u002Fv1\u002Favatar","create-avatar","创建数字人","使用单张肖像创建自定义数字人，支持 JPEG\u002FPNG\u002FWEBP\u002FHEIC，文件不超过 10MB。之后可通过 POST \u002Fapi\u002Fv1\u002Fvideo，使用返回的 `avatar_id` 让数字人朗读任意脚本。","create_avatar_api_v1_avatar_post",20,"\u003Cp>使用单张肖像创建自定义数字人，支持 JPEG\u002FPNG\u002FWEBP\u002FHEIC，文件不超过 10MB。之后可通过 POST \u002Fapi\u002Fv1\u002Fvideo，使用返回的 \u003Ccode>avatar_id\u003C\u002Fcode> 让数字人朗读任意脚本。\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",{"required":18,"contentType":23,"schema":24,"example":47},"application\u002Fjson",{"type":25,"description":26,"nullable":27,"properties":28},"CreateAvatarRequest","",false,[29,34],{"name":30,"required":27,"type":31,"description":32,"nullable":18,"properties":33},"img_url","string | null","源图像的公开可访问 URL。此字段与 `inline_data` 二选一。支持 JPEG\u002FPNG\u002FWEBP\u002FHEIC，文件不超过 10MB。",[],{"name":35,"required":27,"type":36,"description":37,"nullable":18,"properties":38},"inline_data","InlineDataModel | null","以内嵌 base64 数据提供的源图像。此字段与 `img_url` 二选一。",[39,43],{"name":40,"required":18,"type":20,"description":41,"nullable":27,"properties":42},"data","文件原始字节编码后的 base64 字符串，不包含 `data:` URI 前缀。",[],{"name":44,"required":18,"type":20,"description":45,"nullable":27,"properties":46},"mime_type","内嵌数据的 MIME 类型，网关据此区分图像、音频和视频。可接受的类型取决于具体接口，请参阅包含此对象的字段说明。数字人视频接受音频 ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav'] 和图像 ['image\u002Fjpeg', 'image\u002Fjpg', 'image\u002Fpng', 'image\u002Fwebp', 'image\u002Fheic']。",[],{"img_url":48},"https:\u002F\u002Fexample.com\u002Fmedia\u002Fportrait.jpg",[50,114],{"status":51,"description":52,"contentType":23,"schema":53,"example":99,"examples":107,"headers":113},"200","请求成功",{"type":54,"description":26,"nullable":27,"properties":55},"BaseSuccessResponse_CreateAvatarResponse_",[56,89,94],{"name":40,"required":18,"type":57,"description":58,"nullable":18,"properties":59},"CreateAvatarResponse | null","返回已创建的数字人数据。",[60,71,75,81,85],{"name":61,"required":27,"type":62,"description":63,"nullable":27,"properties":64,"items":65},"aspect_ratios","string[]","此数字人已适配的宽高比（`1:1` \u002F `9:16` \u002F `16:9`）。生成视频时请选择匹配的 `aspect_ratio`。",[],{"type":20,"description":26,"nullable":27,"enum":66,"properties":70},[67,68,69],"9:16","16:9","1:1",[],{"name":72,"required":18,"type":20,"description":73,"nullable":27,"properties":74},"avatar_id","数字人的唯一标识符。生成数字人视频时，将其作为 `avatar_id` 传入。",[],{"name":76,"required":27,"type":77,"description":78,"nullable":27,"default":79,"properties":80},"created_at","integer","数字人创建时的 Unix 时间戳，单位为秒；公共或平台数字人为 0。",0,[],{"name":82,"required":27,"type":20,"description":83,"nullable":27,"default":26,"properties":84},"default_voice_id","数字人预设的声音。文本脚本中必须提供 `voice_id`；如需使用数字人自身的声音，请复制此值，不要猜测。未预设声音的数字人可能返回空值。",[],{"name":86,"required":18,"type":20,"description":87,"nullable":27,"properties":88},"thumbnail_url","数字人预览缩略图的 URL。",[],{"name":90,"required":27,"type":20,"description":91,"nullable":27,"default":92,"properties":93},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":95,"required":18,"type":96,"description":97,"nullable":27,"properties":98},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。",[],{"data":100,"message":92,"server_time":106},{"aspect_ratios":101,"avatar_id":102,"created_at":103,"default_voice_id":104,"thumbnail_url":105},[67,68,69],"example_avatar_id",1788480000,"example_voice_id","https:\u002F\u002Fexample.com\u002Favatar.jpg","2026-09-04T00:00:00Z",[108],{"name":92,"description":109,"summary":52,"value":110},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":111,"message":92,"server_time":106},{"aspect_ratios":112,"avatar_id":102,"created_at":103,"default_voice_id":104,"thumbnail_url":105},[67,68,69],[],{"status":115,"description":116,"contentType":23,"schema":117,"example":139,"headers":142},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":118,"description":26,"nullable":27,"properties":119},"ErrorResponse",[120],{"name":121,"required":18,"type":122,"description":26,"nullable":27,"properties":123},"error","ErrorDetail",[124,128,132,136],{"name":125,"required":18,"type":77,"description":126,"nullable":27,"properties":127},"code","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":129,"required":27,"type":31,"description":130,"nullable":18,"properties":131},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":133,"required":27,"type":31,"description":134,"nullable":18,"properties":135},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":90,"required":18,"type":20,"description":137,"nullable":27,"properties":138},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":140},{"code":141,"message":20,"details":20,"hint":20},1,[],[144],{"APIKeyHeader":145},[],[147,150,153],{"lang":148,"source":149},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\navatar = client.create_avatar(image_url=\"https:\u002F\u002Fexample.com\u002Fmedia\u002Fportrait.jpg\")\nprint(avatar)",{"lang":151,"source":152},"REST","import os\nimport requests\nimport base64\n\ndef encode_base64(file_path):\n    with open(file_path, 'rb') as file:\n        encoded_string = base64.b64encode(file.read()).decode('utf-8')\n    return encoded_string\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\n# payload = {\n#     \"img_url\": \"https:\u002F\u002Fcdn.visionstory.ai\u002Fvman\u002Fcharacter\u002Fffcebbfdf9495c501fe70f8453353e3d_4721_head.jpg\"\n# }\n\nimage_file_path = '\u002Fpath\u002Fto\u002Fimage.jpg'\npayload = {\n    \"inline_data\": {\n        \"mime_type\": \"image\u002Fjpg\",\n        \"data\": encode_base64(image_file_path)\n    }\n}\n\nresponse = requests.post(\n    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar',  json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['avatar_id'])",{"lang":154,"source":155},"cURL","curl -X 'POST' \\\n      'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar' \\\n      -H 'accept: application\u002Fjson' \\\n      -H 'content-type: application\u002Fjson' \\\n      -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n      --data '\n{\n    \"img_url\": \"https:\u002F\u002Fcdn.visionstory.ai\u002Fvman\u002Fcharacter\u002F89d9924fc9b73df255e8233613f52de2_3871_norm.jpeg\"\n}\n'","\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\">avatar \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.create_avatar(\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">image_url\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Fmedia\u002Fportrait.jpg\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(avatar)\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\">    \"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:#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>",1788547143931]