使用 zoom 和 offset_x / offset_y，调整自己的一名数字人在一个画幅下的取景。请先通过 GET /api/v1/avatars 读取当前值，修改后完整传回这三个值。新取景会检查是否包含清晰人脸，保存后用于该画幅之后生成的视频，并与网页编辑器共享。
公共数字人不能通过 API 调整取景。接口需要裁剪并检查参考图片，因此请求可能耗时数秒。
请求头
X-API-Keystring必填你的 VisionStory API Key（sk-vs-...），请仅保存在服务端。可在 API Key 管理 中创建或管理，需要 Pro 或更高方案。
请求体
application/json必填aspect_ratiostring必填需要调整取景的画幅。
avatar_idstring必填自己拥有的一个数字人 ID，可通过 GET /api/v1/avatars 查询。公共数字人不能通过 API 调整取景。
offset_xnumber必填取景区域在可水平移动范围内的位置，取值为 -1 到 1：-1 紧贴左边缘，0 居中，1 紧贴右边缘。取景区域已覆盖完整宽度时，此值不生效。
offset_ynumber必填取景区域在可垂直移动范围内的位置，取值为 -1 到 1：-1 紧贴上边缘，0 居中，1 紧贴下边缘。取景区域已覆盖完整高度时，此值不生效。
zoomnumber必填缩放级别，最小为 1。1 表示源图中能够容纳此画幅的最大区域，即最宽取景（例如全身）；2 会将取景宽度和高度各缩小一半，使人物看起来放大一倍。
响应
200请求成功
application/json
dataUpdateAvatarFramingResponse | null必填可为空当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。
aspect_ratiostring必填此取景适用的画幅。
avatar_idstring必填取景已更新的数字人 ID。
image_urlstring | null可为空当前在此画幅生成视频时使用的参考图片 URL。
offset_xnumber | null可为空取景区域在可水平移动范围内的位置，取值为 -1 到 1：-1 紧贴左边缘，0 居中，1 紧贴右边缘。取景区域已覆盖完整宽度时，此值不生效；zoom 为 null 时，此值也为 null。
offset_ynumber | null可为空取景区域在可垂直移动范围内的位置，取值为 -1 到 1：-1 紧贴上边缘，0 居中，1 紧贴下边缘。取景区域已覆盖完整高度时，此值不生效；zoom 为 null 时，此值也为 null。
zoomnumber | null可为空缩放级别，最小为 1。1 表示源图中能够容纳此画幅的最大区域，即最宽取景（例如全身）；2 会将取景宽度和高度各缩小一半，使人物看起来放大一倍。启用取景功能前创建的数字人返回 null。
messagestring便于阅读的状态消息；调用成功时为 "success"。
server_timestring · date-time必填服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。
default错误响应。所有失败均使用统一结构：error 对象包含数字错误码 code、便于阅读的 message、可选的 details 字符串，以及提供后续处理建议的可选 hint（便于 AI Agent 使用）。
application/json
errorErrorDetail必填codeinteger必填机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。
detailsstring | null可为空可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。
hintstring | null可为空供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。
messagestring必填便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。