Metadata-Version: 2.5
Name: visionstory-cli
Version: 0.0.10
Summary: Command-line interface for the VisionStory API - AI talking-avatar video generation.
Project-URL: Homepage, https://developers.visionstory.ai
Project-URL: Documentation, https://developers.visionstory.ai/guides/cli
Author-email: VisionStory <register@visionstory.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,avatar,cli,command-line,talking-avatar,video-generation,visionstory
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: visionstory==0.0.10
Description-Content-Type: text/markdown

# VisionStory CLI

Command-line interface for the [VisionStory API](https://developers.visionstory.ai) — generate media, clone voices, synthesize speech, transcribe audio, create subtitles, and align scripts from your terminal.

- **Covers the whole API** — every list, create, query, and delete operation has a subcommand.
- **JSON in, JSON out** — prints the API response to stdout; composes with `jq` and shell scripts.
- Thin wrapper over the [`visionstory`](https://pypi.org/project/visionstory/) SDK — same auth, same API.

## Install

```bash
pip install visionstory-cli
```

This installs the `visionstory` command (and pulls in the `visionstory` SDK). For the Python library on its own, install [`visionstory`](https://pypi.org/project/visionstory/); for the MCP server, [`visionstory-mcp`](https://pypi.org/project/visionstory-mcp/).

## Quick start

```bash
visionstory login

visionstory avatars --is-public
visionstory voices
visionstory create-video --avatar-id 4321918387609092991 --text "Hello from VisionStory." --voice-id Alice --output result.mp4
visionstory status --video-id 7241059991822401536
```

`visionstory login` hides, verifies, and securely saves the API key for later CLI sessions. Scripts and CI can instead
set `VISIONSTORY_API_KEY`; it takes precedence over the saved login. The key is never accepted as a flag.
`create-video` and `create-ai-video` block until the video is ready and download it with `--output`; add `--no-wait`
to return immediately.

## Commands

```bash
# Discover
visionstory --version
visionstory login
visionstory logout
visionstory update --check
visionstory doctor
visionstory contract
visionstory voices --locale en-GB --provider ElevenLabs --limit 20
visionstory models
visionstory avatars --is-public
visionstory credits
visionstory videos
visionstory assets

# Talking-avatar video
visionstory create-video --avatar-id <id> --text "..." --voice-id Alice --output result.mp4
visionstory status --video-id <id>

# Avatars / voices / assets
visionstory create-avatar --image-url <url>
visionstory update-avatar-framing --avatar-id <id> --aspect-ratio 9:16 --zoom 1.2 --offset-x 0 --offset-y -0.25
visionstory clone-voice --audio-url <url>
visionstory upload-asset --url <url>

# Text-to-speech, audio understanding, image, AI video (Seedance, Wan, Kling)
visionstory tts --text "..." --voice-id Alice --locale en-GB --output speech.mp3
visionstory transcribe --audio-file interview.mp3 --diarize --srt --output interview.srt
visionstory align --audio-url https://example.com/speech.mp3 --text "..."
visionstory create-image --model-id <model> --prompt "..."
visionstory ai-video-cost --model-id seedance-2.0 --duration-sec 8
visionstory create-ai-video --model-id seedance-2.0 --prompt "..." --output ai.mp4

# Delete
visionstory delete-video --video-id <id>
```

Run `visionstory --help` or `visionstory <command> --help` for every command and flag. Full guide: <https://developers.visionstory.ai/guides/cli>.

## Manage the installation

```bash
visionstory --version       # installed version, human-readable
visionstory version         # installed version as JSON
visionstory login           # securely verify and save an API key
visionstory logout          # remove the saved API key
visionstory update --check  # compare with the latest PyPI release
visionstory update          # upgrade through uv tool or pip
visionstory doctor          # local setup diagnostics; never prints the API key
visionstory uninstall       # asks before removing the CLI
```

Interactive commands also check the shared release manifest at most once per day. A newer release is announced on stderr at most once per week with its upgrade command and release notes, so JSON stdout stays safe for scripts. Checks fail silently offline and never install updates automatically. Set `VISIONSTORY_UPDATE_CHECK=0` to disable passive notices.

`visionstory upgrade` is an alias for `visionstory update`. For an unattended uninstall, use
`visionstory uninstall --yes`.

`visionstory contract` requires no API key and prints the OpenAPI contract version, SHA-256
fingerprint, and operation count shared by the SDK and MCP package.

## License

MIT

## Extract structured data from media

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

```bash
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](https://developers.visionstory.ai/guides/media-understanding). TTS supports `slow`, `normal`, or `fast`; omission keeps normal speed.
