VisionStory Docs
llms.txt Get API key

Overview

View as MarkdownOpen in ClaudeOpen in ChatGPT

The VisionStory API turns a script — text or audio — into a lifelike talking-avatar video with a few lines of code. You pick (or create) an avatar, pick (or clone) a voice, submit the script, and download the finished video.

How VisionStory works

Every integration follows the same loop:

  1. Discover resources — list available models, avatars, and voices.
  2. Submit a generation task — POST /api/v1/video returns a video_id immediately.
  3. Poll until done — GET /api/v1/video?video_id=... until the status is created.
  4. Download the result — fetch video_url from the response.

All requests go to one base URL and authenticate with one header:

X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx

Base URL: https://openapi.visionstory.ai

Create your API key at visionstory.ai/openapi. Keep the key on your server — never expose it in browser code or a public repository.

Every response shares one envelope. Read successful payloads from the top-level data field:

{ "data": { "video_id": "7241059991822401536" }, "message": "success", "server_time": "..." }

Core concepts

Avatar

An avatar is the on-screen character that speaks your script. Use a ready-made avatar from the public library, or create your own from a single photo:

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

The response contains public_avatars (curated library) and my_avatars (yours). See the Avatars guide for creating custom avatars.

Voice

A voice is the voice_id that turns text into speech inside a video. Pick from the public voice library, or clone your own voice from an audio sample:

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

The response contains public_voices and my_voices. See the Voices guide for voice cloning.

Credit

A credit is the billing unit for generation. Credits come with your VisionStory subscription; every generation task consumes credits, and a failed task refunds them automatically. Check your balance at any time:

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

The credits charged for a talking-avatar video are reported as cost_credit on its status response, so you can see the exact cost of every task after it finishes. For AI Video, you can also query the cost before submitting — GET /api/v1/ai_video/cost applies exactly the same formula as billing. See AI Video.

Models

Talking-avatar models render your avatar. Query GET /api/v1/models for the machine-readable catalog; the current lineup:

model_id Best for Aspect ratios Resolutions Max duration
vs_character_v4 Recommended default — improved motion quality and stability 9:16, 16:9, 1:1 720p, 1080p, 2k 600 s
vs_talk_v1 Speech Mode — focuses on mouth movements, ideal for clear lip-syncing 9:16, 16:9, 1:1 480p, 720p, 1080p 600 s

Beyond talking avatars, the API also exposes frontier AI video generation models (Seedance family) for text-to-video and image-to-video — currently in beta. See AI Video.

Where to go next