[{"data":1,"prerenderedAt":160},["ShallowReactive",2],{"reference-detail-en-update_avatar_framing_api_v1_avatar_framing_post":3,"developer-code-uw5ijn":158,"developer-code-r9cena":159},{"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":58,"security":145,"codeSamples":148},"Avatars","avatars","POST","\u002Fapi\u002Fv1\u002Favatar\u002Fframing","update-avatar-framing","Update avatar framing","Change how one of your own avatars is framed for one aspect ratio, using `zoom` and `offset_x` \u002F `offset_y`.\nRead the current values from GET \u002Fapi\u002Fv1\u002Favatars, adjust them, and send all three back. The new framing is\nchecked for a visible face, saved, and used by later videos in that aspect ratio (and by the web editor).\n\nPublic avatars cannot be reframed through the API. The request takes a few seconds because the reference\nimage is cropped and checked.","update_avatar_framing_api_v1_avatar_framing_post",20,"\u003Cp>Change how one of your own avatars is framed for one aspect ratio, using \u003Ccode>zoom\u003C\u002Fcode> and \u003Ccode>offset_x\u003C\u002Fcode> \u002F \u003Ccode>offset_y\u003C\u002Fcode>. Read the current values from GET \u002Fapi\u002Fv1\u002Favatars, adjust them, and send all three back. The new framing is checked for a visible face, saved, and used by later videos in that aspect ratio (and by the web editor).\u003C\u002Fp>\u003Cp>Public avatars cannot be reframed through the API. The request takes a few seconds because the reference image is cropped and checked.\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":54},"application\u002Fjson",{"type":25,"description":26,"nullable":27,"properties":28},"UpdateAvatarFramingRequest","",false,[29,37,41,46,50],{"name":30,"required":18,"type":20,"description":31,"nullable":27,"enum":32,"properties":36},"aspect_ratio","Aspect ratio whose framing to change.",[33,34,35],"9:16","16:9","1:1",[],{"name":38,"required":18,"type":20,"description":39,"nullable":27,"properties":40},"avatar_id","Id of one of your own avatars (listed by GET \u002Fapi\u002Fv1\u002Favatars). Public avatars cannot be reframed through the API.",[],{"name":42,"required":18,"type":43,"description":44,"nullable":27,"properties":45},"offset_x","number","Horizontal position of the framed area within the room it can move, from -1 to 1: `-1` touches the left edge, `0` is centered, `1` touches the right edge. It has no effect when the framed area already spans the full width.",[],{"name":47,"required":18,"type":43,"description":48,"nullable":27,"properties":49},"offset_y","Vertical position of the framed area within the room it can move, from -1 to 1: `-1` touches the top edge, `0` is centered, `1` touches the bottom edge. It has no effect when the framed area already spans the full height.",[],{"name":51,"required":18,"type":43,"description":52,"nullable":27,"properties":53},"zoom","Zoom level, at least 1. `1` is the largest area of this aspect ratio that fits in the avatar's source image (the widest framing, e.g. full body); `2` halves the framed width and height, making the person appear twice as large.",[],{"aspect_ratio":33,"avatar_id":55,"offset_x":56,"offset_y":56,"zoom":57},"avatar_123456",-1,1,[59,116],{"status":60,"description":61,"contentType":23,"schema":62,"example":102,"examples":109,"headers":115},"200","Successful Response",{"type":63,"description":26,"nullable":27,"properties":64},"BaseSuccessResponse_UpdateAvatarFramingResponse_",[65,92,97],{"name":66,"required":18,"type":67,"description":68,"nullable":18,"properties":69},"data","UpdateAvatarFramingResponse | null","The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.",[70,74,77,82,86,89],{"name":30,"required":18,"type":20,"description":71,"nullable":27,"enum":72,"properties":73},"Aspect ratio this framing applies to.",[33,34,35],[],{"name":38,"required":18,"type":20,"description":75,"nullable":27,"properties":76},"Id of the avatar whose framing was changed.",[],{"name":78,"required":27,"type":79,"description":80,"nullable":18,"properties":81},"image_url","string | null","URL of the reference image videos in this aspect ratio currently use.",[],{"name":42,"required":27,"type":83,"description":84,"nullable":18,"properties":85},"number | null","Horizontal position of the framed area within the room it can move, from -1 to 1: `-1` touches the left edge, `0` is centered, `1` touches the right edge. It has no effect when the framed area already spans the full width. null when `zoom` is null.",[],{"name":47,"required":27,"type":83,"description":87,"nullable":18,"properties":88},"Vertical position of the framed area within the room it can move, from -1 to 1: `-1` touches the top edge, `0` is centered, `1` touches the bottom edge. It has no effect when the framed area already spans the full height. null when `zoom` is null.",[],{"name":51,"required":27,"type":83,"description":90,"nullable":18,"properties":91},"Zoom level, at least 1. `1` is the largest area of this aspect ratio that fits in the avatar's source image (the widest framing, e.g. full body); `2` halves the framed width and height, making the person appear twice as large. null for avatars created before framing was supported.",[],{"name":93,"required":27,"type":20,"description":94,"nullable":27,"default":95,"properties":96},"message","Human-readable status message; `\"success\"` on a successful call.","success",[],{"name":98,"required":18,"type":99,"description":100,"nullable":27,"properties":101},"server_time","string · date-time","Server-side timestamp when the response was produced, in ISO 8601 format (UTC).",[],{"data":103,"message":95,"server_time":108},{"aspect_ratio":33,"avatar_id":104,"image_url":105,"offset_x":106,"offset_y":56,"zoom":107},"example_avatar_id","https:\u002F\u002Fexample.com\u002Favatar-9x16.png",0,1.2,"2026-09-04T00:00:00Z",[110],{"name":95,"description":111,"summary":112,"value":113},"Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.","Successful response",{"data":114,"message":95,"server_time":108},{"aspect_ratio":33,"avatar_id":104,"image_url":105,"offset_x":106,"offset_y":56,"zoom":107},[],{"status":117,"description":118,"contentType":23,"schema":119,"example":142,"headers":144},"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":120,"description":26,"nullable":27,"properties":121},"ErrorResponse",[122],{"name":123,"required":18,"type":124,"description":26,"nullable":27,"properties":125},"error","ErrorDetail",[126,131,135,139],{"name":127,"required":18,"type":128,"description":129,"nullable":27,"properties":130},"code","integer","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":132,"required":27,"type":79,"description":133,"nullable":18,"properties":134},"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":136,"required":27,"type":79,"description":137,"nullable":18,"properties":138},"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":93,"required":18,"type":20,"description":140,"nullable":27,"properties":141},"Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.",[],{"error":143},{"code":57,"message":20,"details":20,"hint":20},[],[146],{"APIKeyHeader":147},[],[149,152,155],{"lang":150,"source":151},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nframing = client.update_avatar_framing(\n    avatar_id=\"avatar_123456\",\n    aspect_ratio=\"9:16\",\n    zoom=1.2,\n    offset_x=0,\n    offset_y=-0.25,\n)\nprint(framing)",{"lang":153,"source":154},"REST","import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n# zoom=1 frames the widest area (e.g. full body); offset_y=-1 keeps it at the top of the image\npayload = {\n    \"avatar_id\": \"xxxx\",\n    \"aspect_ratio\": \"9:16\",\n    \"zoom\": 1,\n    \"offset_x\": 0,\n    \"offset_y\": -1\n}\nresponse = requests.post(\n    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\u002Fframing', json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['image_url'])",{"lang":156,"source":157},"cURL","curl -X 'POST' \\\n      'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\u002Fframing' \\\n      -H 'accept: application\u002Fjson' \\\n      -H 'content-type: application\u002Fjson' \\\n      -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n      --data '\n{\n    \"avatar_id\": \"xxxx\",\n    \"aspect_ratio\": \"9:16\",\n    \"zoom\": 1,\n    \"offset_x\": 0,\n    \"offset_y\": -1\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\">framing \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.update_avatar_framing(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    avatar_id\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\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:#FFA657\">    aspect_ratio\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"9:16\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    zoom\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1.2\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    offset_x\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">0\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    offset_y\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=-\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">0.25\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:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(framing)\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_ratio\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"9:16\"\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\">\"example_avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"image_url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Favatar-9x16.png\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"offset_x\"\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\">    \"offset_y\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">-1\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"zoom\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1.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>",1790232099881]