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 on the VisionStory API keys page. 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"

VisionStory CLI users can instead run visionstory login after installation. It hides the input, verifies the key, and saves it for future CLI sessions without putting the secret in shell history.

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; the remaining value is your current VisionStory credit balance. A 401 response means the key is missing, expired, or no longer valid; create or replace it at API keys page 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 --is-public
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.