什么是 AI 虚拟人视频 API？

AI 虚拟人视频 API 可将数字主持人加上文本或录制音频，生成可由应用以程序方式生成的对口型视频。VisionStory 接受已鉴权的服务器端请求，会立即返回视频 ID，以异步方式渲染任务，并在生成完成后提供 MP4 URL。

如何用 VisionStory API 生成 AI 虚拟人视频？

创建 VisionStory API key，确认你的积分，获取当前模型、虚拟人和音色 ID，然后将 text_script 或 audio_script 提交到 POST /api/v1/video。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 服务器。受支持的编程 agent 可以在 API key 保留在你的环境变量或 MCP 密钥存储中的前提下，完成积分校验、列出当前模型/虚拟人/音色、准备有效请求、启动视频任务、监控进度并下载结果。

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

可以。希望虚拟人根据录制音频开口说话时发送 audio_script；需要 VisionStory 合成语音时，发送带音色 ID 的 text_script。每次请求只使用一种 script 类型，不要两种同时发送。

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

将视频创建视为异步任务处理。保存你的客户端请求 ID 与返回的视频 ID，大约每 5 秒轮询一次，并在任务到达 created 或 failed 时停止。已完成的视频 URL 会保留 7 天，因此需要时请将成品媒体复制到你自己的永久存储中。

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

将 VISIONSTORY_API_KEY 保存在服务器环境变量、CI secret 或 MCP 客户端密钥存储中，并通过 X-API-Key 请求头传递。切勿将 key 写入浏览器代码、移动应用包、公开仓库、截图、日志或 AI 聊天消息中。

我可以把虚拟人视频 API 和什么功能组合使用？

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

VisionStory API
为开发者打造

使用 VisionStory REST API 或 Python SDK，将文本或音频生成口型同步的虚拟人说话视频。查找当前可用的模型、虚拟人和音色，提交异步任务并下载生成好的 MP4——也可通过 CLI、MCP 服务器或 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 服务器与 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 服务器或安装 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 虚拟人说话模型生成的主持人

虚拟人说话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。

由 Agent 指挥的创作

AI 视频生成 API

从实时目录中选择模型，生成文生视频、图生视频以及参考引导片段。AI agent 可准备提示词与素材、预估积分、提交任务，并将结果与虚拟人主持人合成。

AI 虚拟人视频 API 常见问题

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

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

从一次已鉴权请求开始

打造你的首个 AI 虚拟人视频集成。

创建 API key、确认你的积分，并运行 5 步口播虚拟人快速上手。从 REST 或 Python 开始，随着工作流扩展再加入 CLI 自动化、MCP 工具或 Agent Skill。查询实时资源端点，而不是硬编码模型、虚拟人或音色 ID。

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