VisionStory API Overview

The VisionStory API is a REST API for creating talking-avatar videos and programmable AI media. Send text or audio, choose an avatar and voice, submit an asynchronous generation job, and download the finished video from your backend, automation, or AI agent.

How the VisionStory API works

Every integration follows the same loop:

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

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

Request header

X-API-Key: $VISIONSTORY_API_KEY

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:

JSON

{
  "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:

Shell

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

The response contains public_avatars, the curated library, and my_avatars, the avatars you created.

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:

Shell

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

The response contains public_voices and my_voices.

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:

Shell

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.

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 — focused mouth movement and clear lip-syncing	9:16, 16:9, 1:1	480p, 720p, 1080p	600 s

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.