# VisionStory API documentation for developers and AI agents

> Build talking-avatar video, voice cloning, text-to-speech, image generation, and AI video workflows with the REST API, Python SDK, CLI, MCP server, and Agent Skill.

Documentation version: 0.0.6 · Status: testing · Last reviewed: 2026-08-27

## Start here

- New integration or first video: [Quick start](https://developers.visionstory.ai/guides/quick-start.md)
- Exact request and response schema: [OpenAPI 3.1 JSON](https://developers.visionstory.ai/openapi.json)
- AI agent, MCP, or Agent Skill setup: [For agents](https://developers.visionstory.ai/guides/for-agents.md)
- SDK or CLI automation: [Python SDK](https://developers.visionstory.ai/guides/sdk.md) and [CLI](https://developers.visionstory.ai/guides/cli.md)
- API changes and deprecations: [Changelog](https://developers.visionstory.ai/guides/changelog.md)

Load the one guide that matches the task, then use OpenAPI for exact fields. Use llms-full.txt only when a task spans several capabilities.

## Agent safety and execution contract

- Read `VISIONSTORY_API_KEY` from the local environment. Never ask a user to paste a key into chat, and never print, log, or commit it.
- Discover current model, avatar, and voice IDs with the list endpoints instead of guessing or treating example IDs as valid.
- Use `client_request_id` for retry-safe creation requests when the operation supports it.
- Poll asynchronous jobs no faster than every 5 seconds and stop after 10 minutes unless the user asks to keep waiting.
- Redact credentials when reporting API errors.
- Do not call a DELETE operation without an explicit user request and confirmation.

## Guides

- [VisionStory API Overview](https://developers.visionstory.ai/guides/overview.md)
- [Talking Avatar Video API Quickstart](https://developers.visionstory.ai/guides/quick-start.md)
- [AI Avatar API](https://developers.visionstory.ai/guides/avatars.md)
- [Voice Cloning API](https://developers.visionstory.ai/guides/voices.md)
- [AI Video Generation API](https://developers.visionstory.ai/guides/ai-video.md)
- [Text-to-Speech API](https://developers.visionstory.ai/guides/text-to-speech.md)
- [AI Image Generation API](https://developers.visionstory.ai/guides/image-generation.md)
- [VisionStory Python SDK](https://developers.visionstory.ai/guides/sdk.md)
- [VisionStory CLI](https://developers.visionstory.ai/guides/cli.md)
- [VisionStory API for AI Agents](https://developers.visionstory.ai/guides/for-agents.md)
- [VisionStory API Changelog](https://developers.visionstory.ai/guides/changelog.md)

## API contract

- [OpenAPI 3.1 JSON](https://developers.visionstory.ai/openapi.json)
- [Interactive API reference](https://developers.visionstory.ai/reference)
- [Complete guide corpus](https://developers.visionstory.ai/llms-full.txt)