Change how one of your own avatars is framed for one aspect ratio, using zoom and offset_x / offset_y. Read the current values from GET /api/v1/avatars, 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).
Public avatars cannot be reframed through the API. The request takes a few seconds because the reference image is cropped and checked.
Headers
X-API-KeystringrequiredYour VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).
Request body
application/jsonrequiredaspect_ratiostringrequiredAspect ratio whose framing to change.
avatar_idstringrequiredId of one of your own avatars (listed by GET /api/v1/avatars). Public avatars cannot be reframed through the API.
offset_xnumberrequiredHorizontal 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.
offset_ynumberrequiredVertical 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.
zoomnumberrequiredZoom 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.
Responses
200Successful Response
application/json
dataUpdateAvatarFramingResponse | nullrequirednullableThe endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.
aspect_ratiostringrequiredAspect ratio this framing applies to.
avatar_idstringrequiredId of the avatar whose framing was changed.
image_urlstring | nullnullableURL of the reference image videos in this aspect ratio currently use.
offset_xnumber | nullnullableHorizontal 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.
offset_ynumber | nullnullableVertical 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.
zoomnumber | nullnullableZoom 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.
messagestringHuman-readable status message; "success" on a successful call.
server_timestring · date-timerequiredServer-side timestamp when the response was produced, in ISO 8601 format (UTC).
defaultError 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).
application/json
errorErrorDetailrequiredcodeintegerrequiredMachine-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.
detailsstring | nullnullableOptional 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.
hintstring | nullnullableActionable 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.
messagestringrequiredHuman-readable explanation of what went wrong. Safe to log or surface to end users; not localized.