Search VisionStory documentation

No documentation matched “”.

Try a feature or resource name such as , , or .

VisionStoryDevelopers
Get API key

Guide

AI Avatar API

List public AI avatars, create a reusable custom talking avatar from one portrait photo, and use its avatar_id in VisionStory video generation requests.

The VisionStory AI Avatar API provides the on-screen character for a talking-avatar video. List ready-to-use public avatars or create a reusable custom avatar from one portrait, then pass its avatar_id to each video generation request.

AI avatar API endpoints

MethodPathWhat it does
GET/api/v1/avatarsList public avatars and your custom avatars
POST/api/v1/avatarCreate a custom avatar from an image
DELETE/api/v1/avatarDelete one of your custom avatars

List public and custom avatars

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

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

headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}
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 an AI avatar from a photo

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:

Shell
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:

Python
import base64
import os
import requests

headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}

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 talking video

Pass the avatar_id when creating a video:

JSON
{
  "model_id": "vs_character_v4",
  "avatar_id": "YOUR_AVATAR_ID",
  "text_script": { "text": "Hello!", "voice_id": "YOUR_VOICE_ID" }
}

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

Delete a custom avatar

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

Shell
curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/avatar?avatar_id=YOUR_AVATAR_ID"
  • Voices — pick or clone the voice your avatar speaks with.
  • Quick start — generate your first video.
  • API reference — full request and response schemas.