[{"data":1,"prerenderedAt":159},["ShallowReactive",2],{"reference-detail-zh-update_avatar_framing_api_v1_avatar_framing_post":3,"developer-code-uw5ijn":157,"developer-code-r9cena":158},{"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":144,"codeSamples":147},"Avatars","avatars","POST","\u002Fapi\u002Fv1\u002Favatar\u002Fframing","update-avatar-framing","更新数字人取景","使用 `zoom` 和 `offset_x` \u002F `offset_y`，调整自己的一名数字人在一个画幅下的取景。请先通过 GET \u002Fapi\u002Fv1\u002Favatars 读取当前值，修改后完整传回这三个值。新取景会检查是否包含清晰人脸，保存后用于该画幅之后生成的视频，并与网页编辑器共享。\n\n公共数字人不能通过 API 调整取景。接口需要裁剪并检查参考图片，因此请求可能耗时数秒。","update_avatar_framing_api_v1_avatar_framing_post",20,"\u003Cp>使用 \u003Ccode>zoom\u003C\u002Fcode> 和 \u003Ccode>offset_x\u003C\u002Fcode> \u002F \u003Ccode>offset_y\u003C\u002Fcode>，调整自己的一名数字人在一个画幅下的取景。请先通过 GET \u002Fapi\u002Fv1\u002Favatars 读取当前值，修改后完整传回这三个值。新取景会检查是否包含清晰人脸，保存后用于该画幅之后生成的视频，并与网页编辑器共享。\u003C\u002Fp>\u003Cp>公共数字人不能通过 API 调整取景。接口需要裁剪并检查参考图片，因此请求可能耗时数秒。\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":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","需要调整取景的画幅。",[33,34,35],"9:16","16:9","1:1",[],{"name":38,"required":18,"type":20,"description":39,"nullable":27,"properties":40},"avatar_id","自己拥有的一个数字人 ID，可通过 GET \u002Fapi\u002Fv1\u002Favatars 查询。公共数字人不能通过 API 调整取景。",[],{"name":42,"required":18,"type":43,"description":44,"nullable":27,"properties":45},"offset_x","number","取景区域在可水平移动范围内的位置，取值为 -1 到 1：`-1` 紧贴左边缘，`0` 居中，`1` 紧贴右边缘。取景区域已覆盖完整宽度时，此值不生效。",[],{"name":47,"required":18,"type":43,"description":48,"nullable":27,"properties":49},"offset_y","取景区域在可垂直移动范围内的位置，取值为 -1 到 1：`-1` 紧贴上边缘，`0` 居中，`1` 紧贴下边缘。取景区域已覆盖完整高度时，此值不生效。",[],{"name":51,"required":18,"type":43,"description":52,"nullable":27,"properties":53},"zoom","缩放级别，最小为 1。`1` 表示源图中能够容纳此画幅的最大区域，即最宽取景（例如全身）；`2` 会将取景宽度和高度各缩小一半，使人物看起来放大一倍。",[],{"aspect_ratio":33,"avatar_id":55,"offset_x":56,"offset_y":56,"zoom":57},"avatar_123456",-1,1,[59,115],{"status":60,"description":61,"contentType":23,"schema":62,"example":102,"examples":109,"headers":114},"200","请求成功",{"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","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[70,74,77,82,86,89],{"name":30,"required":18,"type":20,"description":71,"nullable":27,"enum":72,"properties":73},"此取景适用的画幅。",[33,34,35],[],{"name":38,"required":18,"type":20,"description":75,"nullable":27,"properties":76},"取景已更新的数字人 ID。",[],{"name":78,"required":27,"type":79,"description":80,"nullable":18,"properties":81},"image_url","string | null","当前在此画幅生成视频时使用的参考图片 URL。",[],{"name":42,"required":27,"type":83,"description":84,"nullable":18,"properties":85},"number | null","取景区域在可水平移动范围内的位置，取值为 -1 到 1：`-1` 紧贴左边缘，`0` 居中，`1` 紧贴右边缘。取景区域已覆盖完整宽度时，此值不生效；`zoom` 为 null 时，此值也为 null。",[],{"name":47,"required":27,"type":83,"description":87,"nullable":18,"properties":88},"取景区域在可垂直移动范围内的位置，取值为 -1 到 1：`-1` 紧贴上边缘，`0` 居中，`1` 紧贴下边缘。取景区域已覆盖完整高度时，此值不生效；`zoom` 为 null 时，此值也为 null。",[],{"name":51,"required":27,"type":83,"description":90,"nullable":18,"properties":91},"缩放级别，最小为 1。`1` 表示源图中能够容纳此画幅的最大区域，即最宽取景（例如全身）；`2` 会将取景宽度和高度各缩小一半，使人物看起来放大一倍。启用取景功能前创建的数字人返回 null。",[],{"name":93,"required":27,"type":20,"description":94,"nullable":27,"default":95,"properties":96},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":98,"required":18,"type":99,"description":100,"nullable":27,"properties":101},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（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":61,"value":112},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":113,"message":95,"server_time":108},{"aspect_ratio":33,"avatar_id":104,"image_url":105,"offset_x":106,"offset_y":56,"zoom":107},[],{"status":116,"description":117,"contentType":23,"schema":118,"example":141,"headers":143},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":119,"description":26,"nullable":27,"properties":120},"ErrorResponse",[121],{"name":122,"required":18,"type":123,"description":26,"nullable":27,"properties":124},"error","ErrorDetail",[125,130,134,138],{"name":126,"required":18,"type":127,"description":128,"nullable":27,"properties":129},"code","integer","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":131,"required":27,"type":79,"description":132,"nullable":18,"properties":133},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":135,"required":27,"type":79,"description":136,"nullable":18,"properties":137},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":93,"required":18,"type":20,"description":139,"nullable":27,"properties":140},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":142},{"code":57,"message":20,"details":20,"hint":20},[],[145],{"APIKeyHeader":146},[],[148,151,154],{"lang":149,"source":150},"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":152,"source":153},"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":155,"source":156},"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]