VisionStory CLI 指南

VisionStory CLI 让你从终端、Shell 脚本或 CI 任务中调用完整 API。安装 visionstory-cli 后，即可使用 visionstory 命令查询资源、生成媒体、轮询任务和下载结果。需要 Python 3.10 或更高版本，底层使用官方 Python SDK。

安装 VisionStory CLI

一键安装支持 macOS、Linux 和 WSL。安装脚本会按需准备 uv，并从 PyPI 将 CLI 安装到隔离的工具环境中。

安装最新版本（推荐）

不设置版本变量时，以下命令会安装或升级到 PyPI 上最新的 VisionStory CLI 版本：

Shell

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

固定安装版本

仅在明确需要某个旧版本时设置 VISIONSTORY_VERSION。例如：

Shell

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

如果希望自行管理 Python 环境，也可以直接安装同一个包：

Shell

pip install visionstory-cli

确认命令已加入 PATH：

Shell

visionstory --help

然后登录。输入时密钥不会显示；CLI 会通过只读点数查询验证密钥，并将其保存，供后续 CLI 会话使用：

Shell

visionstory login

成功提示会确认连接状态并显示剩余点数。返回 401 表示密钥缺失、过期或无效；请到 API Key 页面更换密钥，然后重新运行 visionstory login。

检查、更新、诊断或卸载 CLI

以下本地命令无需预先配置 API Key：

Shell

visionstory --version
visionstory login
visionstory logout
visionstory update --check
visionstory update
visionstory doctor
visionstory uninstall

命令	功能
`visionstory --version`	单行输出已安装版本
`visionstory version`	以 JSON 输出已安装版本，供脚本读取
`visionstory login`	安全地提示输入、验证并保存 API Key
`visionstory logout`	移除 `visionstory login` 保存的 API Key
`visionstory update --check`	查询 PyPI，不修改当前安装
`visionstory update`	沿用当前的 `uv tool` 或 `pip` 安装方式升级
`visionstory doctor`	显示可执行文件、Python 版本、安装方式、API URL 和密钥是否已配置，不会打印密钥
`visionstory uninstall`	请求确认后卸载 CLI

visionstory upgrade 是 visionstory update 的别名。visionstory uninstall --yes 仅用于无人值守脚本或 CI。

从命令行生成视频

四步生成第一个视频：

Shell

# 1. Sign in once (skip this if you already completed it)
visionstory login

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

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

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

API 操作命令将响应以 JSON 输出到 stdout，出错时返回非零退出码，便于配合 jq 和 Shell 脚本使用。login、logout、update、uninstall 等安装和账户管理命令则使用简洁、便于阅读的输出。

在交互式终端中运行 CLI 时，每天最多检查一次共享的 VisionStory 版本清单。若新版增加了能力，每周最多向 stderr 输出一次简短提醒，包含版本号、版本标题、更新命令和更新日志。stdout 的 JSON 保持不变；离线检查失败时静默跳过。只有执行 visionstory update 才会升级，CLI 不会自行更新。

设置 VISIONSTORY_UPDATE_CHECK=0 可关闭被动提醒。需要立即与 PyPI 版本比较但不安装时，运行 visionstory update --check。

配置 CLI 认证

本地交互式使用只需登录一次：

Shell

visionstory login

输入时不显示字符是正常现象。CLI 会先验证密钥，再将其保存到用户配置目录，文件仅允许当前用户访问。运行 visionstory logout 可移除已保存的密钥。

脚本和 CI 应改为在进程环境中设置 VISIONSTORY_API_KEY。环境变量中的凭证优先于已保存的登录凭证；CLI 不接受通过命令行参数传入密钥。

默认与自定义配置

默认配置：连接官方 API

正常使用时，完成一次 visionstory login 即可，无需额外配置 API 地址。

配置项	默认行为	覆盖方式
API 地址	`https://openapi.visionstory.ai`	`--base-url` 或 `VISIONSTORY_API_BASE`
API Key	使用 `visionstory login` 保存的密钥	`VISIONSTORY_API_KEY` 优先于已保存的密钥
HTTP 超时	未被具体操作覆盖的请求默认为 60 秒	全局参数 `--request-timeout`，单位为秒

先运行 doctor 查看最终使用的地址（api_base_url）和认证来源。它不会发起 API 请求，也不会打印密钥。确认地址后，再用 credits 发起只读请求验证访问权限：

Shell

visionstory doctor
visionstory credits

仅为本次命令指定地址

需要连接可信且兼容 VisionStory API 的代理、网关或测试服务时，可以直接传入地址。请将示例域名替换为自己的服务：

Shell

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

全局参数必须放在子命令前面。 调整请求超时时也遵循这一规则：

Shell

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

--base-url 仅对本次执行生效。下次不传时，会使用环境变量指定的地址；未设置环境变量时，使用官方 API。

为当前终端统一设置地址

在 macOS、Linux 或 WSL 的 Shell 中执行：

Shell

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

该设置对当前 Shell 及其子进程有效，不会自动保存到后续终端。如需持久化，请在 Shell 启动文件或部署环境中配置此变量。CI 中的 API Key 应单独通过平台的密钥存储注入。

地址优先级： --base-url → VISIONSTORY_API_BASE → https://openapi.visionstory.ai。

恢复当前 Shell 的官方地址时，移除环境变量，并省略 --base-url：

Shell

unset VISIONSTORY_API_BASE
visionstory doctor

如果在启动文件或部署配置中也设置了变量，请一并移除，后续会话才会恢复默认。不要将变量设为空字符串。

发送密钥前，先确认目标地址。 仅使用可信且兼容 VisionStory API 的 HTTPS 服务。通过 SDK 发起的 API 命令会将当前密钥放入 X-API-Key 请求头，使用自定义域名时也是如此。基础地址末尾不要加 /api/v1，CLI 会自动拼接接口路径。登录只保存密钥，不会创建按域名隔离的配置，也不会保存自定义地址。使用 --base-url 登录不会改变后续命令的地址。

--request-timeout 控制 HTTP 请求超时，不是整个视频的生成等待时间；部分操作使用自己的请求超时。download 命令直接访问 --url 指定的链接，--base-url 不会改写该 URL。

查询 API 资源

命令	返回内容
`visionstory models`	数字人视频渲染模型
`visionstory avatars`	你的形象和公共形象
`visionstory voices`	你的声音和公共声音
`visionstory credits`	剩余点数
`visionstory videos`	你的数字人视频任务
`visionstory assets`	已上传素材（`--kind image

生成数字人视频

Shell

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

参数	说明
`--avatar-id`	必填，来自 `visionstory avatars`
`--text` / `--audio-url` / `--audio-file`	三选一，提供文本或音频脚本
`--voice-id`	`--text` 使用的声音，默认为 `Alice`
`--model-id`、`--aspect-ratio`、`--resolution`、`--emotion`、`--speech-rate`	可选覆盖参数
`--output PATH`	将生成好的视频下载到此路径
`--no-wait`	立即返回任务 ID，不轮询至完成

使用创建命令返回的 ID 查询状态。删除不可撤销，只有资源所有者明确要求并确认后，才执行删除命令：

Shell

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

管理形象、声音与素材

Shell

visionstory voices --locale es-MX --provider minimax --limit 50
visionstory create-avatar --image-url https://your.site/face.jpg
visionstory clone-voice --audio-url https://your.site/sample.mp3 --preview-text "Hello"
visionstory upload-asset --url https://your.site/clip.mp4

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

使用 --image、--audio-file 或 --file 可传入本地路径，替代 URL。

visionstory voices 支持 --cursor、--limit、--locale 和 --provider。BCP 47 基础语言标记（如 es）匹配所有西班牙语声音；如果发音和口音需要对应特定地区，请使用 es-MX、en-GB、zh-TW 或 zh-HK 等语言地区标记。

生成文本转语音音频

Shell

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

--locale 可选。使用 en-GB 或 zh-TW 等 BCP 47 值，引导多语言声音的发音和口音。

转写与对齐音频

将本地 WAV 或 MP3 文件转写为 JSON，也可以请求说话人标签和 SRT 字幕：

Shell

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

已有准确的口述文本、需要词级时间戳时，使用 align：

Shell

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

两个命令均要求从 --audio-file、--audio-url 和 --asset-id 中选择且仅选择一个。限制与计费见音频转写与对齐。

生成 AI 图像

Shell

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

使用 Seedance、Wan 和 Kling 生成 AI 视频

Shell

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

图生视频和参考素材驱动的生成可通过 URL 传入媒体：

Shell

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

对于复杂请求体（如 Base64 inline_data、asset_id 引用或多个参考素材），通过 --json 传入完整请求体：

Shell

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

create-image 同样支持 --json。

CLI 行为与输出

JSON 输出 — 各 API 命令以 JSON 输出响应，可通过管道传给 jq 提取字段。
接口契约诊断 — visionstory contract 无需 API Key，输出 SDK、CLI 与 MCP 共享的 OpenAPI 指纹和操作数量。
阻塞式创建 — create-video 和 create-ai-video 会轮询至视频状态为 created，指定 --output 时下载结果；加上 --no-wait 可立即返回任务。
退出码 — 成功为 0，出错为 1，错误信息输出到 stderr。
与 SDK 能力一致 — 每条命令一一对应 Python SDK 方法；需要将逻辑嵌入代码时，使用 SDK。

Python SDK — CLI 底层使用的库。
音频转写与对齐 — 语音转文字、SRT 和词级时间戳。
API 参考 — 查看 CLI 封装的全部接口。

从媒体提取结构化数据

使用可公开访问的 URL 或现有素材 ID。--inputs 和 --schema 接受 JSON；运行前请替换占位符。

Shell

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

媒体提取同步处理，最长等待 180 秒，返回 output、usage 和 cost_credit，仅成功调用计费。超时后不要盲目重试，详见媒体理解。TTS 语速支持 slow、normal 或 fast，省略时保持正常语速。