什么是 AI 数字人视频 API？

AI 数字人视频 API 可将数字人讲解员与文本或录制音频合成为口型同步视频，应用可通过编程方式生成。VisionStory 接受已鉴权的服务端请求，立即返回视频 ID，异步渲染任务，并在生成完成后提供 MP4 URL。

如何通过 VisionStory API 生成 AI 数字人视频？

创建 VisionStory API key，确认积分充足，获取当前模型、数字人和音色 ID，然后向 POST /api/v1/video 提交 text_script 或 audio_script。API 会立即返回视频 ID。每隔约 5 秒轮询一次任务，直到状态变为 created，再通过 video_url 下载 MP4。

我应该使用 REST API、Python SDK 还是 CLI？

需要与语言无关的控制时用 REST；搭建 Python 服务或 notebook 时用 Python SDK；终端自动化、CI 或批量生成时用 CLI。这三种接口共用同一套 VisionStory 资源与异步视频工作流。

Codex、Claude Code 或 Cursor 能帮我生成数字人视频吗？

可以。安装 VisionStory Agent Skill 或连接 VisionStory MCP server。受支持的编码智能体可在 API key 保持在你的环境变量或 MCP secret 存储中的前提下，核验积分、列出当前模型/数字人/音色、准备合规请求、启动视频任务、监控进度并下载结果。

我可以用音频而不是文本来生成数字人视频吗？

可以。当你希望数字人按录制音频说话时发送 audio_script；当你希望 VisionStory 合成语音时发送带音色 ID 的 text_script。每次请求只使用一种脚本类型，不要两种同时发送。

生产环境集成应如何处理视频生成？

将视频创建视为异步任务。保存你的客户端请求 ID 与返回的视频 ID，每隔约 5 秒轮询一次，当任务状态到达 created 或 failed 时停止。已完成的视频 URL 会保留 7 天，因此在需要时请将成片复制到你自己的长期存储中。

我应该把 VisionStory API key 存放在哪里？

将 VISIONSTORY_API_KEY 存放在服务器环境变量、CI secret 或 MCP client secret store 中，并通过 X-API-Key 请求头发送。切勿把 key 写进浏览器代码、移动应用安装包、公开仓库、截图、日志或 AI 聊天消息里。

数字人视频 API 可以与哪些能力组合使用？

你可以将数字人视频与文本转语音、公共或克隆音色、可复用的图片与音频素材、转写、AI图像生成以及前沿视频模型组合使用。这些基础能力可支持本地化讲解视频、个性化触达、自动化学习内容与 AI 智能体媒体工作流。

VisionStory API
为开发者而生

通过 VisionStory REST API 或 Python SDK，将文本或音频生成口型同步的数字人口播视频。获取最新的模型、头像与音色，提交异步任务并下载成品 MP4；或使用 CLI、MCP server 或 Agent Skill 自动化同一套工作流。

查看开发者文档

POST /api/v1/video

REST API
Python SDK
CLI
MCP
Agent Skill

智能体就绪

在你的智能体工作的地方也能用。

复制一条配置消息给你的编程智能体，或连接 MCP 服务器，将 VisionStory 作为可复用工具开放出来。

VisionStory CLI

一次安装，在终端调用全部 API。

安装器会在隔离环境中升级到最新的 PyPI 版本，你现有的 Python 项目不受影响。

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

macOS · Linux · WSL安装选项

将此配置提示词发送给 Claude Code

Help me set up VisionStory and generate a talking-avatar video.1. Install or update the CLI and Agent Skill:   curl -fsSL https://developers.visionstory.ai/cli | bash   npx skills add visionstory-ai/skills --skill visionstory-api2. Run visionstory doctor. If I need a key, send me to https://developers.visionstory.ai/api-keys, wait while I create one, then ask me to run visionstory login in my terminal. Never ask me to paste the key into chat or expose it.3. Verify access with visionstory credits. Stop and help me if it fails.4. Discover current models, avatars, and voices, then use the CLI and visionstory-api skill to create and download the video. Never delete anything unless I explicitly request and confirm it.

第一次用？

先创建一个 API Key，然后把这段提示词发给你的编程智能体。它会引导你完成 visionstory 登录、核验积分，并在不暴露密钥的情况下创建视频。

VisionStory 开发者工具

为你的技术栈选择合适的 API 集成方式。

REST、Python SDK、CLI、MCP server 与 Agent Skill 均使用同一套需要鉴权的 VisionStory API 与资源 ID。你可以先从任意一种接口开始，再将同样的数字人视频工作流迁移到后端、CI 流水线或编程智能体中。

01REST

调用 REST API

使用任意后端语言调用 VisionStory。列出当前可用的模型、头像与音色；将 text_script 或 audio_script 发送至 POST /api/v1/video；轮询任务直到创建完成；然后下载 MP4。

查看 REST API 参考 02PYTHON

使用 Python SDK 开发

使用带类型提示、零依赖的 Python 客户端，实现基于环境变量的鉴权、请求体构建、上传、任务轮询与下载。适用于 Python 应用、notebook 以及内部媒体服务。

阅读 Python SDK 快速开始 03CLI

用 CLI 自动化

运行 visionstory doctor，校验积分、查找资源 ID、生成数字人视频、检查任务，并在终端、shell 脚本或 CI 任务中下载结果——无需先搭建应用。

安装并验证 CLI 04MCP / SKILL

连接 AI 编程智能体

连接 VisionStory MCP server 或安装 Agent Skill，让 Codex、Claude Code、Cursor、Windsurf、Cline 与 Gemini 在 API key 保持本地密钥存储的前提下，发现资源、生成媒体并下载结果。

连接 MCP 或 Agent Skill

数字人口播 API 快速开始

生成你的第一个数字人口播视频。

创建服务端 API key，核对积分余额，并获取当前模型、头像与音色 ID。将 text_script 或 audio_script 提交到 POST /api/v1/video，大约每 5 秒轮询一次直到任务创建完成，然后下载 MP4。已完成视频的 URL 将保留 7 天。

create_video.py

from pathlib import Pathfrom visionstory import VisionStoryClient, build_video_payload client = VisionStoryClient.from_env()payload = build_video_payload(    avatar_id="YOUR_AVATAR_ID",    text="Hello from my product.",    voice_id="YOUR_VOICE_ID",)video = client.generate_video(payload)client.download(video["video_url"], Path("result.mp4"))

VisionStory 模型目录

选择满足你输出需求的模型。

从你要完成的任务出发，再在运行时拉取最新的模型目录。可用 ID、支持的参数与输出限制，以 API 返回为准。

数字人口播VisionStory

V-Character 4.0

vs_character_v4

VisionStory 原生角色模型可将一张人像与文本或录制音频结合，生成身份一致、动作更有表现力且口型自然同步的演绎。

文本或录制音频
720p、1080p 或 2K
最长 10 分钟

AI 视频ByteDance

Seedance 2.5

seedance-2.5

生成提示词驱动与图像驱动的视频，具备连贯运动、电影级镜头运动，以及更长的单段片段。

文本生成视频
图像生成视频
4–30 秒片段

AI 图像Google

Nano Banana 2

nano-banana-2

生成高分辨率图像，可靠地渲染文字，并通过对话式、参考引导的编辑来精修结果。

提示词生成图片
参考引导编辑
1K 与 2K 输出

可组合的 AI 媒体 API

整合头像、音色与 AI 视频 API。

用一个 API key 即可生成数字人讲解视频、合成自然语音、复用自定义头像与音色及媒体资产，并生成配套视频片段。无需拼接多个供应商，即可打造本地化讲解、个性化新手引导、教育内容、销售触达或由智能体生成的媒体内容。

核心数字人工作流

数字人口播视频 API

从文本或录制音频生成口型同步的数字人讲解视频。选择公共头像，或用一张人像创建可复用的自定义头像；选择公共音色或克隆音色；异步任务完成后即可获得可下载的 MP4。

音色与语音层

文本转语音与音色 API

使用公共或克隆音色，将文本转换为自然的 MP3 语音，然后在数字人视频与本地化内容中复用同一音色。运行时查询音色目录，而不是硬编码音色 ID。

智能体驱动创作

AI 视频生成 API

从实时目录中选择模型，生成文生视频、图生视频与参考引导片段。AI 智能体可准备提示词与素材、预估积分、提交任务，并将结果与数字人口播讲解员合成。

AI 数字人视频 API 常见问题

关于鉴权、请求、异步任务、SDK、CLI 自动化、MCP 与生产环境使用的直接解答。

AI 数字人视频 API 可将数字人讲解员与文本或录制音频合成为口型同步视频，应用可通过编程方式生成。VisionStory 接受已鉴权的服务端请求，立即返回视频 ID，异步渲染任务，并在生成完成后提供 MP4 URL。
创建 VisionStory API key，确认积分充足，获取当前模型、数字人和音色 ID，然后向 POST /api/v1/video 提交 text_script 或 audio_script。API 会立即返回视频 ID。每隔约 5 秒轮询一次任务，直到状态变为 created，再通过 video_url 下载 MP4。
需要与语言无关的控制时用 REST；搭建 Python 服务或 notebook 时用 Python SDK；终端自动化、CI 或批量生成时用 CLI。这三种接口共用同一套 VisionStory 资源与异步视频工作流。
可以。安装 VisionStory Agent Skill 或连接 VisionStory MCP server。受支持的编码智能体可在 API key 保持在你的环境变量或 MCP secret 存储中的前提下，核验积分、列出当前模型/数字人/音色、准备合规请求、启动视频任务、监控进度并下载结果。
可以。当你希望数字人按录制音频说话时发送 audio_script；当你希望 VisionStory 合成语音时发送带音色 ID 的 text_script。每次请求只使用一种脚本类型，不要两种同时发送。
将视频创建视为异步任务。保存你的客户端请求 ID 与返回的视频 ID，每隔约 5 秒轮询一次，当任务状态到达 created 或 failed 时停止。已完成的视频 URL 会保留 7 天，因此在需要时请将成片复制到你自己的长期存储中。
将 VISIONSTORY_API_KEY 存放在服务器环境变量、CI secret 或 MCP client secret store 中，并通过 X-API-Key 请求头发送。切勿把 key 写进浏览器代码、移动应用安装包、公开仓库、截图、日志或 AI 聊天消息里。
你可以将数字人视频与文本转语音、公共或克隆音色、可复用的图片与音频素材、转写、AI图像生成以及前沿视频模型组合使用。这些基础能力可支持本地化讲解视频、个性化触达、自动化学习内容与 AI 智能体媒体工作流。

从一次鉴权请求开始

搭建你的第一个 AI 数字人视频集成。

创建 API key，确认积分充足，并运行 5 步口播数字人快速上手。先从 REST 或 Python 开始，随着工作流增长再加入 CLI 自动化、MCP 工具或 Agent Skill。查询实时资源接口，而不是硬编码模型、数字人或音色 ID。

创建 VisionStory API key 查看开发者文档