Search VisionStory documentation

No documentation matched “”.

Try a feature or resource name such as , , or .

VisionStoryDevelopers
Get API key

Guide

VisionStory Python SDK

Install the official zero-dependency Python SDK for the VisionStory API, then authenticate, generate videos, upload assets, poll jobs, and download results.

The visionstory package is the official Python SDK for the VisionStory API. This zero-dependency client uses only the Python standard library and handles authentication, JSON, base64 uploads, asynchronous polling, errors, and media downloads.

Requires Python 3.10+.

Install the VisionStory Python SDK

Shell
pip install visionstory

Authenticate the Python client

Create an API key in the VisionStory API dashboard (available on Pro plans and above), then store it in an environment variable. The client reads the key without putting it in source code:

Shell
export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"
Python
from visionstory import VisionStoryClient

client = VisionStoryClient.from_env()

Keep VisionStoryClient.from_env() as the default, especially in shared code and agent workflows, so credentials never appear in source or chat.

Generate a talking avatar video in Python

generate_video submits the job and polls until it finishes — one call in, a finished video out:

Python
from pathlib import Path
from visionstory import VisionStoryClient, build_video_payload

client = VisionStoryClient.from_env()

payload = build_video_payload(
    avatar_id="YOUR_AVATAR_ID",        # select from client.list_avatars()
    text="Hello World, this is my first video.",
    voice_id="YOUR_VOICE_ID",          # select from client.list_voices()
)
video = client.generate_video(payload)          # submit + poll until "created"
client.download(video["video_url"], Path("result.mp4"))
print("saved result.mp4")

build_video_payload takes text or audio_url / audio_file (exactly one), plus optional model_id, aspect_ratio, resolution, speech_rate, and more — it maps directly to the POST /api/v1/video body.

Use the VisionStory CLI

A separate visionstory-cli package provides a visionstory command that covers the same surface — no code required:

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

See the CLI guide for every command, flag, and example.

List models, avatars, voices, and credits

Don't hardcode IDs — list them and pick at runtime:

Python
client.list_models()      # avatar render models
client.list_avatars()     # your avatars + public ones
client.list_voices()      # your voices + public ones
client.get_credits()      # remaining balance

Verify SDK, CLI, and MCP compatibility

Python
from visionstory import get_contract_info

print(get_contract_info())
# contract_version, SHA-256 contract_hash, and operation_count=24

The same fingerprint is available through visionstory contract and the MCP resource visionstory://contract. Matching values mean the SDK, CLI, and MCP server were built from the same OpenAPI and channel mapping.

Create avatars, clone voices, and upload assets

Python
client.create_avatar(image_url="https://your.site/face.jpg")   # or image_file=Path("face.jpg")
client.clone_voice(audio_url="https://your.site/sample.mp3")   # or audio_file=Path("sample.mp3")
client.upload_asset(url="https://your.site/clip.mp4")          # or file_path=Path("clip.mp4")

upload_asset returns a reusable asset_id you can reference from AI Video requests.

Control asynchronous polling

Submit and poll separately when you want to show progress or do other work in between:

Python
created = client.create_video(payload)          # returns immediately with a video_id
video = client.wait_for_video(created["video_id"], poll_interval=5, timeout=600)

generate_video(payload, wait=False) is equivalent to create_video.

Handle SDK errors and timeouts

Python
from visionstory import VisionStoryAPIError, VideoTimeoutError

try:
    video = client.generate_video(payload)
except VideoTimeoutError:
    ...   # still not finished after `timeout` seconds
except VisionStoryAPIError as e:
    ...   # API returned an error, or the task failed — credits for failed tasks are refunded automatically