# VisionStory API — complete developer and agent guides Documentation URL: https://developers.visionstory.ai OpenAPI contract: https://developers.visionstory.ai/openapi.json API base URL: https://openapi.visionstory.ai Documentation version: 0.0.16 Status: testing Last reviewed: 2026-11-17 Changelog: https://developers.visionstory.ai/guides/changelog Release manifest: https://developers.visionstory.ai/releases/latest.json ## Agent safety and execution contract - Read `VISIONSTORY_API_KEY` from the local environment. Never ask a user to paste a key into chat, and never print, log, or commit it. - Discover current model, avatar, and voice IDs with the list endpoints instead of guessing or treating example IDs as valid. - Use `client_request_id` for retry-safe creation requests when the operation supports it. - Poll asynchronous jobs no faster than every 5 seconds and stop after 10 minutes unless the user asks to keep waiting. - Redact credentials when reporting API errors. - Do not call a DELETE operation without an explicit user request and confirmation. # VisionStory API Overview The VisionStory API is a REST API for talking-avatar videos and programmable AI media. Generate video, speech, and images; clone voices and avatars; transcribe audio; create subtitles; and manage reusable media from a backend, automation, or AI agent. ## How the VisionStory API works Every integration follows the same loop: 1. **Discover resources** — list available models, avatars, and voices. 2. **Submit a generation task** — `POST /api/v1/video` returns a `video_id` immediately. 3. **Poll until done** — call `GET /api/v1/video?video_id=...` until the status is `created`. 4. **Download the result** — fetch `video_url` from the response. All requests go to one base URL and authenticate with one header: ```text [Request header] X-API-Key: $VISIONSTORY_API_KEY ``` **Base URL:** `https://openapi.visionstory.ai` Create your API key on the [VisionStory API keys page](https://developers.visionstory.ai/api-keys). Keep the key on your server — never expose it in browser code or a public repository. Every response shares one envelope. Read successful payloads from the top-level `data` field: ```json { "data": { "video_id": "YOUR_VIDEO_ID" }, "message": "success", "server_time": "2026-08-20T06:15:18Z" } ``` ## Core API resources ### Avatar An avatar is the on-screen character that speaks your script. Use a ready-made avatar from the public library, or create your own from a single photo: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/avatars ``` The default response contains your owned avatars in `avatars`; add `is_public=true` to query the public library instead. Follow `next_cursor` to load additional pages. ### Voice A voice is the `voice_id` that turns text into speech inside a video. Pick from the public voice library, or clone your own voice from an audio sample: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/voices ``` The response contains `public_voices` and `my_voices`. ### Audio understanding Transcribe WAV or MP3 speech into text, word-level timestamps, speaker labels, and SRT subtitles, or align a known script with its audio. See the [Audio Transcription and Alignment API](/guides/audio-understanding) for request examples and billing. ### Credit A credit is the billing unit for generation. Credits come with your VisionStory subscription; every generation task consumes credits, and a failed task refunds them automatically. Check your balance at any time: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/billing/credits ``` The credits charged for a talking-avatar video are reported as `cost_credit` on its status response, so you can see the exact cost of every finished task. ## Talking avatar models Talking-avatar models render your avatar. Query `GET /api/v1/models` for the machine-readable catalog. | model_id | Best for | Aspect ratios | Resolutions | Max duration | |---|---|---|---|---| | `vs_character_v4` | Recommended default — improved motion quality and stability | 9:16, 16:9, 1:1 | 720p, 1080p, 2k | 600 s | The retired `vs_talk_v1` model is no longer returned by the model catalog. New requests must choose `720p`, `1080p`, or `2k` from `GET /api/v1/models`; `480p` is no longer accepted as a talking-avatar video request value. Beyond talking avatars, the API exposes frontier AI video generation models for text-to-video and image-to-video workflows. These capabilities are currently in beta. ## Start building with the VisionStory API - [Quick start](/guides/quick-start) — create your first video in five steps. - [API reference](/reference) — explore the available endpoints, schemas, and examples. - [Get an API key](https://developers.visionstory.ai/api-keys) — configure a server-side integration. ## Structured media understanding Extract structured JSON from images, audio, or video with `POST /api/v1/media/understand`. Supply a prompt, 1–8 media references, and an object-root JSON Schema. See [Media Understanding](/guides/media-understanding) for SDK, CLI, and MCP examples. For transcription and subtitle timing, use [Speech to Text](/guides/audio-understanding). --- # Talking Avatar Video API Quickstart This quickstart takes you from an API key to a saved talking-avatar MP4 in five steps: verify authentication and credits, discover a public avatar and voice, submit a text script, poll the asynchronous job, and download the result. ## Before you start {#before-you-start} ### API access {#api-access} API keys are available on Pro plans and above. Create a key on the [API keys page](/api-keys), then use the [authentication guide](/reference/authentication) to configure your backend. Keep the key server-side. API access uses your VisionStory account and generation credits. ### Credits and billing {#credits-and-billing} Check your current balance with the [credits endpoint](/reference/billing/get-credits) before submitting a generation. Talking-avatar video costs depend on the model, resolution, and duration; the [video status response](/reference/videos/get-video-detail) reports the task's `cost_credit`. For prompt- or image-based AI video clips, use the separate [AI video cost endpoint](/reference/ai-videos/get-ai-video-cost) with the selected model and inputs. Speech synthesis reports usage and credits in its [response headers](/guides/text-to-speech#billing-limits-and-storage). These interfaces expose costs differently; use the documentation for the workflow you are integrating. ### Limits and formats {#limits-and-formats} Use [model discovery](/reference/models/get-models) for supported aspect ratios, resolutions, and maximum duration. Check [avatar creation](/reference/avatars/create-avatar) for portrait requirements and the [video request schema](/reference/videos/create-video) for accepted audio inputs. The [AI Video guide](/guides/ai-video) covers the distinct limits of prompt- and reference-based video models. ## 1. Create a VisionStory API key {#1-create-a-visionstory-api-key} Sign up and create an API key on the [VisionStory API keys page](https://developers.visionstory.ai/api-keys). Send it with every request in the `X-API-Key` header: ```text [Request header] X-API-Key: $VISIONSTORY_API_KEY ``` Keep the key on your server and never expose it in browser code or a public repository. The examples below read it from an environment variable: ```bash export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx" ``` VisionStory CLI users can instead run `visionstory login` after installation. It hides the input, verifies the key, and saves it for future CLI sessions without putting the secret in shell history. Before starting a paid generation, verify the key with a read-only request: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \ https://openapi.visionstory.ai/api/v1/billing/credits ``` A successful response includes `data.remaining`, your current VisionStory credit balance. A `401` response means the key is missing, expired, or no longer valid; create or replace it at [API keys page](https://developers.visionstory.ai/api-keys) before continuing. ## 2. Choose a client and discover resources {#2-choose-an-api-client} Choose a client for your environment, then use read-only discovery to get valid resource IDs before submitting a generation. ### Python SDK {#python-sdk} Follow the [Python SDK installation and authentication guide](/guides/sdk), then use the [complete SDK example below](#complete-python-sdk-example). The SDK has no runtime dependencies. ### VisionStory CLI {#visionstory-cli} For terminal commands, shell scripts, or CI jobs, follow the [CLI guide](/guides/cli) for installation, login, and resource discovery. ### AI agents {#agent-skill} Use the [Agent setup guide](/guides/for-agents) to install the focused talking-avatar Skill or [connect the MCP server](/guides/for-agents#connect-the-visionstory-mcp-server). Complete its read-only connection checks before requesting a video. ### REST API {#rest-api} The steps below use `curl`; any backend HTTP client can send the same requests. See the [API reference](/reference) for exact request and response schemas. ### Discover valid IDs with read-only requests {#discover-valid-ids-with-read-only-requests} Query the current talking-avatar models, public avatars, and English voices. These requests do not generate media: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \ https://openapi.visionstory.ai/api/v1/models curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \ "https://openapi.visionstory.ai/api/v1/avatars?is_public=true&limit=20" curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \ "https://openapi.visionstory.ai/api/v1/voices?locale=en&limit=20" ``` Choose an `avatar_id` from `data.avatars` and a `voice_id` from `data.public_voices`. Confirm that `data.models` includes `vs_character_v4` with `9:16` and `720p` support for the example below. If you need more avatar or voice choices, pass the returned `next_cursor` as `cursor` until it is `0`; change `locale` to find voices for another language. Replace `YOUR_AVATAR_ID` and `YOUR_VOICE_ID` below with your selections. They are placeholders, not usable resource IDs. Generation requires sufficient credits and account access to the selected model and voice; a positive balance alone does not guarantee the request can run. ## 3. Generate a talking avatar video {#3-generate-a-talking-avatar-video} Submit a text script with the public avatar and voice you selected. Replace `YOUR_UNIQUE_REQUEST_ID` with an ID for this job and keep it for retries: within 24 hours, reusing the same `client_request_id` returns the original task without a second charge. The request returns a `video_id` immediately while generation continues asynchronously: ```bash curl -s \ -H "X-API-Key: $VISIONSTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model_id": "vs_character_v4", "avatar_id": "YOUR_AVATAR_ID", "client_request_id": "YOUR_UNIQUE_REQUEST_ID", "text_script": { "text": "Hello World, this is my first test video.", "voice_id": "YOUR_VOICE_ID", "speech_rate": "normal" }, "aspect_ratio": "9:16", "resolution": "720p" }' \ https://openapi.visionstory.ai/api/v1/video ``` ```json { "data": { "video_id": "YOUR_VIDEO_ID" } } ``` To use your own audio, send an `audio_script` in place of `text_script` — never both. ## 4. Poll the video generation job {#4-poll-the-video-generation-job} Replace `YOUR_VIDEO_ID` with the returned `data.video_id`, then query the task every 5 seconds until it reaches a final state: ```bash curl -s \ -H "X-API-Key: $VISIONSTORY_API_KEY" \ "https://openapi.visionstory.ai/api/v1/video?video_id=YOUR_VIDEO_ID" ``` | status | Meaning | |---|---| | `queued` | Accepted, waiting for a worker | | `creating` | Generating | | `created` | Done — `video_url` is ready | | `failed` | Generation failed — stop polling and inspect the error | Avoid polling faster than every 5 seconds, and give up after about 10 minutes. ## 5. Download the generated MP4 {#5-download-the-generated-mp4} When the status is `created`, the response carries a `video_url`. Completed videos are retained for **7 days**, so download the file if you need permanent storage: ```bash curl -sL -o result.mp4 "" ``` ## Complete Python SDK example {#complete-python-sdk-example} After installing the SDK and setting `VISIONSTORY_API_KEY`, this example checks credits and discovers resources before submitting a paid generation. It selects the first returned public avatar and English voice. The SDK unwraps the REST `data` envelope, so read `avatars` and `public_voices` directly from its responses: ```python from pathlib import Path from uuid import uuid4 from visionstory import VisionStoryClient, build_video_payload client = VisionStoryClient.from_env() credits = client.get_credits() if credits["remaining"] <= 0: raise RuntimeError("Add credits before generating a video.") models = client.list_models()["models"] model = next((item for item in models if item["model_id"] == "vs_character_v4"), None) avatars = client.list_avatars(is_public=True, limit=1)["avatars"] voices = client.list_voices(locale="en", limit=1)["public_voices"] if model is None or not avatars or not voices: raise RuntimeError("No matching resources. Review model, avatar, and voice discovery.") if "9:16" not in model.get("aspect_ratios", []) or "720p" not in model.get("resolutions", []): raise RuntimeError("Choose an aspect ratio and resolution supported by the model.") payload = build_video_payload( model_id=model["model_id"], avatar_id=avatars[0]["avatar_id"], text="Hello World, this is my first test video.", voice_id=voices[0]["voice_id"], aspect_ratio="9:16", resolution="720p", ) payload["client_request_id"] = uuid4().hex # Keep this value for retries of this job. print("client_request_id:", payload["client_request_id"]) video = client.generate_video(payload, poll_interval=5, timeout=600) client.download(video["video_url"], Path("result.mp4")) print("saved result.mp4") ``` `generate_video()` submits and polls, raises an error on `failed`, and stops waiting after 600 seconds. A timeout does not cancel the server job. Keep the printed `client_request_id` for a retry of the same submission; rerunning the whole example creates a new ID and can create another charged job. Download successful results within the 7-day storage window. ## Related VisionStory API guides {#related-visionstory-api-guides} - [Read the overview](/guides/overview) for core resources, response envelopes, and model choices. - [Explore the API reference](/reference) for request schemas, parameters, and responses. - [Get an API key](https://developers.visionstory.ai/api-keys) when you are ready to run a real request. --- # "Avatar Management API: Create, List & Frame" The VisionStory Avatar Management API manages reusable character resources. Creating an avatar from a portrait returns an `avatar_id`, not a generated MP4. List your own avatars or the public library, create a custom avatar, and control how an owned avatar is framed in each supported aspect ratio. Use the resulting `avatar_id` in a separate talking-avatar video request. ## AI avatar API endpoints | Method | Path | What it does | |---|---|---| | `GET` | `/api/v1/avatars` | List either owned avatars or the public library, with cursor pagination | | `POST` | `/api/v1/avatar` | Create a custom avatar from an image | | `POST` | `/api/v1/avatar/framing` | Update one aspect ratio's framing for an owned avatar | | `DELETE` | `/api/v1/avatar` | Delete one of your custom avatars | ## List owned or public avatars Each request returns one collection. By default, `GET /api/v1/avatars` lists avatars owned by the authenticated account. Set `is_public=true` to list the public library instead. Results are newest first and use cursor pagination: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/avatars?is_public=false&limit=20" ``` ```python import os import requests headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]} params = {"is_public": False, "limit": 20} while True: response = requests.get( "https://openapi.visionstory.ai/api/v1/avatars", headers=headers, params=params, timeout=10, ) data = response.json()["data"] for avatar in data["avatars"]: print(avatar["avatar_id"], avatar["default_voice_id"]) if not data["next_cursor"]: break params["cursor"] = data["next_cursor"] ``` The response shape is `{ "avatars": [...], "next_cursor": 0 }`; `next_cursor=0` means there are no more pages. `limit` accepts 1–100 and defaults to 20. Owned avatars include their real `created_at` and a three-entry `framing` array ordered `9:16`, `16:9`, `1:1`. Public avatars always return `framing: null`. Always choose an `avatar_id` from this endpoint instead of hardcoding one. To use the avatar's configured voice, copy its non-empty `default_voice_id` into `text_script.voice_id`. ## Create an AI avatar from a photo Send one portrait image, get back an `avatar_id`. Provide the image as either a public HTTPS URL or base64 `inline_data` — exactly one of the two: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"img_url": "https://your.site/portrait.jpg"}' https://openapi.visionstory.ai/api/v1/avatar ``` With a local file, base64-encode it into `inline_data`: ```python import base64 import os import requests headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]} with open("/path/to/image.jpg", "rb") as f: encoded = base64.b64encode(f.read()).decode("utf-8") payload = {"inline_data": {"mime_type": "image/jpg", "data": encoded}} response = requests.post("https://openapi.visionstory.ai/api/v1/avatar", json=payload, headers=headers) print(response.json()["data"]["avatar_id"]) ``` Store the returned `avatar_id` — you will pass it to every video request that should feature this avatar. Creation also returns `default_voice_id`; copy a non-empty value into `text_script.voice_id` to use the avatar’s preset voice. If it is empty, select a voice from `GET /api/v1/voices`. **Photo requirements:** use a single, clear, front-facing portrait for best results. Supported formats are JPEG, PNG, WEBP, and HEIC, up to 10 MB. ## Adjust avatar framing Owned avatars expose current framing for all three aspect ratios. Start with the values returned by `GET /api/v1/avatars`, change one ratio at a time, and send all five required fields: ```bash curl -s -X POST -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"avatar_id":"YOUR_AVATAR_ID","aspect_ratio":"9:16","zoom":1.2,"offset_x":0,"offset_y":-0.25}' https://openapi.visionstory.ai/api/v1/avatar/framing ``` `zoom=1` uses the widest frame that fits the selected aspect ratio; larger values move closer. `offset_x` and `offset_y` range from `-1` to `1`, where `0` is centered. The API keeps the frame inside the source image, verifies that it contains a visible face, saves it, and uses it for later videos in that aspect ratio. Only avatars owned by the account can be reframed. Older avatars without source-image dimensions may return `framing_unavailable`. A source image that is too small for one aspect ratio returns `zoom`, `offset_x`, and `offset_y` as `null` for that ratio; its `image_url` remains available and other ratios may still be adjustable. Check each ratio before writing framing back. If a requested zoom makes the crop too small, the `400` response includes `max_zoom` in its details. When `max_zoom` is null, create the avatar again with a larger source image or choose a ratio with non-null framing values. ## Use an avatar in a talking video Pass the `avatar_id` when creating a video: ```json { "model_id": "vs_character_v4", "avatar_id": "YOUR_AVATAR_ID", "text_script": { "text": "Hello!", "voice_id": "YOUR_VOICE_ID" } } ``` See the [Quick start](/guides/quick-start) for the full generate-poll-download flow. ## Delete a custom avatar Deleting only affects your own custom avatars; videos already generated with it are unaffected: ```bash curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/avatar?avatar_id=YOUR_AVATAR_ID" ``` ## Related VisionStory API guides - [Voices](/guides/voices) — pick or clone the voice your avatar speaks with. - [Quick start](/guides/quick-start) — generate your first video. - [Avatar API reference](/reference/avatars/update-avatar-framing) — inspect exact framing fields, bounds, responses, and error details. - [API reference](/reference) — full request and response schemas. --- # Voice Cloning API The VisionStory Voice Cloning API turns an audio sample into a reusable `voice_id`. Choose a public voice or clone your own, then use it for text-to-speech and lip-synced talking-avatar video generation. ## Voice cloning API endpoints | Method | Path | What it does | |---|---|---| | `GET` | `/api/v1/voices` | List public voices and your cloned voices | | `POST` | `/api/v1/voice` | Clone a voice from an audio sample | | `DELETE` | `/api/v1/voice` | Delete one of your cloned voices | ## List public and cloned voices The list response has two groups: `public_voices` and `my_voices`. Each voice includes a machine-readable BCP 47 `locale`, a human-readable `language`, and structured `provider`, `gender`, `age`, `accent`, and `use_cases` fields plus a preview URL. The legacy `tags` field remains available for compatibility. Filter the public library by `locale` and provider, then paginate with `limit` and the returned `next_cursor`. A base locale such as `es` matches every Spanish regional variant; a full locale such as `es-MX`, `en-GB`, `zh-TW`, or `zh-HK` matches that region: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \ "https://openapi.visionstory.ai/api/v1/voices?locale=es-MX&provider=minimax&limit=50" ``` ```python import os import requests headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]} response = requests.get( "https://openapi.visionstory.ai/api/v1/voices", headers=headers, params={"locale": "es-MX", "provider": "minimax", "limit": 50}, timeout=10, ) resp_data = response.json() print(len(resp_data["data"]["public_voices"])) print(len(resp_data["data"]["my_voices"])) print(resp_data["data"]["next_cursor"]) ``` Without `limit`, the endpoint keeps the original behavior and returns the complete filtered library. During pagination, `my_voices` appears on the first page only. `locale` and `provider` matching is case-insensitive. Always use a returned `voice_id` instead of inventing one. ## Clone an AI voice from audio Send an audio sample of the voice, get back a `voice_id`. Provide the audio as either a public HTTPS URL or base64 `inline_data` — exactly one of the two. The optional `preview_text` is synthesized with the new voice so you can hear the result immediately. The request is synchronous and takes about 15 seconds: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"audio_url": "https://your.site/sample.mp3", "preview_text": "How are you doing guys, this is my voice"}' https://openapi.visionstory.ai/api/v1/voice ``` With a local file, base64-encode it into `inline_data`: ```python import base64 import os import requests headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]} with open("/path/to/audio.mp3", "rb") as f: encoded = base64.b64encode(f.read()).decode("utf-8") payload = { "inline_data": {"mime_type": "audio/mp3", "data": encoded}, "preview_text": "How are you doing guys, this is my voice" } response = requests.post("https://openapi.visionstory.ai/api/v1/voice", json=payload, headers=headers) # takes ~15 s voice = response.json()["data"] print(voice["voice_id"], voice["locale"], voice["gender"], voice["preview_audio_url"]) ``` After cloning, listen to the returned `preview_audio_url` to check the result. Keep the corresponding `voice_id` and pass it to [Text to Speech](/guides/text-to-speech) for an audio file, or use it in a [talking-avatar video](/guides/quick-start). The preview URL is for listening; `voice_id` selects the voice in subsequent requests. **Sample requirements:** provide a clean recording of a single speaker. Supported formats are AVI, MP3, MP4, M4A, and WAV, up to 30 MB. How many cloned voices you can keep at once depends on your subscription plan. ## Use a cloned voice in a video Two places a voice applies when creating a video: **Text script** — the voice reads your text: ```json { "model_id": "vs_character_v4", "avatar_id": "YOUR_AVATAR_ID", "text_script": { "text": "Hello!", "voice_id": "YOUR_VOICE_ID", "speech_rate": "normal" } } ``` **Audio script with voice change** — you supply the audio, and `voice_change: true` re-voices it with the selected `voice_id`: ```json { "model_id": "vs_character_v4", "avatar_id": "YOUR_AVATAR_ID", "audio_script": { "audio_url": "https://your.site/narration.mp3", "voice_change": true, "voice_id": "YOUR_VOICE_ID", "denoise": true } } ``` ## Delete a custom voice Deleting only affects your own cloned voices; videos already generated with it are unaffected: ```bash curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/voice?voice_id=YOUR_VOICE_ID" ``` ## Related VisionStory API guides - [Avatars](/guides/avatars) — the character that speaks with your voice. - [Quick start](/guides/quick-start) — generate your first video. - [Text to Speech](/guides/text-to-speech) — steer multilingual pronunciation with `locale`. - [API reference](/reference) — full request and response schemas. --- # AI Video Generation API The VisionStory AI Video Generation API creates text-to-video, image-to-video, and reference-guided clips with V-Character 5.0 Pro, Seedance, Wan, and Kling models. Use the same API key to discover models, estimate credits, submit jobs, reuse media assets, poll status, and download results. Choose the video API for your task: | API | Use it for | |---|---| | `/api/v1/video` | A talking avatar speaking a text or audio script; follow the [Quick start](/guides/quick-start) | | `/api/v1/ai_video` | Clips driven by a prompt, images, or reference media; follow this guide | > **Beta.** Any API key backed by an active Pro plan or above can call these endpoints. No separate capability allowlist is required. ## AI video API endpoints | Method | Path | What it does | |---|---|---| | `GET` | `/api/v1/ai_video/models` | Machine-readable capability sheet for every model | | `GET` | `/api/v1/ai_video/cost` | Exact credit cost of a task before you submit it | | `POST` | `/api/v1/ai_video` | Submit a generation task | | `GET` | `/api/v1/ai_video` | Query one task (or up to 20 with `video_ids`) | | `GET` | `/api/v1/ai_videos` | List your tasks, newest first | | `DELETE` | `/api/v1/ai_video` | Delete a task | | `POST` | `/api/v1/asset` | Upload a reusable media asset | | `GET` | `/api/v1/assets` | List your assets | | `DELETE` | `/api/v1/asset` | Delete an asset | ## Generate an AI video Submit a text-to-video task, then poll until it finishes: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "seedance-2.0", "prompt": "A corgi surfing at sunset, cinematic lighting", "duration_sec": 8, "aspect_ratio": "9:16", "resolution": "1080p"}' https://openapi.visionstory.ai/api/v1/ai_video ``` ```json { "data": { "video_id": "YOUR_AI_VIDEO_ID", "status": "queued", "cost_credit": 64 } } ``` Poll every 5–10 seconds: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/ai_video?video_id=YOUR_AI_VIDEO_ID" ``` ## AI video models and capabilities `GET /api/v1/ai_video/models` returns allowed values and defaults for each parameter, plus media constraints. **Always drive your integration from this endpoint** — new models and parameter values appear there without any API change. | model_id | Best for | Resolution | Duration | Capabilities | |---|---|---|---|---| | `vs_character_v5_pro` | Mixed references and video editing | 720p / 1080p / 2k | 4–15 s or `auto` with video/audio refs | text-to-video, image-to-video | | `kling-4.0` | Audio with image/video references | 720p / 1080p | 3–30 s, integer | text-to-video, image-to-video | | `seedance-2.5` | Up to 50 multimodal references, single clips up to 30 s | 480p / 720p / 1080p | 4–30 s | text-to-video, image-to-video | | `seedance-2.5-flash` | Flash variant with up to 20 multimodal references | 480p / 720p | 4–30 s | text-to-video, image-to-video | | `seedance-2.0` | Flagship quality, multimodal references | 480p / 720p / 1080p | 4–15 s | text-to-video, image-to-video | | `seedance-2.0-fast` | Lower latency and cost | 480p / 720p | 4–15 s | text-to-video, image-to-video | | `seedance-2.0-mini` | Lightweight, most economical | 480p / 720p | 4–15 s | text-to-video, image-to-video | | `wan-3.0` | Multimodal references | 480p / 720p / 1080p | 2–30 s, integer | text-to-video, image-to-video | | `wan-3.0-prime` | Higher-priced Wan variant | 480p / 720p / 1080p | 2–30 s, integer | text-to-video, image-to-video | | `kling-3.0` | Up to 4K output | 720p / 1080p / 4k | 5 or 10 s | text-to-video, image-to-video; no refs | | `kling-3.0-omni` | Image/video references | 720p / 1080p | 3, 5, 7, 10, or 15 s | text-to-video with refs; no first_frame | Read each model's allowed aspect ratios, defaults, and reference limits from discovery. Wan supports `adaptive` and prompts up to 20000 characters; Seedance and V-Character 5.0 Pro support up to 5000, Kling 4.0 up to 11000, and Kling 3.0 / Omni up to 2500. Resolution defaults to 720p except Kling 3.0 Omni (1080p). Seedance 2.5 defaults to 15 seconds; Seedance 2.5 Flash and the Seedance 2.0 series default to 5 seconds. Flash defaults to aspect ratio `9:16` and supports `adaptive`. V-Character 5.0 Pro defaults to 10 seconds and aspect ratio `auto`; Kling 4.0 defaults to 5 seconds. Native audio defaults to on; Kling 4.0 rejects `generate_audio=false` at submission and quote time. The Seedance 5000-character limit is the API's validation limit, not a recommended prompt length. Keep each shot concise: preferably no more than 500 Chinese characters or 1000 English words. Longer prompts can dilute the focus and lose details. Read the live model catalog before submitting. **480p applies to Seedance and Wan AI video only.** It is not available for Kling or new talking-avatar requests. Historical talking-avatar responses can still contain 480p. ## Estimate AI video credits and cost Generation is billed in credits, charged at submit time and **automatically refunded in full if generation fails**. Cost depends on model, resolution, and duration (per second). Query the cost endpoint before submitting — it applies exactly the same formula as billing: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/ai_video/cost?model_id=seedance-2.0&duration_sec=8&resolution=1080p" ``` ```json { "data": { "credit": 64, "base_credit": 64, "reference_video": null } } ``` `generate_audio` does not change the credit price. Reference-video billing depends on the model: - All Seedance models (2.0, Fast, Mini, 2.5, and Flash) and Kling 4.0 include reference-video seconds up to half the output duration for free. Only excess seconds cost 60% of the output second rate. Sum reference durations, capping each video at 15 seconds for the Seedance 2.0 series or 30 seconds for Seedance 2.5 / Flash and Kling 4.0; round the combined generation and reference cost up once. Fractional per-second rates are supported; final charges and refunds remain integers. - V-Character 5.0 Pro doubles the generation second rate once when any video reference is present. Images and audio do not add charges; multiple videos do not multiply the rate again. Billing uses the ceiling of the resolved generation duration. `base_credit=credit` and `reference_video=null` for this model. - Other references do not add charges. Pass optional `reference_video_duration_sec` (a nonnegative number, default 0) to the [cost endpoint](/reference/ai-videos/get-ai-video-cost). For V5 Pro, any positive value selects video-reference pricing. For `auto` or video editing, pass the resolved reference duration as numeric `duration_sec`, including fractional seconds (2–15 seconds); do not send `auto` to the quote endpoint. Submission measures references server-side and returns the actual charge. Quotes return total `credit`, generation `base_credit` rounded up, and optional `reference_video` details (`duration_sec`, `free_duration_sec`, `excess_duration_sec`, `unit_cost`, `cost_credit`). The reference surcharge is the rounded total minus `base_credit`, so the fee details always add up to `credit`. ```bash visionstory ai-video-cost --model-id kling-4.0 --duration-sec 10 --resolution 720p --reference-video-duration-sec 8 ``` Current per-second rates include: | Model | 480p | 720p | 1080p | 4k | |---|---|---|---|---| | V-Character 5.0 Pro | — | 1 (2 with video) | 2 (4 with video) | — | | Kling 4.0 | — | 2 | 4 | — | | Seedance 2.5 | 3 | 6 | 15 | — | | Seedance 2.5 Flash | 2 | 5 | — | — | | Seedance 2.0 | 2 | 3 | 8 | — | | Seedance 2.0 Fast | 0.75 | 1.5 | — | — | | Seedance 2.0 Mini | 0.5 | 1 | — | — | | Wan 3.0 | 1 | 2 | 5 | — | | Wan 3.0 Prime | 2 | 3 | 7 | — | | Kling 3.0 | — | 2 | 3 | 8 | | Kling 3.0 Omni | — | 2 | 3 | — | V-Character 5.0 Pro also supports 2k at 4 credits/s, or 8 with video references. Use the cost endpoint for the current quote rather than caching this table indefinitely. Check your remaining balance with `GET /api/v1/billing/credits`. ## Image, video, and audio inputs Every media slot (`first_frame`, `end_frame`, `refs[]`) accepts **exactly one** of three forms: | Form | Example | Use when | |---|---|---| | `url` | `{"url": "https://your.site/img.jpg"}` | One-off use; fetched by our servers, not added to your asset library | | `inline_data` | `{"inline_data": {"mime_type": "image/png", "data": ""}}` | One-off use, no public URL available | | `asset_id` | `{"asset_id": "YOUR_ASSET_ID"}` | Reused materials — upload once via the Assets API, reference many times | The following media limits describe Seedance inputs. The 2.5 series supports longer references and additional image formats; check the selected model in [model discovery](/reference/ai-videos/get-ai-video-models). Wan and Kling have their own limits. | Kind | Max size | Formats | Constraints | |---|---|---|---| | Image | 30 MB | jpg, jpeg, png, webp, bmp, tiff, gif; heic / heif for 2.5 / Flash | 300–6000 px per side, aspect ratio between 1:2.5 and 2.5:1 | | Video | 100 MB | mp4, mov | 2–15 s for the 2.0 series, 2–30 s for 2.5 / Flash; 300–6000 px, aspect ratio 1:2.5–2.5:1; frame rate is normalized server-side | | Audio | 15 MB | wav, mp3 | 2–15 s for the 2.0 series, 2–30 s for 2.5 / Flash; cannot be the only reference | ## Configure an AI video request `POST /api/v1/ai_video` has two modes on one endpoint: provide `first_frame` (optionally `end_frame`) for **image-to-video**, provide `refs` for **reference-guided** text-to-video (character consistency, style, motion, or voice references), or provide neither for pure text-to-video. `refs` and `first_frame` are mutually exclusive. Unknown fields and unsupported values are rejected — nothing is silently ignored. | Field | Required | Description | |---|---|---| | `model_id` | yes | See Models above | | `prompt` | yes | Text prompt, up to 20000 characters for Wan, 5000 for Seedance / V5 Pro, 11000 for Kling 4.0, and 2500 for Kling 3.0 / Omni | | `client_request_id` | no | Idempotency key; resubmitting the same value within 24h returns the original task instead of charging again | | `duration_sec` | no | Integer seconds or `auto` for V5 Pro with video/audio references; omission uses the model default | | `aspect_ratio` | no | Defaults to the model default | | `resolution` | no | Defaults to the model default | | `generate_audio` | no | Native audio on the output; default `true` | | `first_frame` | no | Image media object; switches to image-to-video | | `end_frame` | no | Image for the last frame; requires `first_frame` | | `refs` | no | Model-specific: check `refs.max`, `refs.max_per_kind`, and `refs.total_duration_sec_max` | ### Model-specific input combinations - Seedance 2.5: up to 30 image / 10 video / 10 audio references, at most 50 total. Flash: up to 10 image / 5 video / 5 audio references, at most 20 total. Both accept 2–30-second video/audio references; video and audio each total at most 30 seconds, measured separately. - Seedance 2.0 / Fast / Mini: up to 9 image / 3 video / 3 audio references, subject to 9 total. Each video/audio reference is 2–15 seconds; each kind totals at most 15 seconds. - V-Character 5.0 Pro: mixed references accept up to 9 images, 3 videos, and 3 audio files, with at most 12 references total. Each video/audio reference must be 2–15 seconds, and each kind totals at most 15 seconds. Ordered image references are reference-guided generation, not implicit first/end frames. Explicit `first_frame` and optional `end_frame` remain supported. Aspect ratios are `auto`, `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, and `9:21`. `auto` requires video/audio refs; with a video it uses the video duration. Video editing is inferred from the prompt intent with one video and a compatible duration, uses `min(requested, video)` seconds and preserves original audio. - Kling 4.0: up to 10 image and 5 video references, at most 15 total; each video is 3–30 seconds and the video total cannot exceed 30 seconds. Use `@image_1`…`@image_10` and `@video_1`…`@video_5` in the prompt, numbered separately by type in input order. Image-to-video follows the first frame's aspect ratio; native audio is always on, including with video references. - Wan: up to 10 image, 5 video, and 5 audio references, also subject to the discovered total limit. Video and audio reference durations are each limited to 15 seconds in total; an individual longer reference is clipped to its first 15 seconds. Exceeding the aggregate limit returns `37104`. Combining `refs` with an explicit `aspect_ratio` returns 400. - Kling 3.0: `refs.max=0`; image-to-video accepts `first_frame`, but an explicit `aspect_ratio` in that mode returns 400. - Kling 3.0 Omni: no `first_frame`; up to 7 image/video references, at most 1 video, with video references totaling at most 15 seconds. More than 1 video is rejected before charging. If refs contain video, set `generate_audio=false`; otherwise the request returns 400. - Use `first_frame` only when discovery declares image-to-video support. Always keep `first_frame` and `refs` mutually exclusive; `end_frame` requires `first_frame`. Image-to-video with first and last frame: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "seedance-2.0", "prompt": "The scene slowly comes alive, gentle camera push-in", "first_frame": {"url": "https://your.site/start.jpg"}, "end_frame": {"url": "https://your.site/end.jpg"}, "duration_sec": 6}' https://openapi.visionstory.ai/api/v1/ai_video ``` Character-consistent generation with a reusable asset: ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "seedance-2.0", "prompt": "The same woman walks through a neon-lit street at night", "refs": [{"asset_id": "YOUR_ASSET_ID"}], "duration_sec": 10}' https://openapi.visionstory.ai/api/v1/ai_video ``` ## Poll AI video generation status Query one task with `?video_id=`, or up to 20 at once with `?video_ids=id1,id2,...` (batch responses return `{"videos": [...]}`). Poll every 5–10 seconds. | status | Meaning | |---|---| | `queued` | Accepted, waiting for a worker | | `creating` | Generating | | `created` | Done — `video_url` and `cover_url` are ready | | `failed` | Generation failed — see `error`; credits were refunded automatically | Seedance moderation is asynchronous: a rejected task resolves to `failed` and is refunded. Wan and Kling can reject content synchronously with HTTP 403 and code `37110` (prompt) or `37111` (image), without charging. Always handle both submission errors and the `failed` task state. Failed generation refunds credits in full. The API does not automatically switch to a different model after failure; returned `model_id` identifies the actual model. ## List and delete AI videos `GET /api/v1/ai_videos` lists your tasks, newest first. Pass `cursor` from the previous page's `next_cursor` to paginate; `next_cursor=0` means no more pages. `limit` defaults to 20 (max 100). `DELETE /api/v1/ai_video?video_id=` deletes a task — only your own. Use the optional `status` query parameter to filter by one or more comma-separated values: `queued`, `creating`, `created`, or `failed`. Omitting it keeps the existing unfiltered behavior; an unknown status returns HTTP 400. ### Check AI video concurrency before submitting Query [in-flight AI video tasks](/reference/ai-videos/get-ai-videos) with `status=queued,creating`: ```bash visionstory ai-videos --status queued,creating --limit 100 ``` ```python page = client.list_ai_videos(status="queued,creating", limit=100) print(page) ``` Follow `next_cursor` until it is 0 when counting tasks; a single page can undercount. The list shows current usage, not the configured limit, and does not reserve a slot. A concurrency rejection returns HTTP 429 with `error.details.limit` and `error.details.in_flight`. Wait for an in-flight task to finish, refresh the list, then retry with the same `client_request_id`. Other rate-limit errors may not include these concurrency fields. **Error-schema compatibility:** the shared error schema currently declares `details` as a nullable string, while concurrency errors are documented with an object. When reading concurrency metadata, accept an object or parse a JSON-encoded string; do not assume every 429 includes these fields. ## Reuse media with the Assets API An asset is a reusable uploaded material: upload once, reference by `asset_id` in any number of generation requests — ideal for a recurring character image, brand footage, or a voice sample. Re-uploading identical content returns the existing asset (idempotent): ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"url": "https://your.site/character.jpg"}' https://openapi.visionstory.ai/api/v1/asset ``` ```json { "data": { "asset_id": "YOUR_ASSET_ID", "kind": "image", "mime": "image/jpeg", "width": 1024, "height": 1536, "duration_sec": 0, "created_at": 1754270000 } } ``` `inline_data` (base64) is also accepted; size and format limits match Media inputs above. `GET /api/v1/assets` lists your assets (filter by `kind`, paginate with `cursor` / `limit`). `DELETE /api/v1/asset?asset_id=` deletes an asset — videos already generated from it are not affected. ## AI video API errors | HTTP | error.code | Meaning | |---|---|---| | 401 | — | Missing or invalid API key | | 403 | 30610 | Active subscription required | | 403 | 30309 | Insufficient paid credits for external models; reward credits cannot be used | | 403 | 30308 | Insufficient paid plus signup credits for V-Character 5.0 Pro | | 403 | 37101 | Invalid input — parameter or media constraint violation | | 403 | 37102 | Prompt too long | | 403 | 37103 | Too many references | | 403 | 37104 | Reference duration total exceeded | | 403 | 37110 / 37111 | Wan/Kling prompt or image moderation rejection; not charged | | 400 | 400 | Rejected by the gateway (unknown model_id, media too large or unsupported, invalid asset_id) | | 422 | — | Malformed request body (unknown fields, missing required fields, invalid combinations) | | 404 | — | Video or asset not found | | 429 | — | Rate limited | Asynchronous failures (moderation, provider errors) never use HTTP errors — the task resolves to `status=failed` with an `error` object, and credits are refunded automatically. Successful delivery is reported only after the generated video is stored. Temporary delivery problems retry the same task; exhausted delivery retries fail with `37007` and a full refund. Keep polling the original task instead of creating another. ## Rate limits, storage, and idempotency - **Concurrency:** the in-flight quota is shared per account across all its API keys, with a default of 3 tasks; the configured limit can differ. Excess requests are rejected, not queued. Read `error.details.limit` and `error.details.in_flight` on 429. - **Rate limit:** 180 requests per 60 seconds per account. Use batch query (`video_ids`) and poll at 5–10 s intervals. - **Storage:** download `video_url` promptly if you need long-term storage. Assets stay available until you delete them. - **Idempotency:** pass a `client_request_id` on submit to make retries safe — resubmitting the same value within 24h returns the original task instead of creating (and charging) a new one. Without it, store the returned `video_id` before retrying, since a network-level retry of a successful submit creates (and charges) a new task. - **Webhooks** are not available yet; polling is the supported integration pattern. - The beta surface may gain new optional parameters and models over time; existing fields and semantics will not change incompatibly. ## Related VisionStory API guides - [Quick start](/guides/quick-start) — the talking-avatar flow with the same key. - [For agents](/guides/for-agents) — drive AI video generation from an AI agent. - [API reference](/reference) — full schemas for every endpoint above. --- # Text-to-Speech API The VisionStory Text-to-Speech API converts text into natural MP3 audio with any public or cloned voice. The request is synchronous: a successful response returns the generated audio bytes directly. > **Beta.** Any API key backed by an active Pro plan or above can call this endpoint. No separate capability allowlist is required. ## Text-to-speech API endpoint | Method | Path | What it does | |---|---|---| | `POST` | `/api/v1/tts` | Synthesize speech from text; returns MP3 audio | ## Generate MP3 speech from text Send `text` and a `voice_id` from `GET /api/v1/voices`. Add an optional BCP 47 `locale`, such as `en-GB` or `zh-TW`, to steer pronunciation and accent for multilingual voices. Locale handling is best-effort per speech engine; omit it to use the voice's native locale. ```bash curl -s -X POST -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"text": "Hello from VisionStory.", "voice_id": "YOUR_VOICE_ID", "locale": "en-GB"}' https://openapi.visionstory.ai/api/v1/tts --output speech.mp3 ``` The response body is the raw MP3 (`audio/mpeg`, 44.1 kHz). Usage and billing come back in **response headers**, not the body: | Header | Meaning | |---|---| | `X-Audio-Duration-Sec` | Length of the generated audio, in seconds | | `X-Usage-Characters` | Characters billed | | `X-Cost-Credit` | Credits charged for this call | ```python import requests, os resp = requests.post( "https://openapi.visionstory.ai/api/v1/tts", headers={"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}, json={"text": "Hello from VisionStory.", "voice_id": "YOUR_VOICE_ID", "locale": "en-GB"}, timeout=240, ) resp.raise_for_status() with open("speech.mp3", "wb") as f: f.write(resp.content) print("credits charged:", resp.headers.get("X-Cost-Credit")) ``` ## Control speech rate The optional `speech_rate` accepts `slow`, `normal`, or `fast`. Omit it or send `null` to use normal speed. The setting works with public and cloned voices, but the actual duration change depends on the voice; read `X-Audio-Duration-Sec` rather than assuming a fixed duration. Speed changes preserve pitch, and billing is unchanged. ```python from visionstory import VisionStoryClient from pathlib import Path speech = VisionStoryClient.from_env().create_speech( text="Hello from VisionStory.", voice_id="YOUR_VOICE_ID", locale="en-GB", speech_rate="slow", ) Path("speech.mp3").write_bytes(speech["audio"]) ``` ```bash visionstory tts --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --speech-rate slow --output speech.mp3 ``` Local and remote MCP expose the same optional `speech_rate` on `create_speech`. REST callers put it alongside `text`, `voice_id`, and `locale` in the JSON body. Existing calls that omit it keep working. ## Billing, limits, and storage - **Synchronous & not stored.** The audio is returned inline and is **not** saved on our side — persist the bytes yourself; a repeat call regenerates and bills again. - **Billing:** 2 credits per 1,000 characters (rounded up), charged only on success. There is no free allowance. - **Character limit:** long text is supported up to a per-request cap; exceeding it returns `400`. - **Concurrency:** synchronous generation is capped at a few concurrent requests per key during beta; excess requests are rejected rather than queued. ## Related VisionStory API guides - [Voices](/guides/voices) — pick or clone the `voice_id` to speak with. - [Audio Transcription and Alignment](/guides/audio-understanding) — align generated speech to exact word timestamps for subtitles. - [API reference](/reference) — full request schema and error codes. --- # Speech to Text and Alignment API The VisionStory Speech to Text API turns speech audio into text, subtitles, and precise word timing. Use transcription when you need speech-to-text, speaker labels, or SRT output. Use alignment when you already know the spoken script and need accurate timestamps for every word. For structured extraction from images, audio, or video, use [Media Understanding](/guides/media-understanding). Both endpoints are synchronous, accept WAV or MP3 audio up to 15 MB, and charge 1 credit per started 5 minutes only when processing succeeds. An active Pro plan or above is required; no separate beta allowlist is needed. ## Audio transcription and alignment endpoints | Method | Path | Use it for | |---|---|---| | `POST` | `/api/v1/audio/transcribe` | Speech-to-text with optional speaker diarization and SRT subtitles | | `POST` | `/api/v1/audio/align` | Word-level timing when the exact spoken text is already known | Each request accepts exactly one audio source inside `audio`: a reusable `asset_id`, a public `url`, or base64 `inline_data`. ## Transcribe audio to text Set `diarize: true` to label speaker turns and `srt: true` to include a ready-to-save subtitle track. The flags are independent: `srt: true` works without `diarize: true`, and speaker labels are omitted unless you explicitly request diarization. ```bash curl -s -X POST \ -H "X-API-Key: $VISIONSTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"audio":{"url":"https://example.com/interview.mp3"},"diarize":true,"srt":true}' \ https://openapi.visionstory.ai/api/v1/audio/transcribe ``` The response contains the full transcript, detected language, word timestamps, optional `speaker` labels, optional SRT, duration, and credits charged: ```json { "data": { "text": "Welcome to VisionStory.", "language": "en", "words": [ { "text": "Welcome", "start_sec": 0.0, "end_sec": 0.48, "speaker": "speaker_0" } ], "srt": "1\n00:00:00,000 --> 00:00:01,200\nWelcome to VisionStory.", "duration_sec": 1.2, "cost_credit": 1 } } ``` With the Python SDK: ```python from pathlib import Path from visionstory import VisionStoryClient client = VisionStoryClient.from_env() transcript = client.transcribe_audio( audio_file=Path("interview.mp3"), diarize=True, srt=True, ) Path("interview.srt").write_text(transcript["srt"], encoding="utf-8") ``` ## Align a script with audio Alignment is useful after [text-to-speech generation](/guides/text-to-speech), dubbing, or voice-over production. Send the exact text spoken in the audio: ```bash curl -s -X POST \ -H "X-API-Key: $VISIONSTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"audio":{"asset_id":"YOUR_AUDIO_ASSET_ID"},"text":"Welcome to VisionStory."}' \ https://openapi.visionstory.ai/api/v1/audio/align ``` The response returns `words`, `duration_sec`, and `cost_credit`. Each word includes `text`, `start_sec`, and `end_sec`. ## Use the CLI or MCP ```bash visionstory transcribe --audio-file interview.mp3 --diarize --srt --output interview.srt visionstory align --audio-url https://example.com/speech.mp3 --text "Welcome to VisionStory." ``` MCP clients expose the same workflows as `transcribe_audio` and `align_audio`. The local stdio MCP accepts file paths, URLs, or asset IDs. The remote MCP accepts public URLs or reusable asset IDs because it cannot read files from your computer. ## Limits and billing - Audio input: WAV or MP3, up to 15 MB. - Processing: synchronous; use short audio where possible to avoid client or proxy timeouts. - Billing: 1 credit per started 5 minutes, charged only on success. - Concurrency: requests beyond the per-key synchronous limit are rejected rather than queued. - Reuse: upload frequently used audio through the Assets API and pass its `asset_id`. ## Related VisionStory API guides - [Text to Speech](/guides/text-to-speech) — generate MP3 speech, then align it for subtitles. - [Voices](/guides/voices) — filter public voices or clone a reusable voice. - [Python SDK](/guides/sdk) — call transcription and alignment from Python. - [API reference](/reference) — exact request and response schemas. --- # Structured Media Understanding API Use `POST /api/v1/media/understand` to extract structured data from media, such as a subject label, scene description, or fields for your application. Supply a prompt, media inputs, and your output JSON Schema. This is a synchronous API, not a video generation task: there is no task ID to poll, public model selector, or free-text response mode. ## Request parameters | Field | Required | Contract | |---|---|---| | `prompt` | Yes | String, 1–5000 characters | | `inputs` | Yes | Array of 1–8 media references | | `schema` | Yes | JSON Schema (supported 2020-12 subset) describing a top-level object | Each media reference supplies exactly one of `url` (publicly accessible), `asset_id` (an uploaded asset), or `inline_data` (`mime_type` and base64 `data`). Supported inline media includes JPEG, PNG, WebP, BMP, TIFF, GIF; WAV/MP3 audio; and MP4/MOV video. See the [request schema](/reference/media-understanding/understand-media) for precise MIME types. Do not send local file paths as URLs. ## Extract structured data with Python After [configuring authentication](/guides/sdk#authenticate-the-python-client), replace the example URL with your own accessible media. The SDK sets a 180-second timeout for this operation. ```python from visionstory import VisionStoryClient client = VisionStoryClient.from_env() result = client.understand_media( prompt="Identify the main subject in the image.", inputs=[{"url": "https://example.com/photo.jpg"}], schema={ "type": "object", "properties": {"subject": {"type": "string"}}, "required": ["subject"], "additionalProperties": False, }, ) print(result["output"]) print(result["usage"], result["cost_credit"]) ``` ## CLI and MCP The CLI accepts JSON for both `--inputs` and `--schema`: ```bash visionstory understand-media \ --prompt "Identify the main subject in the image." \ --inputs '[{"url":"https://example.com/photo.jpg"}]' \ --schema '{"type":"object","properties":{"subject":{"type":"string"}},"required":["subject"],"additionalProperties":false}' ``` Both local and remote MCP expose `understand_media` with `prompt`, `inputs`, and `schema`. Remote MCP accepts public URLs and asset IDs, not local paths or inline media. The local Agent Skill helper supports the same `understand-media` command as the CLI. ## Response, billing, and failure handling A successful REST response contains `data.output` (the structured object), `data.usage.input_tokens`, `data.usage.output_tokens`, and `data.cost_credit`. The SDK unwraps `data` automatically. This operation can take up to 180 seconds; allow sufficient time in the calling application or MCP client as well. Only successful requests are charged. Cost is based on token usage, converted at 1 credit per USD 0.10 and rounded up, with a minimum of 1 credit. There is a per-key concurrency limit; excess requests are rejected rather than queued. Content moderation can reject a request with code `37100`; it is uncharged, and unchanged input is likely to be refused again. Insufficient paid credits return `30309`, with `details.paid_credit_balance` and `details.credit_needed`; reward credits cannot pay for external models. Do not automatically repeat a timed-out request: the server may already have succeeded, and another successful call can incur another charge. Inspect the error before retrying. Never log API keys or base64 media. ## Related guides - [Speech to Text](/guides/audio-understanding) — use transcription for speech, SRT subtitles, and word timestamps. - [Assets API](/reference/assets/create-asset) — upload media once and reuse the returned `asset_id`. - [For agents](/guides/for-agents) — connect an MCP client or install the Agent Skill. --- # AI Image Generation API The VisionStory AI Image Generation API creates or edits images from text prompts and optional reference media. The synchronous response returns an image URL that you can download or pass directly into an image-to-video workflow. > **Beta.** Any API key backed by an active Pro plan or above can call this endpoint. No separate capability allowlist is required. ## AI image API endpoints | Method | Path | What it does | |---|---|---| | `GET` | `/api/v1/image/models` | List image models with sizes and per-image credit cost | | `POST` | `/api/v1/image` | Generate an image from a prompt (+ optional references) | ## List image generation models ```bash curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/image/models ``` Each model reports its aspect ratios, resolution choices and default, prompt-length limit, reference-image limit, and live pricing. `credit_per_image` is the base price at the default resolution; `credit_by_resolution` gives the base price for each supported resolution. `reference_pricing` describes any reference surcharge; null means none. Drive your integration from this endpoint rather than hardcoding capabilities or prices. | Model | Resolution | Prompt limit | Reference images | |---|---|---:|---:| | `nano-banana-2` | `1K` default; `1K` or `2K` | 5,000 characters | 14 | | `nano-banana-pro` | `1K` default; `1K` or `2K` | 5,000 characters | 14 | | `seedream-5.0-lite` | `2K` default; `2K` or `4K` | 3,000 characters | 14 | | `seedream-5.0-pro` | `1K` default; `1K` or `2K` | 3,000 characters | 10 | | `gpt-image-2.5-flare` | `1K` default; `1K` or `2K` | 5,000 characters | 6 | | `gpt-image-2.5-sunburst` | `1K` default; `1K` or `2K` | 5,000 characters | 6 | | `gpt-image-2` | `1K` default; `1K` or `2K` | 5,000 characters | 16 | All seven current models support `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, and `21:9`. Query [`GET /api/v1/image/models`](/reference/images/get-image-models) before every model-selection flow because availability, limits, defaults, and credit costs can change. GPT Image is available through the API. Flare favors faster generation, Sunburst targets precise edits with longer processing, and GPT Image 2 is the previous-generation option. Quality is fixed per model; there is no public quality parameter. GPT Image reference images accept PNG, JPEG (including MPO), and WebP; BMP, TIFF, GIF, and HEIC are converted to PNG by the service. Unreadable references return code `37101`. ## Generate or edit an AI image Send a `model_id` from the models endpoint and a `prompt`. You can add `refs` to guide style or subject, or to **edit** an image through prompt instructions without a mask. The accepted prompt length, resolution values, default resolution, and reference-image count all depend on the selected model. ```bash curl -s -X POST -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "seedream-5.0-lite", "prompt": "A red panda barista in a cozy cafe, warm lighting", "aspect_ratio": "1:1", "resolution": "2K"}' https://openapi.visionstory.ai/api/v1/image ``` ```json { "data": { "url": "https://cdn.visionstory.ai/example.png" } } ``` - **Aspect ratio:** use a value returned in `params.aspect_ratio.values`; the current default is `1:1`. - **Resolution:** use `params.resolution.values` and `params.resolution.default`. In particular, `seedream-5.0-lite` does not accept `1K`, while `seedream-5.0-pro` does not accept `4K`. - **Prompt:** stay within `params.prompt.max_length` for the selected model. - **References:** each entry uses `asset_id`, `url`, or `inline_data`; stay within the selected model's `params.refs.max`. - **Timeout:** any image model can take up to 180 seconds server-side. Allow at least 240 seconds; the SDK, CLI, local/remote MCP, and standalone Skill client enforce this minimum and preserve a longer configured timeout. After a provider timeout (`504` / `37008`) or provider failure (`502` / `37009`) response, retry once with the same parameters. Do not resubmit while the first request is pending or after an ambiguous client timeout: a completed request can still be billed. ## Use a generated image in a video The returned `url` is a normal image URL — pass it straight into other endpoints, e.g. as `first_frame` or `refs` for [AI Video](/guides/ai-video): ```json { "model_id": "seedance-2.0", "prompt": "the scene gently comes alive, slow camera push-in", "first_frame": { "url": "https://cdn.visionstory.ai/example.png" } } ``` ## Billing, limits, and storage - **Not stored by default.** The image is returned as a URL but **not** added to your asset library — upload it via `POST /api/v1/asset` if you want a reusable `asset_id`. - **Billing:** charged only on success, using `credit_by_resolution` as the base for the selected resolution. `credit_per_image` remains the default-resolution base price. GPT Image 2 includes the first 6 references and adds `ceil(max(0, ref_count - 6) / 3)` credits per output, up to 16 references. `reference_pricing` exposes `included_refs`, `refs_per_credit`, and `credit_per_step`; `cost_credit` includes the surcharge. Flare and Sunburst stay at 6 references with no surcharge. The current GPT Image examples show 2 credits for `1K` and 3 for `2K`; read live prices before submitting. Other current models have the same price across their supported resolutions. - **Validation:** an unsupported resolution returns HTTP 400; exceeding the selected model's reference limit returns HTTP 422. - **Failures:** failures happen before billing; use the errors below to decide whether to retry. - **Concurrency:** synchronous generation is capped at a few concurrent requests per key during beta; excess requests are rejected rather than queued. ## Image generation errors | HTTP | error.code | Meaning and action | |---|---|---| | 504 | 37008 | Generation timed out; `details.timeout_sec` reports the budget. No charge; retry the same parameters once after the response. | | 502 | 37009 | Model provider failure, including an empty image result. No charge; retry the same parameters once after the response. | | 403 | 37100 | Content refused; no charge. The same input is likely to be refused again. Optional `details.stage` is `input` or `output`. | | 403 | 30309 | Insufficient paid credits; reward credits cannot pay for images or external models. `details.paid_credit_balance` and `details.credit_needed` report the balance and requirement. | | 400 | 400 | Unsupported resolution or invalid inline base64; fix the input. | | 422 | — | Invalid request body or query; inspect the location and safe numeric limit details. | | 403 | 1 | Other program or provider errors; inspect the returned message and hint. | Error details can be objects despite the shared schema's nullable-string declaration. Preserve the response and handle both representations. ## Related VisionStory API guides - [AI Video](/guides/ai-video) — turn a generated image into video. - [`POST /api/v1/image`](/reference/images/create-image) — full request schema and error behavior. --- # VisionStory Python SDK 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 ```bash pip install visionstory ``` ## Discover new SDK features In an interactive Python session, the SDK checks the VisionStory release manifest using a 10-minute cache and displays an upgrade notice at most once per week when a newer version is available. The notice includes the latest version, release title, upgrade command, and [release notes](/guides/changelog). Update checks fail silently when you are offline and never change the installed package. Check explicitly in a notebook, server process, or CI job: ```python from visionstory import check_for_updates print(check_for_updates()) # installed_version, latest_version, update_available, highlights, update_command ``` Disable passive notices with `VISIONSTORY_UPDATE_CHECK=0`, or force the interactive notice behavior with `VISIONSTORY_UPDATE_CHECK=1`. The machine-readable release manifest is available at [`/releases/latest.json`](/releases/latest.json). ## Authenticate the Python client ### Default setup: use the official API For most applications, configure only `VISIONSTORY_API_KEY` and use `from_env()`. You do not need to set a domain or a timeout. Create a key on the [API keys page](/api-keys), then provide it through your application's environment or deployment secret store. Never put a real key in source code, chat, or a committed environment file. ```python from visionstory import VisionStoryClient client = VisionStoryClient.from_env() print(client.get_credits()) # Read-only authentication check; does not generate media ``` For a local test without a configured environment, run this in your own terminal before creating the client. Input stays hidden; the key is available only to this Python process, not future terminals: ```python import getpass import os os.environ["VISIONSTORY_API_KEY"] = getpass.getpass("VisionStory API key (hidden): ") ``` | Setting | Default behavior | How to customize | | --- | --- | --- | | API key | `from_env()` reads `VISIONSTORY_API_KEY`; a missing or empty key raises an error | Supply the environment variable or pass `api_key` to the constructor | | API address | `https://openapi.visionstory.ai` when `VISIONSTORY_API_BASE` is not set | Set `VISIONSTORY_API_BASE` for `from_env()`, or pass `base_url` to the constructor | | HTTP timeout | 60 seconds for requests without an operation-specific override | Pass `request_timeout` in seconds | > **SDK authentication is separate from CLI login.** `from_env()` reads the current process environment. It does not load `.env` files or credentials saved by `visionstory login`; your application must load or inject environment variables before creating the client. ### Custom setup: choose another API address Use this only for a trusted proxy, gateway, or test server that implements the VisionStory API. The simplest option is to change the environment and keep your Python code unchanged: ```bash # macOS / Linux / WSL shell; applies to this terminal and its child processes export VISIONSTORY_API_BASE="https://your-api.example.com" ``` ```python from visionstory import VisionStoryClient client = VisionStoryClient.from_env(request_timeout=120) ``` To return to the official API, remove the override (`unset VISIONSTORY_API_BASE` in the same shell), then create a new client. Do not set it to an empty string. For per-client settings, pass the values explicitly: ```python import os from visionstory import VisionStoryClient client = VisionStoryClient( api_key=os.environ["VISIONSTORY_API_KEY"], base_url="https://your-api.example.com", request_timeout=120, ) ``` **Configuration precedence:** `from_env()` reads both environment variables. The direct constructor uses its arguments and defaults; it does not read `VISIONSTORY_API_BASE`. If you omit `base_url` from the constructor, it uses the official address even when that environment variable is set. Changes to environment variables do not update an existing client. > **Use a trusted HTTPS address.** SDK requests send your key in the `X-API-Key` header to the configured server. Provide the base address without `/api/v1`: SDK methods append paths such as `/api/v1/models`. Changing the domain does not make an unrelated API compatible. `request_timeout` controls HTTP requests, not total video rendering time. Some operations use their own request timeout. Configure asynchronous waiting separately with `wait_for_video(..., timeout=600)`; downloads have their own `client.download(url, path, timeout=120)` setting. ## 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. Optional `prompt` supplies motion instructions for `vs_character_v4` with either script type (up to 2000 characters); omission, null, empty, or whitespace-only values retain existing behavior. Motion and timing are not guaranteed; `emotion` is not merged into the motion prompt. ## Use the VisionStory CLI A separate `visionstory-cli` package provides a `visionstory` command that covers the same surface — no code required: ```bash visionstory create-video --avatar-id YOUR_AVATAR_ID --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --output result.mp4 ``` See the [CLI](/guides/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(limit=20) # owned avatars client.list_avatars(is_public=True, limit=20) # public avatar library client.list_voices(locale="es-MX", provider="minimax", limit=50) 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=28 ``` 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 avatar = client.create_avatar(image_url="https://your.site/face.jpg") # or image_file=Path("face.jpg") client.update_avatar_framing( avatar_id=avatar["avatar_id"], aspect_ratio="9:16", zoom=1.2, offset_x=0, offset_y=-0.25, ) 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") ``` Avatar listing is cursor-paginated and returns one collection at a time. Omit `is_public` for avatars owned by the current account, or set `is_public=True` for the public library. Follow `next_cursor` with `cursor=` and choose a `limit` from 1 to 100. Only owned avatars can be reframed; read the avatar's current `framing` entries before updating one aspect ratio. `upload_asset` returns a reusable `asset_id` you can reference from [AI Video](/guides/ai-video) requests. ## Transcribe audio and create subtitles Transcribe WAV or MP3 audio from a local path, public URL, or reusable asset. Add `diarize=True` for speaker labels and `srt=True` for subtitle output: ```python from pathlib import Path transcript = client.transcribe_audio( audio_file=Path("interview.mp3"), diarize=True, srt=True, ) Path("interview.srt").write_text(transcript["srt"], encoding="utf-8") alignment = client.align_audio( text="Welcome to VisionStory.", asset_id="YOUR_AUDIO_ASSET_ID", ) ``` See [Audio Transcription and Alignment](/guides/audio-understanding) for request shapes, limits, word timestamps, and billing. ## Synthesize localized speech ```python speech = client.create_speech( text="Welcome to VisionStory.", voice_id="YOUR_VOICE_ID", locale="en-GB", ) Path("speech.mp3").write_bytes(speech["audio"]) ``` ## 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 ``` ## Related VisionStory developer guides - [Quick start](/guides/quick-start) — the same flow, step by step. - [For agents](/guides/for-agents) — let an AI agent drive the API via the Skill or MCP server. - [Audio Transcription and Alignment](/guides/audio-understanding) — speech-to-text, SRT, and forced alignment. - [API reference](/reference) — every endpoint the SDK wraps. ## Structured media extraction and speech rate Use `understand_media` for schema-constrained JSON from images, audio, or video. It takes required `prompt`, `inputs`, and `schema`, waits synchronously for up to 180 seconds, and returns `output`, `usage`, and `cost_credit`. ```python from visionstory import VisionStoryClient client = VisionStoryClient.from_env() result = client.understand_media( prompt="Identify the subject", inputs=[{"asset_id": "YOUR_ASSET_ID"}], schema={"type": "object", "properties": {"subject": {"type": "string"}}, "required": ["subject"]}, ) print(result["output"]) speech = client.create_speech(text="Hello", voice_id="YOUR_VOICE_ID", speech_rate="slow") # Save speech["audio"] as MP3. Omit speech_rate to keep normal speed. ``` `speech_rate` accepts `slow`, `normal`, or `fast`; `None` leaves the field out. See [Media Understanding](https://developers.visionstory.ai/guides/media-understanding) for input limits, billing, and timeout handling, and [Text to Speech](https://developers.visionstory.ai/guides/text-to-speech) for binary responses. ## Quote reference-guided AI videos `create_ai_video` and `generate_ai_video` accept the full request dictionary, including V-Character 5.0 Pro `duration_sec="auto"` with video/audio references, and Kling 4.0 inputs. Discover current limits with `list_ai_video_models`. Use numeric resolved duration for quotes; fractional seconds are accepted for V5 Pro auto/video editing: ```python quote = client.ai_video_cost( model_id="vs_character_v5_pro", duration_sec=6.5, resolution="720p", reference_video_duration_sec=6.5, ) print(quote) ``` `reference_video_duration_sec` defaults to 0. A positive value doubles V5 Pro generation rates once; all Seedance models (including 2.5 Flash) and Kling 4.0 charge excess reference seconds beyond half the output duration at 60% of the output rate. Quotes retain `credit` and add `base_credit` and optional `reference_video` details. See [AI video billing and inputs](/guides/ai-video). `create_image` preserves the complete response and uses a minimum 240-second timeout, including a longer configured timeout. Read [image generation](/guides/image-generation) for GPT Image 2 reference surcharges and retryable `37008` / `37009` provider responses. Never resend a pending request or blindly retry an ambiguous client timeout. --- # 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](/guides/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: ```bash 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: ```bash 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: ```bash pip install visionstory-cli ``` Confirm it's on your PATH: ```bash 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: ```bash 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](https://developers.visionstory.ai/api-keys), then rerun `visionstory login`. ## Check, update, diagnose, or uninstall the CLI These local commands do not require an API key: ```bash visionstory --version visionstory login visionstory logout visionstory update --check visionstory update visionstory doctor visionstory uninstall ``` | Command | What it does | |---|---| | `visionstory --version` | Prints the installed version in one line | | `visionstory version` | Prints the installed version as JSON for scripts | | `visionstory login` | Securely prompts for, verifies, and saves an API key | | `visionstory logout` | Removes the API key saved by `visionstory login` | | `visionstory update --check` | Checks PyPI without changing the installation | | `visionstory update` | Upgrades with the same `uv tool` or `pip` installation method currently in use | | `visionstory doctor` | Shows the executable, Python version, install method, API URL, and whether an API key is configured; it never prints the key | | `visionstory uninstall` | Requests confirmation, then removes the CLI | `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: ```bash # 1. Sign in once (skip this if you already completed it) visionstory login # 2. Discover a public avatar and voice visionstory avatars --is-public 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. Before normal commands run, the CLI checks the shared VisionStory release manifest using a 10-minute cache and a one-second network timeout. When a newer version is available and stdin, stdout, and stderr are all interactive terminals, it shows the installed and latest versions, a [release notes](/guides/changelog) link, and three choices: | Choice | Behavior | |---|---| | `1) Update now` (default) | Press Enter or `1` to confirm an upgrade using the current uv or pip installation method. Installer progress goes to stderr. | | `2) Later — remind me in 4 hours` | Run the original command and pause prompts for this version for four hours. A newer release can still prompt. | | `3) Skip this version` | Run the original command and suppress prompts for this version. The next release can still prompt. | After an upgrade, the CLI exits and asks you to run the original command again with the new version. A failed or cancelled upgrade does not run that command. The menu shows no feature summary. Login, logout, update, uninstall, `--help`, and `--version` do not open the upgrade menu. CI and redirected streams never open an upgrade menu. Passive notices use stderr, leaving JSON stdout unchanged. Offline failures are silent and retried after ten minutes; no package is installed without user confirmation. Existing installations must be upgraded once to receive this behavior. 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: ```bash 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. | Setting | Default | Override | | --- | --- | --- | | API address | `https://openapi.visionstory.ai` | `--base-url` or `VISIONSTORY_API_BASE` | | API key | Key saved by `visionstory login` | `VISIONSTORY_API_KEY` takes precedence over the saved key | | HTTP timeout | 60 seconds for requests without an operation-specific override | Global `--request-timeout`, in seconds | 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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`: ```bash 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 | Command | What it returns | |---|---| | `visionstory models` | Talking-avatar render models | | `visionstory avatars` | Owned avatars by default; add `--is-public` for the public library (`--cursor`, `--limit`) | | `visionstory voices` | Your voices plus public ones | | `visionstory credits` | Remaining credit balance | | `visionstory videos` | Your talking-avatar tasks | | `visionstory assets` | Uploaded assets (`--kind image|video|audio`, `--cursor`, `--limit`) | ## Generate talking-avatar videos ```bash visionstory create-video --avatar-id YOUR_AVATAR_ID --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --output result.mp4 ``` | Flag | Description | |---|---| | `--avatar-id` | Required — from `visionstory avatars` | | `--text` / `--audio-url` / `--audio-file` | Exactly one — the script (text or audio) | | `--voice-id` | Voice for `--text` (default `Alice`) | | `--model-id`, `--aspect-ratio`, `--resolution`, `--emotion`, `--speech-rate` | Optional overrides | | `--prompt` | Optional `vs_character_v4` motion instructions, up to 2000 characters; works with text or audio | | `--output PATH` | Download the finished video to this path | | `--no-wait` | Return the task id immediately instead of polling to completion | 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: ```bash visionstory status --video-id YOUR_VIDEO_ID visionstory delete-video --video-id YOUR_VIDEO_ID ``` ## Manage avatars, voices, and assets ```bash visionstory voices --locale es-MX --provider minimax --limit 50 visionstory avatars --is-public --limit 20 visionstory create-avatar --image-url https://your.site/face.jpg visionstory update-avatar-framing --avatar-id YOUR_AVATAR_ID --aspect-ratio 9:16 --zoom 1.2 --offset-x 0 --offset-y -0.25 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 avatars` lists avatars owned by the current account. Add `--is-public` to list the public library instead. Each response contains `avatars` and `next_cursor`; pass the returned cursor to `--cursor` and choose a page size from 1 to 100 with `--limit`. Framing can be changed only for an owned avatar. Read its current `framing` values first, then update one `9:16`, `16:9`, or `1:1` entry with all five required options shown above. `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 ```bash 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: ```bash 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: ```bash 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](/guides/audio-understanding) for limits and billing. ## Generate AI images ```bash visionstory image-models visionstory create-image --model-id --prompt "a corgi surfing at sunset" ``` ## Generate AI videos with V-Character, Seedance, Wan, and Kling {#generate-ai-videos-with-seedance-wan-and-kling} ```bash 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: ```bash 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`: ```bash 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. See [image generation](/guides/image-generation) for 240-second timeout guidance, per-model reference limits, GPT Image 2 surcharges, and retryable provider errors. `create-ai-video --duration-sec auto` supports V-Character 5.0 Pro with video/audio refs. Quotes accept fractional `--duration-sec` for the resolved output duration and `--reference-video-duration-sec` for reference-video billing. Both quote and creation commands accept `--generate-audio` / `--no-generate-audio`; Kling 4.0 always generates audio and rejects false. See [AI video](/guides/ai-video) for model input combinations, account concurrency, and pricing. ```bash visionstory ai-video-cost --model-id vs_character_v5_pro --duration-sec 6.5 --reference-video-duration-sec 6.5 visionstory create-ai-video --model-id vs_character_v5_pro --prompt "Edit the scene into a watercolor animation" --duration-sec auto --ref-url https://example.com/clip.mp4 ``` ## 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](/guides/sdk) method; reach for the SDK when you need to embed the logic in code. ## Related VisionStory developer guides - [Python SDK](/guides/sdk) — the library the CLI is built on. - [Audio Transcription and Alignment](/guides/audio-understanding) — speech-to-text, SRT, and word timing. - [API reference](/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. ```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. --- # VisionStory MCP Server and Agent Setup Start by connecting your agent, discovering its available tools, and verifying API access with read-only requests. This guide covers setup and connection checks; after they succeed, follow the [Quick start](/guides/quick-start) for the complete talking-avatar generation workflow. AI agents can generate VisionStory videos, images, speech, avatars, and voices through MCP, the Python SDK, CLI, or machine-readable documentation. The Agent Skill covers talking-avatar generation, voice discovery, localized speech, transcription, and word alignment. 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 | Channel | Install | Best when | |---|---|---| | **MCP server** | `uvx visionstory-mcp` — your client runs it, nothing to host | Claude Desktop, coding agents, and other local MCP clients | | **CLI** | `curl -fsSL https://developers.visionstory.ai/cli \| bash` (latest release) | People and agents that want one persistent terminal command | | **Python SDK** | `pip install visionstory` | Agents that write and run Python | | **Agent Skill** | `npx skills add visionstory-ai/skills --skill visionstory-api` | Skill-compatible coding agents working with avatars, speech, or audio inside a repo | | **llms.txt + `.md` pages** | nothing — just fetch the URLs | Agents that browse the web and read docs on demand | 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: ```bash 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 on the [API keys page](https://developers.visionstory.ai/api-keys). ## 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 **28 public operations** available through the SDK and CLI, including avatar framing, audio transcription, and alignment. ### Recommended setup — Run with `uvx` 👍 Install `uv` once. Skip this command if `uvx --version` already works: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` Confirm VisionStory MCP can start: ```bash 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**: ```json { "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. Open its tool list and confirm that the VisionStory tools are available, including `get_credits`, `list_models`, `list_avatars`, and `list_voices`. Ask it to call `get_credits` and `list_models`; the connection is ready when both succeed. These read-only checks do not submit a generation. Before generating, use `list_avatars` with `is_public=true` and `list_voices` to discover valid resource IDs. ### Alternative — Install with `pip` Use this only if you prefer a permanently installed `visionstory-mcp` command: ```bash python3 -m pip install --upgrade visionstory-mcp ``` In the configuration above, replace the command and arguments with: ```json "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. ```json { "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. The local MCP server checks for a newer package when it starts and exposes `visionstory://release` with the installed version, latest version, feature highlights, release notes, and upgrade command. Update checks are cached and fail silently when offline. Set `VISIONSTORY_UPDATE_CHECK=0` to disable them. The remote MCP service is managed centrally and exposes the same resource, but it updates automatically; reconnect the MCP client to refresh its available tools. ## Use the Python SDK from an agent If your agent writes and runs code, `pip install visionstory` gives it a typed, zero-dependency client: ```python 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 immediately before building a request. Use `client.list_avatars(is_public=True)` for the public avatar library or omit `is_public` for owned avatars, then call `client.list_voices()`. Values shown in examples are placeholders, not guaranteed resources. Prefer the terminal? `pip install visionstory-cli` gives a `visionstory` [command-line tool](/guides/cli), so an agent can run `visionstory create-video ...` without writing code. See the [Python SDK](/guides/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](https://www.npmjs.com/package/skills) auto-detects your agent and drops the skill into `.agents/skills/`: ```bash 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](https://github.com/visionstory-ai/skills) before accepting it. No Node? Clone the repo and copy the skill folder in yourself: ```bash 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 resource discovery, avatar framing, talking-avatar generation, localized text to speech, audio transcription, word alignment, polling, and downloads. Use MCP, the standalone CLI, or the Python SDK when the agent needs the complete set of 28 public operations, including AI Video, image generation, and reusable assets. Skills-compatible agents pick it up automatically; you can also [view the developer-site SKILL.md](https://developers.visionstory.ai/skills/visionstory-api/SKILL.md) without downloading, or use the public distribution mirror at [github.com/visionstory-ai/skills](https://github.com/visionstory-ai/skills). The helper works standalone too: ```bash 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: ```text 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. ## Next: generate a video with one agent instruction {#generate-a-video-with-one-agent-instruction} After the read-only checks succeed, with the Skill installed (or the MCP server connected), use an instruction like this to request a paid generation: > 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](/guides/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](/guides/quick-start) — the underlying five-step flow. - [AI Video](/guides/ai-video) — text-to-video and image-to-video for agents using an active Pro API key. - [Audio Transcription and Alignment](/guides/audio-understanding) — speech-to-text, SRT, speaker labels, and word timing. - [API reference](/reference) — every endpoint the channels are built on. - [Changelog](/guides/changelog) — documentation version, API changes, and deprecation status. ## Structured media understanding Use `understand_media(prompt, inputs, schema)` for structured extraction from 1–8 images, audio clips, or videos. The prompt must contain 1–5000 characters and the JSON Schema must describe a top-level object. The synchronous call allows 180 seconds and returns `output`, token `usage`, and `cost_credit`; there is no model selector or free-text mode. Successful calls are charged, so do not automatically repeat timeouts. Remote MCP accepts media URLs or asset IDs; local MCP additionally accepts `inline_data`. The Agent Skill helper exposes `understand-media --prompt ... --inputs ... --schema ...`. Both MCP variants also accept optional `speech_rate` (`slow`, `normal`, `fast`) on `create_speech`; omission or null uses normal speed. See [Media Understanding](https://developers.visionstory.ai/guides/media-understanding) and [Text to Speech](https://developers.visionstory.ai/guides/text-to-speech) for complete contracts. --- # VisionStory API Changelog See what is new and improved in VisionStory developer tools and documentation. Current version: **0.0.16**. SDKs, CLIs, MCP clients, and AI agents can read the [machine-readable release manifest](/releases/latest.json) to discover new capabilities and upgrade instructions during use. ## 0.0.16 — November 17, 2026 **Seedance 2.5 Flash and unified reference-video pricing** ### Added - Added Seedance 2.5 Flash, expanded Seedance 2.5 reference limits, HEIC/HEIF image inputs, and additional V-Character 5.0 Pro aspect ratios across developer tools and bilingual documentation. - Aligned all Seedance models with reference-video pricing, reduced Fast and Mini rates, clarified integer fee breakdowns, and documented the Kling Omni one-video limit. ## 0.0.15 — November 6, 2026 **Faster version discovery and guided CLI upgrades** ### Added - Added startup upgrade guidance with a default Update now choice, four-hour reminders, and per-version skipping, without a feature summary. - Reduced release discovery caching to ten minutes across SDK, CLI, and local MCP; kept scripted calls non-interactive and added fresh explicit SDK checks. ## 0.0.14 — November 6, 2026 **Kling 4.0, V-Character 5.0 Pro, and reference-aware billing** ### Added - Added Kling 4.0 and V-Character 5.0 Pro support, auto and fractional-duration quotes, reference-video pricing, and talking-avatar motion prompts across developer tools. - Added higher image reference limits, reference-aware image pricing, longer timeouts, and provider-error guidance across bilingual API documentation, SDK, CLI, MCP, and Agent Skill. ## 0.0.13 — September 24, 2026 **AI video status filters and longer Seedance prompts** ### Added - Added AI video status filtering, structured concurrency error guidance, and 5000-character Seedance prompts across developer tools and bilingual documentation. ## 0.0.12 — September 23, 2026 **GPT Image models and resolution pricing** ### Added - Added GPT Image models, per-resolution image pricing, longer image request timeouts, and guidance for unavailable avatar framing across developer tools and bilingual documentation. ## 0.0.11 — September 17, 2026 **Seedream 5 image generation with model-aware limits** ### Added - Added Seedream 5.0 Lite and Pro image models with model-aware prompt, resolution, reference-image, and credit limits across the API reference, guides, CLI, MCP, Agent Skill, and bilingual developer site. ## 0.0.10 — September 16, 2026 **Avatar pagination and framing across every developer channel** ### Added - Added paginated avatar discovery and owned-avatar framing across the SDK, CLI, MCP servers, Agent Skill, and bilingual API reference. ## 0.0.9 — September 5, 2026 **Structured media understanding and bilingual developer docs** ### Added - Added structured media understanding for images, audio, and video through the Python SDK, CLI, local MCP, and Agent Skill. - Added optional text-to-speech speed control with slow, normal, and fast settings. - Added complete Chinese guides with English code and Agent prompts preserved. ### Changed - Updated model discovery documentation, bilingual navigation, canonical and language links, and the production sitemap; workflow illustrations now load as separate SVG files. ### Fixed - Completed all 27 successful API response examples, including typed image and AI video model catalogs and binary speech response headers. ## 0.0.8 — September 2, 2026 **CLI login, locale-aware voices, and complete API tooling** ### Added - Added `visionstory login` to securely prompt for, verify, and save an API key for future CLI sessions. - Added `visionstory logout` to remove the credential saved by the CLI. - Added voice `locale` metadata to voice listings and clone responses, and exposed voice filtering and pagination consistently in the SDK, CLI, MCP tools, and Agent Skill. - Added text-to-speech, transcription, and word-alignment commands to the bundled Agent Skill helper. ### Changed - Simplified CLI onboarding to one login command with clear connection and remaining-credit confirmation; `VISIONSTORY_API_KEY` remains available for scripts and CI and takes precedence over saved credentials. - Replaced the `GET /api/v1/voices` `language` filter with the BCP 47 `locale` filter; base tags such as `es` match every regional variant, while tags such as `es-MX`, `en-GB`, `zh-TW`, and `zh-HK` select one region. - Removed `480p` from the talking-avatar request and model capability enums; new requests must use `720p`, `1080p`, or `2k`. Historical video responses may still report `480p`. ### Fixed - Fixed Agent Skill binary MP3 handling, case-insensitive remote MCP provider filtering, and invalid Python boolean literals in generated REST examples. - Documented that transcription with `srt: true` now works without requiring `diarize: true`; speaker labels remain absent unless diarization is requested. ## 0.0.7 — September 2, 2026 **Audio understanding, voice discovery, and simplified API access** ### Added - Added `POST /api/v1/audio/transcribe` for speech-to-text, word timestamps, speaker diarization, and SRT subtitles. - Added `POST /api/v1/audio/align` for aligning a known script with audio at word level. - Added voice filtering and pagination, structured voice attributes, avatar `default_voice_id`, clone-voice metadata, and optional TTS `locale` support. - Added matching Python SDK, CLI, local MCP, and remote MCP operations. ### Changed - Removed per-capability beta allowlists; an active Pro plan or above is now the access requirement. - Retired `vs_talk_v1` from model discovery and directed new integrations to `vs_character_v4` with `720p`, `1080p`, or `2k` output. - Expanded the public API contract from 24 to 26 operations. ## 0.0.6 — August 27, 2026 **API key management and clearer API reference** ### Added - Added an [API keys](/api-keys) workspace for creating, renaming, copying, and deleting secret keys, with direct access to usage and billing. ### Changed - Updated the API reference with clearer supported models, parameter values, defaults, media requirements, and ready-to-use request examples. ### Fixed - Improved API key management on mobile and corrected incomplete or invalid examples across the reference documentation. ## 0.0.4 — August 25, 2026 **Developer platform testing release** ### Added - Launched the VisionStory developer portal with API reference pages, integration guides, and code examples. ### Changed - Improved authentication guidance and onboarding for the SDK, CLI, MCP, and Agent Skill. Breaking changes and deprecations will be called out clearly in the relevant release. ---