[{"data":1,"prerenderedAt":141},["ShallowReactive",2],{"reference-detail-create_avatar_api_v1_avatar_post":3,"developer-code-1yji1ji":139,"developer-code-1r1iwoq":140},{"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":129,"codeSamples":132},"Avatars","avatars","POST","\u002Fapi\u002Fv1\u002Favatar","create-avatar","Create avatar","Create a custom avatar from a single portrait image (JPEG\u002FPNG\u002FWEBP\u002FHEIC, up to 10MB). The returned\n`avatar_id` can then speak any script via POST \u002Fapi\u002Fv1\u002Fvideo.","create_avatar_api_v1_avatar_post",20,"\u003Cp>Create a custom avatar from a single portrait image (JPEG\u002FPNG\u002FWEBP\u002FHEIC, up to 10MB). The returned \u003Ccode>avatar_id\u003C\u002Fcode> can then speak any script via POST \u002Fapi\u002Fv1\u002Fvideo.\u003C\u002Fp>",[15],{"name":16,"in":17,"required":18,"description":19,"type":20,"example":21},"X-API-Key","header",true,"Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](\u002Fapi-keys) (Pro plan and up).","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","Publicly reachable URL of the source image. Provide either this or `inline_data`. Formats: JPEG\u002FPNG\u002FWEBP\u002FHEIC, up to 10MB.",[],{"name":35,"required":27,"type":36,"description":37,"nullable":18,"properties":38},"inline_data","InlineDataModel | null","Source image as inline base64 data. Provide either this or `img_url`.",[39,43],{"name":40,"required":18,"type":20,"description":41,"nullable":27,"properties":42},"data","The file's raw bytes encoded as a base64 string (no `data:` URI prefix).",[],{"name":44,"required":18,"type":20,"description":45,"nullable":27,"properties":46},"mime_type","MIME type of the inline data, used to detect image vs audio. Audio: ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav']; images: ['image\u002Fjpeg', 'image\u002Fjpg', 'image\u002Fpng', 'image\u002Fwebp', 'image\u002Fheic'].",[],{"img_url":48},"https:\u002F\u002Fexample.com\u002Fmedia\u002Fportrait.jpg",[50,101],{"status":51,"description":52,"contentType":23,"schema":53,"example":95},"200","Successful Response",{"type":54,"description":26,"nullable":27,"properties":55},"BaseSuccessResponse_CreateAvatarResponse_",[56,85,90],{"name":40,"required":18,"type":57,"description":58,"nullable":18,"properties":59},"CreateAvatarResponse | null","Response with created avatar data",[60,71,75,81],{"name":61,"required":27,"type":62,"description":63,"nullable":27,"properties":64,"items":65},"aspect_ratios","string[]","Aspect ratios this avatar was prepared for (`1:1` \u002F `9:16` \u002F `16:9`). Choose a matching `aspect_ratio` when generating a video.",[],{"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","Unique avatar identifier. Pass it as `avatar_id` when generating a talking video.",[],{"name":76,"required":27,"type":77,"description":78,"nullable":27,"default":79,"properties":80},"created_at","integer","Unix timestamp (seconds) when the avatar was created; 0 for public\u002Fplatform avatars.",0,[],{"name":82,"required":18,"type":20,"description":83,"nullable":27,"properties":84},"thumbnail_url","URL of the avatar's preview thumbnail image.",[],{"name":86,"required":27,"type":20,"description":87,"nullable":27,"default":88,"properties":89},"message","Human-readable status message; `\"success\"` on a successful call.","success",[],{"name":91,"required":18,"type":92,"description":93,"nullable":27,"properties":94},"server_time","string · date-time","Server-side timestamp when the response was produced, in ISO 8601 format (UTC).",[],{"data":96,"server_time":100,"message":88},{"avatar_id":97,"thumbnail_url":98,"aspect_ratios":99,"created_at":79},"avatar_123456","https:\u002F\u002Fexample.com\u002Fmedia\u002Finput.mp4",[67],"2026-08-24T08:00:00Z",{"status":102,"description":103,"contentType":23,"schema":104,"example":126},"default","Error response. All failures share one envelope: an `error` object with a numeric `code`, a human-readable `message`, an optional `details` string, and an optional `hint` giving an actionable next step (useful for AI agents).",{"type":105,"description":26,"nullable":27,"properties":106},"ErrorResponse",[107],{"name":108,"required":18,"type":109,"description":26,"nullable":27,"properties":110},"error","ErrorDetail",[111,115,119,123],{"name":112,"required":18,"type":77,"description":113,"nullable":27,"properties":114},"code","Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.",[],{"name":116,"required":27,"type":31,"description":117,"nullable":18,"properties":118},"details","Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.",[],{"name":120,"required":27,"type":31,"description":121,"nullable":18,"properties":122},"hint","Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.",[],{"name":86,"required":18,"type":20,"description":124,"nullable":27,"properties":125},"Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.",[],{"error":127},{"code":128,"message":20,"details":20,"hint":20},1,[130],{"APIKeyHeader":131},[],[133,136],{"lang":134,"source":135},"Python","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":137,"source":138},"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\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> os\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> base64\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">def\u003C\u002Fspan>\u003Cspan style=\"color:#D2A8FF\"> encode_base64\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(file_path):\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">    with\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> open\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(file_path, \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'rb'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">) \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">as\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\"> file\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">        encoded_string \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> base64.b64encode(\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">file\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">.read()).decode(\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'utf-8'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">    return\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> encoded_string\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">headers \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"X-API-Key\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: os.environ[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"VISIONSTORY_API_KEY\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\"># payload = {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\">#     \"img_url\": \"https:\u002F\u002Fcdn.visionstory.ai\u002Fvman\u002Fcharacter\u002Fffcebbfdf9495c501fe70f8453353e3d_4721_head.jpg\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\"># }\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">image_file_path \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> '\u002Fpath\u002Fto\u002Fimage.jpg'\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">payload \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"inline_data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"mime_type\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"image\u002Fjpg\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: encode_base64(image_file_path)\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\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">response \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests.post(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,  \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">json\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">payload, \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">headers\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">headers\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">resp_data \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> response.json()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(resp_data[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'data'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">][\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'avatar_id'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">])\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\">    \"avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"avatar_123456\"\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\u002Fmedia\u002Finput.mp4\"\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>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\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>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\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-08-24T08:00:00Z\"\u003C\u002Fspan>\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>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788166855863]