Talking Avatar Video API Quickstart

This quickstart creates a complete AI talking-avatar video in five steps. You will authenticate the VisionStory API, submit a text script, poll the asynchronous job, and save the generated MP4 locally.

1. Create a VisionStory API key

Sign up and create an API key at visionstory.ai/openapi. Send it with every request in the X-API-Key header:

X-API-Key: $VISIONSTORY_API_KEY

Keep the key on your server and never expose it in browser code or a public repository. The examples below read it from an environment variable:

export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"

Before starting a paid generation, verify the key with a read-only request:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \
  https://openapi.visionstory.ai/api/v1/billing/credits

A successful response includes your plan and remaining credits. A 401 response means the key is missing, expired, or no longer valid; create or replace it at visionstory.ai/openapi before continuing.

2. Choose an API client

Start with the option that matches your task. You can switch later because every interface uses the same VisionStory API and VISIONSTORY_API_KEY.

Python SDK

Install the typed, zero-dependency Python client:

pip install visionstory

from visionstory import VisionStoryClient

client = VisionStoryClient.from_env()  # reads VISIONSTORY_API_KEY

VisionStory CLI

Install or upgrade to the latest CLI release in an isolated environment:

curl -fsSL https://developers.visionstory.ai/cli | bash

After restarting the terminal if prompted, verify authentication and discover valid resource IDs:

visionstory credits
visionstory avatars
visionstory voices

See the CLI guide for every command.

Agent Skill

The focused talking-avatar Agent Skill ships a SKILL.md plus a dependency-free Python helper that handles authentication, base64 encoding, polling, and downloads. It auto-detects supported coding agents:

npx skills add visionstory-ai/skills --skill visionstory-api

Then create a video in one command:

python3 .agents/skills/visionstory-api/scripts/visionstory_api.py create-video \
  --avatar-id YOUR_AVATAR_ID \
  --text "Hello from VisionStory." \
  --voice-id YOUR_VOICE_ID \
  --output result.mp4

REST API

Call the API directly with curl or any HTTP client. The complete Python example at the end of this guide only needs requests.

3. Generate a talking avatar video

Submit a text script with a public avatar and voice. The request returns a video_id immediately while generation continues asynchronously:

curl -s \
  -H "X-API-Key: $VISIONSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "vs_character_v4",
    "avatar_id": "YOUR_AVATAR_ID",
    "client_request_id": "YOUR_UNIQUE_REQUEST_ID",
    "text_script": {
      "text": "Hello World, this is my first test video.",
      "voice_id": "YOUR_VOICE_ID",
      "speech_rate": "normal"
    },
    "aspect_ratio": "9:16",
    "resolution": "720p"
  }' \
  https://openapi.visionstory.ai/api/v1/video

{
  "data": {
    "video_id": "YOUR_VIDEO_ID"
  }
}

Before building a production integration, discover current IDs instead of hardcoding them: GET /api/v1/models, GET /api/v1/avatars, and GET /api/v1/voices. To use your own audio, send an audio_script in place of text_script — never both.

4. Poll the video generation job

Query the task every 5 seconds until it reaches a final state:

curl -s \
  -H "X-API-Key: $VISIONSTORY_API_KEY" \
  "https://openapi.visionstory.ai/api/v1/video?video_id=YOUR_VIDEO_ID"

Avoid polling faster than every 5 seconds, and give up after about 10 minutes.

5. Download the generated MP4

When the status is created, the response carries a video_url. Completed videos are retained for 7 days, so download the file if you need permanent storage:

curl -sL -o result.mp4 "<video_url from the response>"

Complete Python SDK example

With the SDK, the whole flow is a few lines:

from pathlib import Path
from visionstory import VisionStoryClient, build_video_payload

client = VisionStoryClient.from_env()
payload = build_video_payload(
    avatar_id="YOUR_AVATAR_ID",
    text="Hello World, this is my first test video.",
    voice_id="YOUR_VOICE_ID",
)
video = client.generate_video(payload)
client.download(video["video_url"], Path("result.mp4"))
print("saved result.mp4")

Related VisionStory API guides

• Read the overview for core resources, response envelopes, and model choices.
• Explore the API reference for request schemas, parameters, and responses.
• Get an API key when you are ready to run a real request.