VisionStory Docs
llms.txt Get API key
Avatars/List avatars
GET/api/v1/avatars

List avatars available to your account: the public platform library plus your own custom avatars (up to 100). The response is not paginated.

Headers

X-API-KeystringRequired
Your VisionStory API key (sk-vs-...), kept server-side. Create one at OpenApi (Pro plan and up).

Response

200Successful Response

Successful calls return a standard envelope: the endpoint payload under data (its fields are documented below), plus a message string ("success") and an ISO 8601 server_time.

Response fields (data)
public_avatarsarray of AvatarDtoRequired
Platform-provided avatars available to every account.
Show 4 propertiesHide 4 properties
avatar_idstringRequired
Unique avatar identifier. Pass it as avatar_id when generating a talking video.
thumbnail_urlstringRequired
URL of the avatar's preview thumbnail image.
aspect_ratiosarray of stringOptional
Aspect ratios this avatar was prepared for (1:1 / 9:16 / 16:9). Choose a matching aspect_ratio when generating a video.
created_atintegerOptionalDefault 0
Unix timestamp (seconds) when the avatar was created; 0 for public/platform avatars.
my_avatarsarray of AvatarDtoRequired
Custom avatars created by this account (up to 100 returned).
Show 4 propertiesHide 4 properties
avatar_idstringRequired
Unique avatar identifier. Pass it as avatar_id when generating a talking video.
thumbnail_urlstringRequired
URL of the avatar's preview thumbnail image.
aspect_ratiosarray of stringOptional
Aspect ratios this avatar was prepared for (1:1 / 9:16 / 16:9). Choose a matching aspect_ratio when generating a video.
created_atintegerOptionalDefault 0
Unix timestamp (seconds) when the avatar was created; 0 for public/platform avatars.
total_cntintegerRequired
Total number of avatars returned across both lists.

Errors

All error responses share one JSON 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 (handy for AI agents).

errorErrorDetailRequired
Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead.
Show 4 propertiesHide 4 properties
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.
messagestringRequired
Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.
detailsstring | nullOptional
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 | nullOptional
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.