VisionStory Docs
llms.txt Get API key

Avatars

View as MarkdownOpen in ClaudeOpen in ChatGPT

An avatar is the on-screen character that speaks your script in a generated video. Use a curated avatar from the public library, or create a custom avatar from a single photo and reuse it across any number of videos.

Endpoints

Method Path What it does
GET /api/v1/avatars List public avatars and your custom avatars
POST /api/v1/avatar Create a custom avatar from an image
DELETE /api/v1/avatar Delete one of your custom avatars

List avatars

The list response has two groups: public_avatars (ready to use, no setup) and my_avatars (created by you):

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/avatars
import requests

headers = {"X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx"}
response = requests.get("https://openapi.visionstory.ai/api/v1/avatars", headers=headers, timeout=10)
resp_data = response.json()
print(len(resp_data["data"]["public_avatars"]))
print(len(resp_data["data"]["my_avatars"]))

Always pick an avatar_id from this endpoint instead of hardcoding one — the public library evolves over time.

Create a custom avatar

Send one portrait image, get back an avatar_id. Provide the image as either a public HTTPS URL or base64 inline_data — exactly one of the two:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"img_url": "https://your.site/portrait.jpg"}' https://openapi.visionstory.ai/api/v1/avatar

With a local file, base64-encode it into inline_data:

import requests
import base64

headers = {"X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx"}

with open("/path/to/image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {"inline_data": {"mime_type": "image/jpg", "data": encoded}}
response = requests.post("https://openapi.visionstory.ai/api/v1/avatar", json=payload, headers=headers)
print(response.json()["data"]["avatar_id"])

Store the returned avatar_id — you will pass it to every video request that should feature this avatar.

Photo requirements: use a single, clear, front-facing portrait for best results. Supported formats are JPEG, PNG, WEBP, and HEIC, up to 10 MB.

Use an avatar in a video

Pass the avatar_id when creating a video:

{
  "model_id": "vs_character_v4",
  "avatar_id": "4321918387609092991",
  "text_script": { "text": "Hello!", "voice_id": "Alice" }
}

See the Quick start for the full generate-poll-download flow.

Delete an avatar

Deleting only affects your own custom avatars; videos already generated with it are unaffected:

curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/avatar?avatar_id=YOUR_AVATAR_ID"

Next steps