List avatars — VisionStory API

List either your own avatars or the public avatar library (is_public=true), newest first. Pass the previous page's next_cursor to paginate; next_cursor=0 means no more pages.

Headers

X-API-Keystringrequired

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

Query parameters

is_publicboolean

false lists your own avatars (with their framing); true lists the public avatar library instead.

Default: false

cursorinteger

Pagination cursor from the previous page's next_cursor. Omit or pass 0 for the first page.

Default: 0

limitinteger

Maximum avatars to return per page. Range 1–100; defaults to 20.

Default: 20

Responses

200Successful Response

application/json

dataGetAvatarsResponse | nullrequirednullable

The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.

avatarsAvatarDto[]required

Avatars on this page, newest first: your own avatars, or the public library when the request sets is_public=true.

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.

next_cursorinteger

Cursor for the next page; pass it back as cursor. 0 means no more pages.

Default: 0

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.