数字人视频 API 快速开始

本指南用五个步骤完成一个数字人视频：配置 VisionStory API 认证、提交文本脚本、轮询异步任务，并将生成的 MP4 保存到本地。

1. 创建 VisionStory API Key

注册后，在 VisionStory API Key 页面创建密钥。每次请求都通过 X-API-Key 请求头传入：

Request header

X-API-Key: $VISIONSTORY_API_KEY

密钥应保存在服务端，不要暴露在浏览器代码或公开仓库中。以下示例从环境变量读取密钥：

Shell

export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"

使用 VisionStory CLI 时，也可以在安装后运行 visionstory login。它会隐藏输入并验证密钥，然后保存供后续 CLI 会话使用，不会将密钥写入 Shell 历史记录。

开始付费生成前，先通过只读请求验证密钥：

Shell

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \
  https://openapi.visionstory.ai/api/v1/billing/credits

成功响应包含订阅方案和剩余点数；remaining 是当前 VisionStory 点数余额。返回 401 表示密钥缺失、过期或已失效。请先前往 API Key 页面创建或更换密钥，再继续。

2. 选择 API 客户端

按任务选择接入方式即可，之后可以随时切换，因为所有接入方式都使用同一个 VisionStory API 和 VISIONSTORY_API_KEY。

目标	推荐方式
将 VisionStory 接入 Python 应用	Python SDK
执行临时命令、Shell 脚本或 CI 任务	VisionStory CLI
让 AI Agent 将完整 API 作为工具使用	MCP Server
为编码 Agent 提供专注于数字人视频的工作流	Agent Skill
使用其他后端语言接入	REST API

Python SDK

安装带类型定义、无运行时依赖的 Python 客户端：

Shell

pip install visionstory

Python

from visionstory import VisionStoryClient

client = VisionStoryClient.from_env()  # reads VISIONSTORY_API_KEY

VisionStory CLI

在隔离环境中安装 CLI，或升级到最新版本：

Shell

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

如有提示，先重启终端，再验证认证并查询有效的资源 ID：

Shell

visionstory credits
visionstory avatars
visionstory voices

完整命令见 CLI 指南。

Agent Skill

面向数字人视频的 Agent Skill 包含 SKILL.md 和无依赖的 Python 辅助程序，可处理认证、Base64 编码、轮询和下载。安装时会自动检测支持的编码 Agent：

Shell

npx skills add visionstory-ai/skills --skill visionstory-api

然后用一条命令创建视频：

Shell

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

REST API

使用 curl 或任意 HTTP 客户端直接调用 API。本指南末尾的完整 Python 示例仅需 requests。

3. 生成数字人视频

使用公共形象和声音提交文本脚本。请求会立即返回 video_id，生成过程在后台异步继续：

Shell

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"
  }
}

正式接入前，请通过 GET /api/v1/models、GET /api/v1/avatars 和 GET /api/v1/voices 查询当前有效 ID，不要写死。要使用自己的音频，请用 audio_script 替代 text_script，两者不能同时传入。

4. 轮询视频任务

每 5 秒查询一次任务，直到进入最终状态：

Shell

curl -s \
  -H "X-API-Key: $VISIONSTORY_API_KEY" \
  "https://openapi.visionstory.ai/api/v1/video?video_id=YOUR_VIDEO_ID"

status	含义
`queued`	已接收，等待处理
`creating`	生成中
`created`	已完成，可以使用 `video_url`
`failed`	生成失败，停止轮询并检查错误

轮询间隔不要短于 5 秒，等待约 10 分钟后应停止。

5. 下载生成的 MP4

状态为 created 时，响应包含 video_url。已完成的视频保留 7 天；如需永久保存，请下载文件：

Shell

curl -sL -o result.mp4 "<video_url from the response>"

完整 Python SDK 示例

使用 SDK，只需几行代码即可完成整个流程：

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",
    text="Hello World, this is my first test video.",
    voice_id="YOUR_VOICE_ID",
)
video = client.generate_video(payload)
client.download(video["video_url"], Path("result.mp4"))
print("saved result.mp4")

阅读概览，了解核心资源、响应结构和模型选择。
浏览 API 参考，查看请求结构、参数和响应。
准备执行真实请求时，先获取 API Key。