Overview

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": "2026-08-20T06:15:18Z"
}

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?is_public=true"

The response lists avatars newest first, paginated with cursor / next_cursor: the curated public library with is_public=true, or your own avatars by default. 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:

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

• Quick start — your first video in five steps.
• Avatars — create a custom avatar from a photo.
• Voices — clone a voice and use it in any video.
• AI Video — text-to-video and image-to-video with Seedance models.
• Developer tools — SDK, CLI, MCP, and Agent Skill documentation.
• API reference — every endpoint, schema, and error code.