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 sign in. The CLI hides the key while you type, verifies it with a read-only credits request, and saves it for future CLI sessions:

visionstory login

The success message confirms the connection and shows the remaining credit balance. A 401 response means the key is missing, expired, or invalid; replace it on the API keys page, then rerun visionstory login.

Check, update, diagnose, or uninstall the CLI

These local commands do not require an API key:

visionstory --version
visionstory login
visionstory logout
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. Sign in once (skip this if you already completed it)
visionstory login

# 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

API operation commands print responses as JSON to stdout and exit non-zero on error, so they compose with jq and shell scripts. Lifecycle commands such as login, logout, update, and uninstall use concise human-readable output.

When you run the CLI interactively, it checks the shared VisionStory release manifest at most once per day. If a newer version adds capabilities, a short notice is written to stderr at most once per week with the version, release title, update command, and release notes. JSON stdout remains unchanged, offline checks fail silently, and the CLI never updates itself without visionstory update.

Set VISIONSTORY_UPDATE_CHECK=0 to disable passive notices. Use visionstory update --check whenever you want an immediate PyPI version comparison without installing anything.

Authenticate CLI commands

For local interactive use, sign in once:

visionstory login

Typed characters stay hidden. The CLI validates the key before saving it to your user configuration directory with owner-only permissions. Run visionstory logout to remove the saved key.

For scripts and CI, set VISIONSTORY_API_KEY in the process environment instead. Environment credentials take precedence over a saved login, and the key is never accepted as a command-line argument.

Default and custom configuration

Default: connect to the official API

For normal use, run visionstory login once. You do not need to configure an API address.

Use doctor to inspect the resolved address (api_base_url) and authentication source without sending an API request or printing the key. After confirming the address, credits makes a read-only API request to verify access:

visionstory doctor
visionstory credits

Override the address for one command

For a trusted proxy, gateway, or test server compatible with VisionStory, pass the address explicitly. Replace the example domain with your own service:

visionstory --base-url https://your-api.example.com doctor
visionstory --base-url https://your-api.example.com credits

Global options go before the subcommand. This also applies when changing the request timeout:

visionstory --base-url https://your-api.example.com --request-timeout 120 credits

--base-url affects only that invocation. A subsequent command without the flag uses the environment variable, if set, or the official API.

Use the same address throughout a terminal session

In a macOS, Linux, or WSL shell:

export VISIONSTORY_API_BASE="https://your-api.example.com"
visionstory doctor
visionstory credits

This applies to the current shell and its child processes, not future terminals. For a persistent setup, configure the variable in your shell startup file or your deployment environment. In CI, inject the API key separately through the platform's secret store.

Address priority: --base-url → VISIONSTORY_API_BASE → https://openapi.visionstory.ai.

To restore the official address in that shell, remove the variable and omit --base-url:

unset VISIONSTORY_API_BASE
visionstory doctor

If you also configured the variable in a startup file or deployment settings, remove it there to keep future sessions on the default. Do not set it to an empty string.

Check the destination before sending a key. Use a trusted HTTPS server that implements the VisionStory API. SDK-backed API commands send the active key in X-API-Key, including when using a custom domain. Provide the base address without /api/v1; the CLI appends endpoint paths. Login saves only the key, not a domain-specific profile or the custom address. Logging in with --base-url does not change the address used by later commands.

--request-timeout controls HTTP requests, not total video generation time. Some operations have their own request timeout. The download command fetches its --url directly; --base-url does not rewrite that URL.

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 voices --locale es-MX --provider minimax --limit 50
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.

visionstory voices accepts --cursor, --limit, --locale, and --provider. A base BCP 47 locale such as es matches all Spanish voices; use a regional locale such as es-MX, en-GB, zh-TW, or zh-HK when pronunciation and accent need to match one region.

Generate text-to-speech audio

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

--locale is optional. Use a BCP 47 value such as en-GB or zh-TW to steer pronunciation and accent for multilingual voices.

Transcribe and align audio

Transcribe a local WAV or MP3 file to JSON, or request speaker labels and SRT subtitle output:

visionstory transcribe --audio-file interview.mp3 --diarize --srt --output interview.srt

Use align when you already know the exact spoken text and need word-level timestamps:

visionstory align --audio-url https://example.com/speech.mp3 --text "Welcome to VisionStory."

Both commands accept exactly one of --audio-file, --audio-url, or --asset-id. See Audio Transcription and Alignment for limits and billing.

Generate AI images

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

Generate AI videos with Seedance, Wan, and Kling

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.
• Audio Transcription and Alignment — speech-to-text, SRT, and word timing.
• API reference — every endpoint the CLI wraps.

Extract structured data from media

Use a public URL or an existing asset ID. --inputs and --schema accept JSON; replace the placeholder before running.

visionstory understand-media --prompt "Identify the subject" --inputs '[{"asset_id":"YOUR_ASSET_ID"}]' --schema '{"type":"object","properties":{"subject":{"type":"string"}},"required":["subject"]}'
visionstory tts --text "Hello" --voice-id YOUR_VOICE_ID --speech-rate slow --output speech.mp3

Media extraction is synchronous (up to 180 seconds), returns output, usage, and cost_credit, and bills only successful calls. Do not blindly retry timeouts. See Media Understanding. TTS supports slow, normal, or fast; omission keeps normal speed.