# VisionStory API Documentation

VisionStory provides a REST API for AI avatar video generation: turn a script (text or audio) into a lip-synced talking avatar video, create custom avatars from a photo, clone voices, and generate videos with frontier AI video models.

## Instructions for AI Agents

- Every page listed below is served as raw markdown; append `.md` to any documentation page URL to get its markdown variant.
- For the complete documentation in a single file, fetch https://openapi.visionstory.ai/docs/llms-full.txt.

## Overview

- [VisionStory API Documentation](https://openapi.visionstory.ai/docs.md): Landing page with the capability catalog and agent entry points.
- [Overview](https://openapi.visionstory.ai/docs/guides/overview.md): 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, subm...
- [For agents](https://openapi.visionstory.ai/docs/guides/for-agents.md): AI agents can drive the VisionStory API through three channels. All three use the same API key and the same REST API underneath — pick the one that fits where your agent runs.

## Talking Avatar Video

Turn a script (text or audio) into a lip-synced talking avatar video.

- [Quick start](https://openapi.visionstory.ai/docs/guides/quick-start.md): Generate your first talking-avatar video in five steps. The whole flow is: get a key, set up a client, submit a script, poll, download.
- [Generate video](https://openapi.visionstory.ai/docs/reference/post-api-v1-video.md): POST /api/v1/video — Generate a talking-avatar video: an avatar speaks a script provided either as text-to-speech
- [Get video status](https://openapi.visionstory.ai/docs/reference/get-api-v1-video.md): GET /api/v1/video — Get a single video task by `video_id`, including its status (`queued`, `creating`, `created`, or
- [List videos](https://openapi.visionstory.ai/docs/reference/get-api-v1-videos.md): GET /api/v1/videos — List your most recent videos (up to 100, newest first). Not paginated — intended for quick access to
- [Delete video](https://openapi.visionstory.ai/docs/reference/delete-api-v1-video.md): DELETE /api/v1/video — Delete one of your videos by `video_id`. Only videos you created are affected, and deletion cannot

## Avatars

Create custom avatars from a photo, or pick from the public library.

- [Avatars](https://openapi.visionstory.ai/docs/guides/avatars.md): An avatar is the on-screen character that speaks your script in a generated video. Use a curated avatar from the public library, or create a custom avatar from a single photo an...
- [Create avatar](https://openapi.visionstory.ai/docs/reference/post-api-v1-avatar.md): POST /api/v1/avatar — Create a custom avatar from a single portrait image (JPEG/PNG/WEBP/HEIC, up to 10MB). The returned
- [List avatars](https://openapi.visionstory.ai/docs/reference/get-api-v1-avatars.md): GET /api/v1/avatars — List avatars available to your account: the public platform library plus your own custom avatars
- [Delete avatar](https://openapi.visionstory.ai/docs/reference/delete-api-v1-avatar.md): DELETE /api/v1/avatar — Delete one of your custom avatars by `avatar_id`. Only avatars you created can be deleted; public

## Voices

Clone a voice from audio samples and use it in any video.

- [Voices](https://openapi.visionstory.ai/docs/guides/voices.md): A voice is the `voice_id` that turns your text into speech inside a video. Use a voice from the public library, or clone a voice from an audio sample and make every video speak ...
- [Clone voice](https://openapi.visionstory.ai/docs/reference/post-api-v1-voice.md): POST /api/v1/voice — Clone a voice from a clean audio sample (AVI/MP3/MP4/M4A/WAV, up to 30MB) and get a reusable
- [List voices](https://openapi.visionstory.ai/docs/reference/get-api-v1-voices.md): GET /api/v1/voices — List the voices you can synthesize with: the public voice library plus any voices you have cloned.
- [Delete voice](https://openapi.visionstory.ai/docs/reference/delete-api-v1-voice.md): DELETE /api/v1/voice — Delete one of your cloned voices by `voice_id`. Only voices you created can be removed.

## Models

Machine-readable catalog of avatar rendering models.

- [List avatar models](https://openapi.visionstory.ai/docs/reference/get-api-v1-models.md): GET /api/v1/models — List the avatar rendering models available for talking-avatar videos. Each entry reports its

## Billing

Check subscription plan and remaining credits.

- [Get credit balance](https://openapi.visionstory.ai/docs/reference/get-api-v1-billing-credits.md): GET /api/v1/billing/credits — Return the credits currently available on your account. Every generation deducts credits based on

## AI Video

Generate videos from text or images with frontier AI video models.

- [AI Video](https://openapi.visionstory.ai/docs/guides/ai-video.md): Generate AI videos with Seedance models — text-to-video, image-to-video, and multimodal references — through the same API key and billing you already use for talking avatars.
- [List AI video models](https://openapi.visionstory.ai/docs/reference/get-api-v1-ai-video-models.md): GET /api/v1/ai_video/models — List available AI video models with the allowed values and defaults for every parameter, plus media
- [Estimate cost](https://openapi.visionstory.ai/docs/reference/get-api-v1-ai-video-cost.md): GET /api/v1/ai_video/cost — Estimate the credits a generation will cost before submitting, using the same formula as the actual
- [Generate AI video](https://openapi.visionstory.ai/docs/reference/post-api-v1-ai-video.md): POST /api/v1/ai_video — Generate a video with a frontier AI model. Provide `first_frame` (optionally `end_frame`) for
- [Get AI video status](https://openapi.visionstory.ai/docs/reference/get-api-v1-ai-video.md): GET /api/v1/ai_video — Get one task by `video_id`, or up to 20 at once with `video_ids` (comma-separated). Status is
- [List AI videos](https://openapi.visionstory.ai/docs/reference/get-api-v1-ai-videos.md): GET /api/v1/ai_videos — List AI video tasks for this account, newest first. Pass the previous page's `next_cursor` to
- [Delete AI video](https://openapi.visionstory.ai/docs/reference/delete-api-v1-ai-video.md): DELETE /api/v1/ai_video — Soft-delete an AI video task by `video_id`. Only tasks you created are affected.

## Text to Speech

Turn text into natural speech with any public or cloned voice; returns MP3 audio.

- [Text to Speech](https://openapi.visionstory.ai/docs/guides/text-to-speech.md): Turn text into natural-sounding speech with any public or cloned voice. The endpoint is synchronous — the response body **is** the MP3 audio.
- [Create Speech](https://openapi.visionstory.ai/docs/reference/post-api-v1-tts.md): POST /api/v1/tts — Convert text to speech with VisionStory smart TTS. Pick a voice from GET /api/v1/voices (public or

## Image Generation

Generate or edit images from a text prompt and optional reference images; returns an image URL.

- [Image Generation](https://openapi.visionstory.ai/docs/guides/image-generation.md): Generate or edit images from a text prompt, optionally guided by reference images. The endpoint is synchronous — the response carries the finished image URL.
- [Get Image Models](https://openapi.visionstory.ai/docs/reference/get-api-v1-image-models.md): GET /api/v1/image/models — Machine-readable capabilities of available image models: aspect ratios, resolutions, reference
- [Create Image](https://openapi.visionstory.ai/docs/reference/post-api-v1-image.md): POST /api/v1/image — Generate an image from a text prompt, optionally guided by up to 4 reference images

## Assets

Upload and manage reusable media assets (image / audio / video).

- [Upload asset](https://openapi.visionstory.ai/docs/reference/post-api-v1-asset.md): POST /api/v1/asset — Upload a reusable media asset (image / video / audio) from a public URL or inline base64, and get an
- [List assets](https://openapi.visionstory.ai/docs/reference/get-api-v1-assets.md): GET /api/v1/assets — List your uploaded assets, newest first. Pass the previous page's `next_cursor` to paginate
- [Delete asset](https://openapi.visionstory.ai/docs/reference/delete-api-v1-asset.md): DELETE /api/v1/asset — Delete an asset by `asset_id`. Videos already generated from it — or still generating — are