VisionStory API 概览

VisionStory API 是面向数字人视频和可编程 AI 媒体的 REST API。你可以从后端、自动化脚本或 AI Agent 中生成视频、语音和图像，克隆声音和数字人形象，转写音频、创建字幕，并管理可复用的媒体素材。

VisionStory API 的工作方式

接入时遵循以下流程：

1. 查询资源 — 获取当前可用的模型、数字人形象和声音。
2. 提交生成任务 — POST /api/v1/video 会立即返回 video_id。
3. 轮询任务状态 — 调用 GET /api/v1/video?video_id=...，直到状态变为 created。
4. 下载结果 — 从响应中获取 video_url。

所有请求使用同一个基础地址，并通过同一个请求头进行认证：

X-API-Key: $VISIONSTORY_API_KEY

基础地址： https://openapi.visionstory.ai

在 VisionStory API Key 页面创建密钥。密钥应保存在服务端，不要暴露在浏览器代码或公开仓库中。

所有响应采用统一的外层结构。请求成功后，从顶层 data 字段读取结果：

{
  "data": {
    "video_id": "YOUR_VIDEO_ID"
  },
  "message": "success",
  "server_time": "2026-08-20T06:15:18Z"
}

核心 API 资源

数字人形象

数字人形象是视频中讲述脚本的角色。你可以使用公共形象库中的现成形象，也可以通过一张照片创建专属形象：

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

默认响应在 avatars 中返回你的专属形象；添加 is_public=true 后改为查询公共形象库。使用 next_cursor 继续加载后续页面。

声音

声音通过 voice_id 标识，用于将视频中的文本转换为语音。你可以从公共声音库中选择，也可以通过音频样本克隆自己的声音：

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

响应包含 public_voices 和 my_voices。

音频理解

将 WAV 或 MP3 语音转为文本、词级时间戳、说话人标签和 SRT 字幕，或将已知脚本与音频对齐。请求示例和计费方式见音频转写与对齐 API。

点数

点数是生成任务的计费单位，随 VisionStory 订阅提供。每次生成任务都会消耗点数，失败任务会自动退还。你可以随时查询余额：

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

数字人视频的状态响应通过 cost_credit 返回实际消耗的点数，方便你查看每个已完成任务的准确费用。

数字人视频模型

数字人视频模型负责渲染角色。调用 GET /api/v1/models 获取机器可读的模型目录。

已下线的 vs_talk_v1 不再出现在模型目录中。新请求必须从 GET /api/v1/models 返回的选项中选择 720p、1080p 或 2k；数字人视频请求不再接受 480p。

除数字人视频外，API 还提供前沿 AI 视频生成模型，支持文生视频和图生视频。这些能力目前处于 Beta 阶段。

开始接入 VisionStory API

• 快速开始 — 五步创建第一个视频。
• API 参考 — 查看可用接口、数据结构和示例。
• 获取 API Key — 配置服务端接入。

结构化媒体理解

通过 POST /api/v1/media/understand 从图片、音频或视频中提取结构化 JSON。请求包含提示词、1–8 个媒体引用，以及顶层为对象的 JSON Schema。SDK、CLI 与 MCP 示例见媒体理解；音频转写和字幕时间戳请使用语音转文字。