Create avatar — VisionStory API

Create a custom avatar from a single portrait image (JPEG/PNG/WEBP/HEIC, up to 10MB). The returned avatar_id can then speak any script via POST /api/v1/video.

The avatar starts with automatic framing; the response includes it as framing. Change it with POST /api/v1/avatar/framing.

Headers

X-API-Keystringrequired

Your VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).

Request body

application/jsonrequired

img_urlstring | nullnullable

Publicly reachable URL of the source image. Provide either this or inline_data. Formats: JPEG/PNG/WEBP/HEIC, up to 10MB.

inline_dataInlineDataModel | nullnullable

Source image as inline base64 data. Provide either this or img_url.

datastringrequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

mime_typestringrequired

MIME type of the inline data; the gateway uses it to tell image / audio / video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] and images ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

Responses

200Successful Response

application/json

dataCreateAvatarResponse | nullrequirednullable

Response with created avatar data

aspect_ratiosstring[]

Aspect ratios this avatar was prepared for (1:1 / 9:16 / 16:9). Choose a matching aspect_ratio when generating a video.

avatar_idstringrequired

Unique avatar identifier. Pass it as avatar_id when generating a talking video.

created_atinteger

Unix timestamp (seconds) when the avatar was created.

Default: 0

default_voice_idstring

The voice this avatar was set up with. voice_id is required in a text script, so copy this value when you want the avatar's own voice (rather than guessing one). May be empty for avatars without a preset voice.

Default:

framingAvatarFraming[] | nullnullable

Current framing per aspect ratio, always 3 entries in the order 9:16, 16:9, 1:1. New avatars start with automatic framing; change it with POST /api/v1/avatar/framing. It is shared with the web editor. Always null for public avatars, which cannot be reframed through the API.

aspect_ratiostringrequired

Aspect ratio this framing applies to.

Values: 9:1616:91:1

image_urlstring | nullnullable

URL of the reference image videos in this aspect ratio currently use.

offset_xnumber | nullnullable

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.

offset_ynumber | nullnullable

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.

zoomnumber | nullnullable

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.

thumbnail_urlstringrequired

URL of the avatar's preview thumbnail image.

messagestring

Human-readable status message; "success" on a successful call.

Default: success

server_timestring · date-timerequired

Server-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

errorErrorDetailrequired

codeintegerrequired

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.

detailsstring | nullnullable

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.

hintstring | nullnullable

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.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.