VisionStory CLI

The VisionStory CLI exposes the complete API from a terminal, shell script, or CI job. Install the visionstory-cli package to add the visionstory command for listing resources, generating media, polling jobs, and downloading results. It requires Python 3.10+ and uses the official Python SDK.

Install the VisionStory CLI

The one-line installer supports macOS, Linux, and WSL. It prepares uv when needed and installs the CLI from PyPI into an isolated tool environment.

Install the latest release (recommended)

With no version variable, this command always installs or upgrades to the latest VisionStory CLI release available on PyPI:

curl -fsSL https://developers.visionstory.ai/cli | bash

Pin an exact release

Set VISIONSTORY_VERSION only when you intentionally need a specific older release. For example:

curl -fsSL https://developers.visionstory.ai/cli | VISIONSTORY_VERSION=0.0.4 bash

Prefer to manage the Python environment yourself? Install the same package directly:

pip install visionstory-cli

Confirm it's on your PATH:

visionstory --help

Then set the key and run a read-only authentication check before generating paid media:

export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"
visionstory credits

A 401 response means the key is missing, expired, or invalid. Replace it at visionstory.ai/openapi, then rerun visionstory credits.

Check, update, diagnose, or uninstall the CLI

These local commands do not require an API key:

visionstory --version
visionstory update --check
visionstory update
visionstory doctor
visionstory uninstall

visionstory upgrade is an alias for visionstory update. Use visionstory uninstall --yes only for unattended scripts or CI.

Generate a video from the command line

Four steps to your first video:

# 1. Point the CLI at your key (it is never passed as a flag)
export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"

# 2. Discover a public avatar and voice
visionstory avatars
visionstory voices

# 3. Create a video — blocks until it is ready, then downloads it
visionstory create-video --avatar-id YOUR_AVATAR_ID --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --output result.mp4

# 4. Or check a task you submitted earlier
visionstory status --video-id YOUR_VIDEO_ID

Every command prints the API response as JSON to stdout and exits non-zero on error, so it composes with jq and shell scripts.

Authenticate CLI commands

The CLI reads the API key from the VISIONSTORY_API_KEY environment variable — never as a command-line argument:

export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"

Point the CLI at a different environment with the VISIONSTORY_API_BASE variable or the global --base-url flag.

List API resources

Generate talking-avatar videos

visionstory create-video --avatar-id YOUR_AVATAR_ID --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --output result.mp4

Check status with the ID returned by the create command. Deletion is irreversible, so run the delete command only after the owner explicitly requests and confirms it:

visionstory status --video-id YOUR_VIDEO_ID
visionstory delete-video --video-id YOUR_VIDEO_ID

Manage avatars, voices, and assets

visionstory create-avatar --image-url https://your.site/face.jpg
visionstory clone-voice --audio-url https://your.site/sample.mp3 --preview-text "Hello"
visionstory upload-asset --url https://your.site/clip.mp4

visionstory delete-avatar --avatar-id YOUR_AVATAR_ID
visionstory delete-voice --voice-id YOUR_VOICE_ID
visionstory delete-asset --asset-id YOUR_ASSET_ID

Pass a local path instead of a URL with --image, --audio-file, or --file.

Generate text-to-speech audio

visionstory tts --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --output speech.mp3

Generate AI images

visionstory image-models
visionstory create-image --model-id <model> --prompt "a corgi surfing at sunset"

Generate AI videos with Seedance

visionstory ai-video-models
visionstory ai-video-cost --model-id seedance-2.0 --duration-sec 8 --resolution 1080p
visionstory create-ai-video --model-id seedance-2.0 --prompt "a corgi surfing at sunset" --duration-sec 8 --output ai.mp4

visionstory ai-video-status --video-id YOUR_AI_VIDEO_ID
visionstory ai-videos --limit 20
visionstory delete-ai-video --video-id YOUR_AI_VIDEO_ID

Image-to-video and reference-guided generation take media as URLs:

visionstory create-ai-video --model-id seedance-2.0 --prompt "the scene comes alive" --first-frame-url https://your.site/start.jpg --output ai.mp4
visionstory create-ai-video --model-id seedance-2.0 --prompt "the same character walks on" --ref-url https://your.site/char.jpg

For advanced payloads (base64 inline_data, asset_id references, multiple refs), pass the full request body with --json:

visionstory create-ai-video --json '{"model_id":"seedance-2.0","prompt":"...","refs":[{"asset_id":"YOUR_ASSET_ID"}]}' --output ai.mp4

create-image accepts --json the same way.

CLI behavior and output

• JSON everywhere — every command prints the API response as JSON; pipe to jq to extract fields.
• Contract diagnostics — visionstory contract needs no API key and prints the shared SDK/CLI/MCP OpenAPI fingerprint and operation count.
• Blocking creates — create-video and create-ai-video poll until the video is created and download it with --output; add --no-wait to return the task immediately.
• Exit codes — 0 on success, 1 on any error (the message goes to stderr).
• Same surface as the SDK — every command maps 1:1 to a Python SDK method; reach for the SDK when you need to embed the logic in code.

Related VisionStory developer guides

• Python SDK — the library the CLI is built on.
• API reference — every endpoint the CLI wraps.