VisionStory Docs
llms.txt Get API key
Avatars/Create avatar
POST/api/v1/avatar

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.

Headers

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

Request body

img_urlstring | nullOptional
Publicly reachable URL of the source image. Provide either this or inline_data. Formats: JPEG/PNG/WEBP/HEIC, up to 10MB.
inline_dataInlineDataModel | nullOptional
Source image as inline base64 data. Provide either this or img_url.
Show 2 propertiesHide 2 properties
mime_typestringRequired
MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].
datastringRequired
The file's raw bytes encoded as a base64 string (no data: URI prefix).

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)
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.

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.