VisionStory API Overview

The VisionStory API is a REST API for talking-avatar videos and programmable AI media. Generate video, speech, and images; clone voices and avatars; transcribe audio; create subtitles; and manage reusable media from a backend, automation, or AI agent.

How the VisionStory API 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 — call 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: $VISIONSTORY_API_KEY

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

Create your API key on the VisionStory API keys page. 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": "YOUR_VIDEO_ID"
  },
  "message": "success",
  "server_time": "2026-08-20T06:15:18Z"
}

Core API resources

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 default response contains your owned avatars in avatars; add is_public=true to query the public library instead. Follow next_cursor to load additional pages.

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.

Audio understanding

Transcribe WAV or MP3 speech into text, word-level timestamps, speaker labels, and SRT subtitles, or align a known script with its audio. See the Audio Transcription and Alignment API for request examples and billing.

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 finished task.

Talking avatar models

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

The retired vs_talk_v1 model is no longer returned by the model catalog. New requests must choose 720p, 1080p, or 2k from GET /api/v1/models; 480p is no longer accepted as a talking-avatar video request value.

Beyond talking avatars, the API exposes frontier AI video generation models for text-to-video and image-to-video workflows. These capabilities are currently in beta.

Start building with the VisionStory API

• Quick start — create your first video in five steps.
• API reference — explore the available endpoints, schemas, and examples.
• Get an API key — configure a server-side integration.

Structured media understanding

Extract structured JSON from images, audio, or video with POST /api/v1/media/understand. Supply a prompt, 1–8 media references, and an object-root JSON Schema. See Media Understanding for SDK, CLI, and MCP examples. For transcription and subtitle timing, use Speech to Text.