VisionStory API for AI Agents

AI agents can generate VisionStory videos, images, speech, avatars, and voices through MCP, the Python SDK, CLI, or machine-readable documentation. The focused Agent Skill covers the common talking-avatar workflow. Every channel uses the same REST API and VISIONSTORY_API_KEY; choose the integration that matches where your agent runs.

Choose an AI agent integration

Whichever channel you use, configure the key the same way — the agent reads it from an environment variable. If the variable is missing, the agent must explain how to set it locally and must never ask you to paste the key into chat:

export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"

Before asking an agent to submit a paid generation, run the read-only visionstory credits command or call the MCP get_credits tool. A 401 response means the local key is missing, expired, or invalid and must be replaced at visionstory.ai/openapi.

Connect the VisionStory MCP server

For most users, the recommended local setup below is enough. Your MCP client starts VisionStory on demand and receives the same 24 public operations available through the SDK and CLI.

Recommended setup — Run with uvx 👍

Install uv once. Skip this command if uvx --version already works:

curl -LsSf https://astral.sh/uv/install.sh | sh

Confirm VisionStory MCP can start:

uvx --refresh visionstory-mcp --check

When it prints ✓ VisionStory MCP started successfully, add this configuration to your MCP client. In Claude Desktop, open Settings → Developer → Edit Config:

{
  "mcpServers": {
    "visionstory": {
      "command": "uvx",
      "args": ["visionstory-mcp"],
      "env": { "VISIONSTORY_API_KEY": "YOUR_LOCAL_VISIONSTORY_API_KEY" }
    }
  }
}

Replace the API-key placeholder only in your local client configuration, then restart the client. Ask it to call get_credits and list_models; the connection is ready when both succeed.

Alternative — Install with pip

Use this only if you prefer a permanently installed visionstory-mcp command:

python3 -m pip install --upgrade visionstory-mcp

In the configuration above, replace the command and arguments with:

"command": "visionstory-mcp",
"args": []

Advanced — Connect to a remote MCP endpoint

The local uvx visionstory-mcp setup above remains the simplest option and continues to support files on your computer. Teams that want one centrally managed MCP service can additionally deploy the repository's stateless Streamable HTTP service and connect to its /mcp endpoint.

{
  "mcpServers": {
    "visionstory-remote": {
      "url": "https://YOUR_MCP_HOST/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LOCAL_VISIONSTORY_API_KEY"
      }
    }
  }
}

This option is for teams operating a shared MCP service. Local files must be uploaded or available through HTTP(S); choose uvx when the agent needs direct access to files on your computer.

For every setup, keep the API key local and never paste it into chat or commit it to Git. Generation tools wait for results by default, and deletion tools require explicit confirmation.

Use the Python SDK from an agent

If your agent writes and runs code, pip install visionstory gives it a typed, zero-dependency client:

from visionstory import VisionStoryClient, build_video_payload

client = VisionStoryClient.from_env()   # reads VISIONSTORY_API_KEY
video = client.generate_video(build_video_payload(
    avatar_id="YOUR_AVATAR_ID", text="Hello from VisionStory.", voice_id="YOUR_VOICE_ID"))

Select both IDs from client.list_avatars() and client.list_voices() immediately before building a request. Values shown in examples are placeholders, not guaranteed resources.

Prefer the terminal? pip install visionstory-cli gives a visionstory command-line tool, so an agent can run visionstory create-video ... without writing code. See the Python SDK guide for the full client.

Install the VisionStory Agent Skill

For skill-compatible coding agents (Claude Code, Codex, …), install the skill straight from GitHub. The skills CLI auto-detects your agent and drops the skill into .agents/skills/:

npx skills add visionstory-ai/skills --skill visionstory-api

The installer may display Snyk warning W011 because the text you ask the avatar to speak is sent to POST /api/v1/video. That network transfer is the purpose of the skill, not an undeclared dependency; review the generated security-audit link and the public skill source before accepting it.

No Node? Clone the repo and copy the skill folder in yourself:

git clone https://github.com/visionstory-ai/skills.git
mkdir -p .agents/skills
cp -r skills/visionstory-api .agents/skills/

The package contains SKILL.md (workflow instructions the agent follows) and scripts/visionstory_api.py, a zero-dependency Python helper for the talking-avatar workflow, including resource discovery, authentication, base64 encoding, polling, timeouts, and downloads. Use MCP, the standalone CLI, or the Python SDK when the agent needs all 24 public operations such as AI Video, image generation, text to speech, and assets. Skills-compatible agents pick it up automatically; you can also view SKILL.md without downloading, or browse the source at github.com/visionstory-ai/skills. The helper works standalone too:

python3 .agents/skills/visionstory-api/scripts/visionstory_api.py models
python3 .agents/skills/visionstory-api/scripts/visionstory_api.py create-video --avatar-id YOUR_AVATAR_ID --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --output result.mp4

Give agents llms.txt and OpenAPI

Point any web-capable agent at the docs index; it links every guide in agent-readable form:

Read https://developers.visionstory.ai/llms.txt for the VisionStory API docs index.
Append .md to any guide URL to get that guide as Markdown.
Load the one guide that matches the task, then use OpenAPI for exact fields.
Use https://developers.visionstory.ai/llms-full.txt only when the task spans several capabilities.
Use https://developers.visionstory.ai/openapi.json for the complete machine-readable API contract.

You can also hand a single .md guide URL or the OpenAPI JSON URL to an agent directly.

Generate a video with one agent instruction

With the Skill installed (or the MCP server connected), a single instruction produces a video:

Create a talking-avatar video that says "Welcome to our launch week!", pick a friendly public avatar and an energetic voice, wait for it to finish, and save it as launch.mp4.

The agent will list avatars and voices, submit POST /api/v1/video, poll GET /api/v1/video?video_id=... until created, and download the video_url — the same flow as the Quick start.

Security and reliability rules for agents

• Read the key from VISIONSTORY_API_KEY; never print, log, or commit it.
• If the key is missing, explain how the user can set it locally; never ask them to paste it into chat.
• Discover resources (GET /api/v1/models, /api/v1/avatars, /api/v1/voices) instead of guessing IDs.
• Treat every ID shown in documentation as a placeholder until it has been returned by a discovery or creation request.
• Pass client_request_id when the create operation supports it so network retries cannot create a second charged task.
• Poll no faster than every 5 seconds; stop after 10 minutes unless asked to keep waiting.
• Handle the failed status explicitly and report the server's error message (with credentials redacted).
• Never call a DELETE operation without an explicit user request and confirmation immediately before the call.

Related VisionStory developer guides

• Quick start — the underlying five-step flow.
• AI Video — text-to-video and image-to-video for agents with beta access.
• API reference — every endpoint the channels are built on.
• Changelog — documentation version, API changes, and deprecation status.