万相 3.0 视频生成 API 开发文档
适用模型:wan3.0-video-prime、wan3.0-video
API Base URL:https://openapi.yhsapi.com
文档版本:1.0 · 更新日期:2026-11-07
本文介绍通过本平台调用万相 3.0 的完整流程:准备 API Key、提交生成任务、查询状态、获取视频,以及处理限流、失败和重试。两个模型共用本文中的接口与参数结构,仅需修改请求的 model。
1. 模型与能力
| 模型 ID | 版本 | 说明 |
|---|---|---|
wan3.0-video-prime | 高速版 | 官方定位为能力对齐标准版、提升生成速度;实际耗时取决于排队、素材和输出规格 |
wan3.0-video | 标准版 | 使用相同的请求格式、任务查询方式和结果结构 |
两款模型均采用异步任务方式,支持以下输入场景。模型能力介绍可参考万相 3.0 官方使用指南。
| 场景 | 输入方式 | 说明 |
|---|---|---|
| 文生视频 | input.prompt | 通过文字描述生成视频,省略 media |
| 首帧生视频 | first_frame | 使用图片作为起始画面 |
| 首尾帧生视频 | first_frame + last_frame | 指定起始与结束画面 |
| 参考生视频 | reference_image / reference_video / reference_audio | 结合图片、视频、音频及提示词生成 |
| 文件或网页生视频 | file 或 link | 根据公开文档或网页内容生成,可搭配参考素材 |
| 视频编辑 | reference_video + 编辑指令 | 通过提示词描述风格、画面内容等修改目标 |
| 视频延长 | reference_video + 延长指令 | 明确传入最终输出时长,建议使用自适应比例 |
平台接受的输出规格为 480P、720P、1080P,输出时长为 2~30 秒的整数。具体请求还需符合输入与输出总时长限制,以及模型当前启用的规格和能力配置。输出为 MP4,模型标准输出帧率为 30 fps。官方输出规格说明
2. 接入准备
2.1 开通与鉴权
调用前,请在平台创建可用的 API Key,并确认账户余额、Key 额度、模型权限及 IP 白名单允许本次调用。
所有提交和查询请求均使用:
Authorization: Bearer <平台 API Key>平台 Key 的格式为 LT- 加 32 位英文字母或数字。请使用平台实际签发的完整值;百炼 Key、官网登录 JWT 和其他平台的 Key 不能用于本接口。
请从服务端调用 API,通过环境变量或密钥管理服务保存 Key。不要将 Key 写入前端页面、移动端安装包、公开仓库或 URL 查询参数。
2.2 接口地址
| 操作 | Method | 完整地址 |
|---|---|---|
| 创建视频任务 | POST | https://openapi.yhsapi.com/api/v1/services/aigc/video-generation/video-synthesis |
| 查询视频任务 | GET | https://openapi.yhsapi.com/api/v1/tasks/{task_id} |
Base URL 不包含 /api/v1;拼接时不要重复添加路径。本文接口使用百炼原生结构,请按上表路径调用。
2.3 协议约定
- 提交请求使用 UTF-8 编码的 JSON,
Content-Type: application/json。 - 提交任务必须携带
X-DashScope-Async: enable;查询任务无需该请求头。 - 接口成功与失败均返回 JSON。HTTP 请求失败时使用标准 HTTP 状态码;任务执行失败通过查询响应的
output.task_status表达。 - 响应体的
request_id与响应头X-Request-ID用于定位本次请求。request_id不是任务 ID,每次查询会产生本次查询的请求标识。 - 可通过
Accept-Language: zh-CN、zh-Hant或en选择错误提示语言,默认简体中文;响应头Content-Language表示响应语言。不要在 JSON 中添加language。
3. 快速开始
以下 cURL 示例使用 Bash / zsh 语法。Windows PowerShell 用户可使用 curl.exe 并调整环境变量与换行语法,或直接使用后文的 Python 示例。
第一步:准备环境变量
export API_BASE_URL="https://openapi.yhsapi.com"
export PLATFORM_API_KEY="替换为平台签发的完整 API Key"第二步:提交任务
curl --request POST \
"$API_BASE_URL/api/v1/services/aigc/video-generation/video-synthesis" \
--header "Authorization: Bearer $PLATFORM_API_KEY" \
--header 'Content-Type: application/json' \
--header 'X-DashScope-Async: enable' \
--header 'Accept-Language: zh-CN' \
--data-raw '{
"model": "wan3.0-video-prime",
"input": {
"prompt": "清晨的海边,一只金毛犬沿着沙滩奔跑,镜头平稳跟随,阳光温暖,配有自然海浪声。"
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 5,
"audio": true
}
}'受理成功,HTTP 200:
{
"output": {
"task_id": "b5836ed1-f195-441d-990b-0eaec3b9f349",
"task_status": "PENDING"
},
"request_id": "33c511a7-d546-49dd-bb06-6405b5c51873"
}立即保存 output.task_id。此响应表示平台已受理,最终生成结果需要继续查询。
第三步:查询状态
将变量替换为实际返回的任务 ID,后续查询使用创建任务时的同一 API Key:
export TASK_ID="b5836ed1-f195-441d-990b-0eaec3b9f349"
curl --request GET \
"$API_BASE_URL/api/v1/tasks/$TASK_ID" \
--header "Authorization: Bearer $PLATFORM_API_KEY" \
--header 'Accept-Language: zh-CN'PENDING 或 RUNNING 时,建议等待 10~15 秒再次查询。SUCCEEDED 时读取 output.video_url 并下载;FAILED、CANCELED、UNKNOWN 的处理方式见任务状态。查询间隔是客户端建议值,不代表生成时间承诺。
4. 创建视频生成任务
POST /api/v1/services/aigc/video-generation/video-synthesis4.1 请求头
| Header | 必填 | 值与说明 |
|---|---|---|
Authorization | 是 | Bearer <平台 API Key> |
Content-Type | 是 | application/json |
X-DashScope-Async | 是 | 固定为小写字符串 enable |
Accept-Language | 否 | zh-CN、zh-Hant、en,默认简体中文 |
4.2 顶层请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | wan3.0-video-prime 或 wan3.0-video,区分大小写 |
input | object | 是 | 提示词和素材输入 |
parameters | object | 否 | 生成参数;省略时输出时长为 5 秒、分辨率为 1080P |
4.3 input 对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 条件必填 | 描述主体、动作、场景、镜头和声音;与 media 至少提供一项 |
media | array of object | 条件必填 | 1~20 项有序素材;纯文生视频时省略,与 prompt 至少提供一项 |
提示词建议控制在 20,000 字符以内,较长内容应自行精简;不要依赖上游自动截断。平台还可能按模型配置限制长度,且整个 JSON 正文始终受 65,535 字节上限约束。官方提示词参数说明
media 每一项的结构:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | 素材类型表中的一种 |
url | string | 是 | 可从公网直接读取的 HTTP(S) 素材地址;签名 URL 按原始内容使用 |
4.4 parameters 对象
| 字段 | 类型 | 默认行为 | 取值与说明 |
|---|---|---|---|
resolution | string | 平台补为 1080P | 480P、720P、1080P,必须大写 |
ratio | string | 省略后使用模型默认的 adaptive | adaptive、21:9、16:9、4:3、1:1、3:4、9:16 |
duration | integer | 平台补为 5 | 输出视频时长,单位秒,2~30 的整数;输入参考视频时还需满足总时长限制 |
audio | boolean | 省略后使用模型默认的 true | true 生成声音,false 不生成音轨 |
seed | integer | 省略后由模型随机生成 | -1 或 0~2147483647;-1 表示随机,相同种子也不保证结果完全一致 |
prompt_extend | boolean | 省略后使用模型默认的 true | 是否智能改写提示词;使用 file 或 link 时不得设为 false,建议显式传 true |
watermark | boolean | 省略后使用模型默认的 false | 是否添加水印 |
ratio、audio、seed、prompt_extend、watermark 省略时保持未指定,由模型采用默认行为;需要固定行为时请显式传值。官方参数默认值
平台暂不支持 duration: -1 智能时长,会返回 HTTP 403、code: "UnsupportedOperation"。视频编辑和延长场景也必须提供确定的整数时长,或使用省略时的 5 秒默认值。
4.5 校验与空值
- 请求顶层和所有嵌套请求对象都只接受本文声明的字段;未知字段会被拒绝。不要添加
stream、n、negative_prompt、callback_url或其他模型的参数。 - 整数与布尔值使用严格 JSON 类型,例如
duration: 5、audio: false;不要传"5"、5.0或"false"。 - 已声明的字段收到
null、空字符串、纯空白字符串,或忽略大小写及首尾空白后的字符串"null"时,按未传处理:必填字段报错,可选字段采用省略行为。 0、false、[]、{}不按空值处理,仍需满足对应字段约束。例如media: []无效,纯文生视频应省略media;parameters: {}会使用默认参数。- JSON 必须合法且不能包含重复对象键、
NaN或Infinity。 - 正文上限为 65,535 字节,包含字段名、提示词、URL 和 JSON 结构;这是字节上限,不是字符数上限。超限返回 HTTP
413。
4.6 受理响应
| 字段 | 类型 | 说明 |
|---|---|---|
output.task_id | string | 平台任务 ID,标准小写 UUID;用于后续查询 |
output.task_status | string | 提交成功固定返回 PENDING。当前执行状态请调用查询接口 |
request_id | string | 本次提交请求的追踪 ID |
5. 素材要求与组合规则
5.1 素材类型与数量
type | 含义 | 数量上限 | 使用要求 |
|---|---|---|---|
first_frame | 首帧图片 | 1 张 | 只能与 last_frame 组合,或单独使用 |
last_frame | 尾帧图片 | 1 张 | 必须同时提供 first_frame |
reference_image | 参考图片 | 10 张 | 可与其他参考类型、文件或网页组合 |
reference_video | 参考视频 | 5 段 | 单段 1~15 秒,所有输入视频合计不超过 15 秒 |
reference_audio | 参考音频 | 5 段 | 单段 1~15 秒,所有输入音频合计不超过 15 秒 |
file | 参考文档 | 1 个 | 与 link 互斥,可与参考图片、视频、音频组合 |
link | 公开网页 | 1 个 | 与 file 互斥,可与参考图片、视频、音频组合 |
每类上限与 media 总数不超过 20 的限制需同时满足。不能将所有分类的最大数量直接相加使用。具体可用组合还受模型当前启用的能力配置约束。
5.2 文件规格
| 素材 | 格式 | 规格限制 |
|---|---|---|
| 图片 | JPEG / JPG / PNG / BMP / WEBP | 单张 ≤20 MB;单边 240~8000 像素;长边与短边比不超过 8;PNG 不使用透明通道 |
| 视频 | MP4 / MOV | 单个 ≤100 MB;单边 240~4096 像素;长边与短边比不超过 8;帧率 ≥16 fps;时长同时满足上一表 |
| 音频 | WAV / MP3 | 单个 ≤15 MB;时长同时满足上一表 |
| 文档 | DOCX / DOC / XLSX / XLS / PPTX / PPT / PDF / TXT / KEY / PAGES / NUMBERS / MD | 单个 ≤100 MB;PDF、Word、PowerPoint、KEY、PAGES 文档不超过 50 页 |
| 网页 | HTTP(S) URL | 公开可读取,无需登录 |
以上是模型侧素材规格,符合请求 JSON 校验不代表媒体内容一定有效。平台会在受理前读取参考视频的实际时长;其他媒体属性及内容也可能在异步执行时被模型拒绝。官方素材规格
5.3 URL 要求
- 仅接受公网
http://或https://地址;建议 HTTPS。 - 不接受 Base64 /
data:、oss://、本地路径、file://、localhost、私网 IP 或带用户名密码的 URL。 - 链接必须直接返回真实素材,不能依赖浏览器 Cookie、登录态或额外的自定义鉴权 Header。本文接口不负责上传本地文件。
- 可以使用有效的签名 URL。有效期应覆盖提交时的素材检查、排队及生成读取;提交后不要删除、覆盖素材或修改 URL 内容。
- 引用视频应可被正常读取和解析,支持 HTTP Range 有助于时长探测。地址不可访问、已过期或无法解析时,可能在创建阶段返回
400 InvalidParameter。
5.4 组合规则与引用顺序
首帧 / 首尾帧模式只允许 first_frame、last_frame,不能混入任何参考图片、视频、音频、文件或网页。需要图片与音频组合时,请使用 reference_image + reference_audio。
参考模式中,图片、视频、音频可以组合,file 和 link 最多二选一。平台保留 media 数组顺序:提示词中的“图1”“图2”按参考图片出现顺序编号,“视频1”“视频2”和“音频1”“音频2”各自独立编号。此编号不使用整个数组的绝对下标。官方素材使用说明
5.5 时长约束
无输入参考视频时:
2 ≤ parameters.duration ≤ 30,且为整数存在输入参考视频时,同时满足:
每段输入视频时长 ∈ [1, 15] 秒
输入视频总时长 ≤ 15 秒
输入视频总时长 + parameters.duration ≤ 30 秒参考音频的时长约束独立计算,不计入上述“输入视频总时长”。不要在请求中自行添加输入视频时长字段,平台会读取素材实际时长。
视频延长场景中,duration 表示最终生成视频的总时长。例如原视频 5 秒、希望向后延长 2 秒,应传 duration: 7;该请求的输入与输出合计为 12 秒。官方延长时长说明
6. 常见场景请求示例
以下均为创建接口的完整 JSON 请求体,Header 与快速开始相同。https://media.example.com/... 为素材占位地址,调用前必须替换为自己真实可访问的 URL。
6.1 文生视频:竖屏有声视频
{
"model": "wan3.0-video-prime",
"input": {
"prompt": "竖屏短片:雨后街角的咖啡店,店员推开木门,镜头缓慢推进,伴随轻柔爵士乐与雨滴声。"
},
"parameters": {
"resolution": "720P",
"ratio": "9:16",
"duration": 8,
"audio": true,
"prompt_extend": true,
"watermark": false
}
}6.2 首帧生视频
{
"model": "wan3.0-video",
"input": {
"prompt": "以首帧为起点,小船缓缓驶向湖心,镜头轻微拉远,保持自然光线与人物外观。",
"media": [
{"type": "first_frame", "url": "https://media.example.com/first_frame.jpg"}
]
},
"parameters": {
"resolution": "1080P",
"ratio": "adaptive",
"duration": 5
}
}6.3 首尾帧生视频
{
"model": "wan3.0-video-prime",
"input": {
"prompt": "镜头从关闭的花苞平稳推进到盛开的花朵,展现连续自然的绽放过程。",
"media": [
{"type": "first_frame", "url": "https://media.example.com/flower_start.jpg"},
{"type": "last_frame", "url": "https://media.example.com/flower_end.jpg"}
]
},
"parameters": {
"resolution": "720P",
"ratio": "adaptive",
"duration": 6
}
}6.4 多模态参考
{
"model": "wan3.0-video",
"input": {
"prompt": "图1中的人物走进图2中的房间,动作节奏参考视频1,配乐氛围参考音频1。",
"media": [
{"type": "reference_image", "url": "https://media.example.com/character.jpg"},
{"type": "reference_video", "url": "https://media.example.com/motion.mp4"},
{"type": "reference_image", "url": "https://media.example.com/room.jpg"},
{"type": "reference_audio", "url": "https://media.example.com/music.mp3"}
]
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 8,
"audio": true
}
}此例中 character.jpg 是“图1”,room.jpg 是“图2”,motion.mp4 是“视频1”。请确保参考视频与音频分别满足时长限制,且输入视频总时长加 8 秒不超过 30 秒。
6.5 文档 / 网页生视频
{
"model": "wan3.0-video-prime",
"input": {
"prompt": "根据产品资料制作一条产品介绍视频,依次展示核心功能、使用场景与产品外观。",
"media": [
{"type": "file", "url": "https://media.example.com/product.pdf"}
]
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 10,
"prompt_extend": true
}
}网页场景将素材替换为 {"type": "link", "url": "https://www.example.com/product"},其余结构不变。网页地址同样为占位示例,需替换;不要同时提交 file 与 link。
6.6 视频编辑
{
"model": "wan3.0-video",
"input": {
"prompt": "将视频1改为温暖的手绘动画风格,保留原有构图、主体与动作。",
"media": [
{"type": "reference_video", "url": "https://media.example.com/source_5s.mp4"}
]
},
"parameters": {
"resolution": "720P",
"ratio": "adaptive",
"duration": 5
}
}若希望输出时长与输入相同,请先确定输入时长并填写符合约束的整数 duration。平台不支持用 -1 自动保持原片时长。
6.7 视频延长
{
"model": "wan3.0-video-prime",
"input": {
"prompt": "将视频1向后延长2秒,人物继续向前行走,镜头平稳跟随,保持场景和光线连贯。",
"media": [
{"type": "reference_video", "url": "https://media.example.com/source_5s.mp4"}
]
},
"parameters": {
"resolution": "720P",
"ratio": "adaptive",
"duration": 7
}
}此例假设输入视频确实为 5 秒,目标输出为 7 秒,计费秒数为 5 + 7 = 12 秒。提示词应明确说明向前或向后延长的意图。
7. 查询任务与获取结果
GET /api/v1/tasks/{task_id}
Authorization: Bearer <创建任务时使用的同一平台 API Key>7.1 请求参数与查询范围
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
task_id | Path | string | 是 | 创建接口返回的平台标准小写 UUID,包含连字符 |
Authorization | Header | string | 是 | 创建该任务时使用的同一 API Key |
Accept-Language | Header | string | 否 | 错误提示语言 |
查询不需要请求体,也不需要 X-DashScope-Async。任务按用户、创建任务的 API Key 及接口协议隔离:即使属于同一个账户,更换 API Key 也无法读取原 Key 的任务,返回 HTTP 404。格式错误的任务 ID 返回 HTTP 400。
查询返回平台已记录的任务状态;提高查询频率不会加快生成。任务处理、结果确认和文件交付需要时间,请持续按合理间隔轮询。
7.2 任务状态
output.task_status | 含义 | 客户端处理 |
|---|---|---|
PENDING | 平台已受理,等待提交或上游排队 | 等待后查询 |
RUNNING | 正在生成,或结果交付 / 终态处理尚未完成 | 等待后查询,不重复创建 |
SUCCEEDED | 生成成功且结果已可交付 | 读取 video_url,保存结果,结束轮询 |
FAILED | 已确认任务失败 | 读取 output.code / output.message,结束轮询,按原因处理 |
CANCELED | 任务已取消 | 结束轮询;此状态不代表平台提供主动取消接口 |
UNKNOWN | 结果或交付需要核查 | 结束高频轮询,保留任务与请求 ID 联系平台;不要据此自动重提 |
状态可能跳跃,例如第一次查询就得到 SUCCEEDED,客户端不要依赖必须先看到 RUNNING。
查询本身成功时,上述状态均返回 HTTP 200。 必须同时判断 HTTP 状态码和 output.task_status,不能仅凭 HTTP 200 认定视频已生成。
7.3 成功响应示例
以下为结构示例,任务 ID、时间、URL 和用量均为示意,真实字段以实际响应为准:
{
"output": {
"task_id": "b5836ed1-f195-441d-990b-0eaec3b9f349",
"task_status": "SUCCEEDED",
"submit_time": "2026-11-07 10:00:00.000",
"scheduled_time": "2026-11-07 10:00:02.000",
"end_time": "2026-11-07 10:03:10.000",
"orig_prompt": "清晨的海边,一只金毛犬沿着沙滩奔跑,镜头平稳跟随,阳光温暖,配有自然海浪声。",
"video_url": "https://media.example.com/generated/video.mp4"
},
"usage": {
"video_count": 1,
"duration": 5.0,
"input_video_duration": 0.0,
"output_video_duration": 5.0,
"fps": 30,
"SR": 720,
"ratio": "16:9"
},
"request_id": "91472d54-521d-4473-8e1a-97a612609928"
}7.4 响应字段
| 字段 | 类型 | 返回条件与含义 |
|---|---|---|
output | object | 查询成功时返回 |
output.task_id | string | 平台任务 UUID,与提交所得 ID 相同 |
output.task_status | string | 当前任务状态 |
output.submit_time | string | 可选,上游提供的提交时间,格式 YYYY-MM-DD HH:mm:ss.SSS |
output.scheduled_time | string | 可选,上游提供的执行时间,格式同上 |
output.end_time | string | 可选,上游提供的结束时间,格式同上 |
output.orig_prompt | string | 成功时按可用信息返回原始提示词;仅素材输入时可能省略 |
output.video_url | string | SUCCEEDED 时返回已交付的视频地址 |
output.code | string | FAILED 或 UNKNOWN 时的错误 / 核查代码 |
output.message | string | 对应的安全、本地化提示 |
usage | object | 成功且存在有效用量时返回;子字段也可能省略 |
usage.video_count | integer | 输出数量,返回时为 1 |
usage.duration | number | 实际输入视频时长与输出视频时长之和,单位秒 |
usage.input_video_duration | number | 实际输入视频总时长,单位秒,无输入视频时可为 0 |
usage.output_video_duration | number | 实际输出视频时长,单位秒 |
usage.fps | integer | 实际输出帧率 |
usage.SR | integer | 输出分辨率档位数值,例如 720;注意字段名为大写 SR |
usage.ratio | string | 实际输出宽高比,例如 16:9 |
request_id | string | 本次查询的请求 ID |
时间字段不带时区偏移,不应自行假设为 UTC;需要跨时区排序时,建议同时保存自己系统的请求与接收时间。实际用量采用 JSON 数值,客户端应允许小数,不要强转为整数。可选字段缺失时应正常处理。
7.5 失败与待核查响应
已确认内容审核失败,HTTP 200:
{
"output": {
"task_id": "b5836ed1-f195-441d-990b-0eaec3b9f349",
"task_status": "FAILED",
"code": "DataInspectionFailed",
"message": "内容未通过审核,请调整输入后重试"
},
"request_id": "91472d54-521d-4473-8e1a-97a612609928"
}结果待核查,HTTP 200:
{
"output": {
"task_id": "b5836ed1-f195-441d-990b-0eaec3b9f349",
"task_status": "UNKNOWN",
"code": "TaskStatusUnknown",
"message": "暂无法确认任务结果,请保留任务编号以便核查"
},
"request_id": "91472d54-521d-4473-8e1a-97a612609928"
}7.6 视频下载与保存
只在 SUCCEEDED 后使用 output.video_url。平台会完成生成文件交付后再公开成功结果,交付过程中可能继续显示 RUNNING。
curl --location --fail \
'替换为响应中的完整 video_url' \
--output generated_video.mp4下载请求不要携带平台 API Key。文件地址与 API 地址可能使用不同域名;不要自行拼接存储路径、添加扩展名或重写 URL 查询参数。
建议在成功后及时下载并保存在自己的存储中。平台交付地址不直接沿用百炼临时产物地址,不能套用原厂“视频链接和任务 ID 均为 24 小时”的规则,也不将平台地址视为永久保存承诺;具体保留政策以平台公告或服务约定为准。
8. 提交异常与查询重试
- 提交成功后保存
task_id,后续使用该 ID 查询任务。 - 如果创建请求超时、断开连接或返回结果不明确,先核实任务是否已受理,再决定是否重新提交。记录请求时间及可获取的
request_id,便于排查。自动重复提交可能创建新任务并产生费用。 - 查询请求遇到
429、500、502、503或临时网络故障时,可对同一task_id做有限重试,例如等待 2、4、8 秒,并加入随机延迟。达到客户端等待上限后,保留task_id供稍后查询。 - 任务状态为
UNKNOWN时,保留任务 ID 和请求 ID,联系平台核查执行和交付结果。
9. 错误处理
9.1 HTTP 请求错误
请求未成功完成时,响应使用顶层错误格式:
{
"code": "InvalidApiKey",
"message": "API Key 无效或已过期",
"request_id": "33c511a7-d546-49dd-bb06-6405b5c51873"
}以上 message 为示意,实际内容随错误原因和语言变化。客户端应根据 HTTP 状态码与 code 分支,不要依赖固定文案匹配。
| HTTP | code | 常见原因 | 建议处理 |
|---|---|---|---|
400 | InvalidParameter | JSON / 参数类型错误、缺字段、非法枚举、素材组合或时长不符、素材无法读取、模型不可用等 | 检查请求和素材;修正后作为新业务请求提交 |
401 | InvalidApiKey | 平台 Key 缺失、格式错误、已停用或过期 | 检查 Key,不盲目重试 |
403 | AccessDenied | 用户被停用、IP 不被允许、模型未授权、余额或 Key 额度不足 | 调整账户、授权或额度 |
403 | UnsupportedOperation | duration: -1 | 改用 2~30 的整数,并检查总时长 |
404 | NotFound | 任务不存在、跨用户 / 跨 Key 查询,或任务不属于本协议 | 使用原 Key 和本接口返回的任务 ID |
405 | UnsupportedOperation | HTTP Method 不正确 | 按接口要求使用 POST 或 GET |
413 | RequestEntityTooLarge | JSON 正文超过 65,535 字节 | 缩短正文或 URL,素材使用公网链接 |
429 | Throttling | 触发请求速率、RPM 或并发限制 | 降低频率,减少并行任务 |
500 | InternalError | 平台内部异常 | 查询可有限重试,持续发生时提供请求 ID |
503 | ServiceUnavailable | 服务依赖异常、模型维护、暂无可用渠道等 | 查询可退避重试,持续发生时联系平台 |
上游生成调用在平台受理后异步执行,因此生成过程的问题通常通过任务状态返回,并不一定在创建请求中同步返回 HTTP 错误。任务查询的语言化提示位于 output.message;HTTP 请求错误的提示位于顶层 message。
9.2 任务错误与核查代码
| 任务状态 | output.code | 含义与处理 |
|---|---|---|
FAILED | DataInspectionFailed | 内容未通过审核,调整提示词或素材后再创建新任务 |
FAILED | ServiceUnavailable | 已确认生成失败;可在确认结果与账户记录后按需创建新任务 |
UNKNOWN | TaskStatusUnknown | 无法确认执行结果;保留任务 ID 以便核查,不自动重提 |
UNKNOWN | DeliveryNeedsReview | 视频已生成,交付需要核查;不要重新创建相同任务 |
CANCELED 可能不附带 code 或 message,应直接按状态处理。平台返回经过安全处理的公开错误,不透传上游原始错误全文;排障时请提供模型名、任务 ID、请求 ID、发生时间和 HTTP 状态,不要提供完整 API Key。
10. 计费与调用限制
10.1 计费口径
当前接口在任务受理时按确定的输出规格计算费用并一次扣款:
计费秒数 = 输入参考视频实际总时长 + 请求输出时长
费用基础 = 计费秒数 × 对应模型、输出分辨率的每秒单价
实际扣减积分按平台当时的售价及积分换算规则计算| 场景 | 输入视频总时长 | 请求输出时长 | 计费秒数 |
|---|---|---|---|
| 纯文生视频 / 图片参考 | 0 秒 | 5 秒 | 5 秒 |
| 视频参考 | 10.32 秒 | 7 秒 | 17.32 秒 |
| 5 秒原片延长至 7 秒 | 5 秒 | 7 秒 | 12 秒 |
输入视频的小数时长按实际值参与计算,不先向上取整成整秒。提示词、图片、音频、文件或网页不额外增加“输入视频秒数”。当前单价按模型和输出分辨率选择,audio 开关不改变所选单价。
具体售价以平台模型价格展示为准,两个模型及不同分辨率可能采用不同单价。成功任务保留受理时的报价,查询返回的 usage 用于展示实际用量,不据此重新补扣或退还时长差额。
已确认失败或取消时,平台按原扣款处理退款;退款处理完成前,查询状态可能仍为 RUNNING。请求超时、客户端退出、UNKNOWN 或交付异常不能直接视为已失败 / 已退款,需以核查与账户记录为准。
10.2 限制概览
| 项目 | 当前约束 |
|---|---|
| 请求体 | UTF-8 JSON,最多 65,535 字节 |
| 每次生成数量 | 1 个视频,无 n 参数 |
| 输出分辨率 | 480P / 720P / 1080P,还需符合当前模型配置 |
| 输出时长 | 2~30 秒整数,默认 5 秒,不接受 -1 |
| 媒体项数 | 合计不超过 20,并符合各分类上限 |
| 输入视频 | 最多 5 段,每段 1~15 秒,总计不超过 15 秒 |
| 输入视频 + 输出 | 总计不超过 30 秒 |
| 输入音频 | 最多 5 段,每段 1~15 秒,总计不超过 15 秒 |
| 请求速率 / RPM / 并发 | 由账户权益、API Key 权限及模型实际限制共同决定;以平台展示或服务约定为准 |
| 结果查询建议 | 10~15 秒一次,遇限流退避 |
同一账户的多个 API Key 可能共享账户级请求与并发限制,不应通过切换 Key 绕过限制。本文不沿用百炼的默认 RPS 或免费额度作为平台承诺。
11. Python 完整调用示例
适用 Python 3.11+,示例客户端使用 requests。安装客户端依赖并设置环境变量:
python -m pip install requests
export API_BASE_URL="https://openapi.yhsapi.com"
export PLATFORM_API_KEY="替换为平台签发的完整 API Key"示例发送一次创建请求,随后轮询任务状态并流式下载视频。查询遇到临时故障时会有限重试,轮询等待上限设为 30 分钟。
import json
import os
import random
import time
import requests
BASE_URL = os.getenv("API_BASE_URL", "https://openapi.yhsapi.com").rstrip("/")
API_KEY = os.environ["PLATFORM_API_KEY"]
RETRYABLE = {429, 500, 502, 503}
session = requests.Session()
def request_json(method, path, *, body=None):
submitting = method == "POST"
attempts = 1 if submitting else 4
headers = {
"Authorization": f"Bearer {API_KEY}",
"Accept-Language": "zh-CN",
}
if submitting:
headers.update({
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
})
for attempt in range(attempts):
can_retry = attempt + 1 < attempts
try:
response = session.request(
method, BASE_URL + path, headers=headers, data=body,
timeout=(10, 360 if submitting else 30),
allow_redirects=False,
)
except (requests.Timeout, requests.ConnectionError):
if submitting:
raise RuntimeError("提交结果未确认,请先核实任务是否已受理") from None
if not can_retry:
raise RuntimeError("查询请求失败,请保留任务 ID 稍后查询") from None
else:
if can_retry and response.status_code in RETRYABLE:
response.close()
else:
try:
data = response.json()
except ValueError:
raise RuntimeError(
f"响应不是 JSON,HTTP {response.status_code},"
f"request_id={response.headers.get('X-Request-ID', '')}"
) from None
finally:
response.close()
if response.status_code != 200:
raise RuntimeError(
f"HTTP {response.status_code}: {data.get('code')} / "
f"{data.get('message')}; request_id={data.get('request_id')}"
)
return data
time.sleep(2 ** (attempt + 1) + random.random())
payload = {
"model": "wan3.0-video-prime",
"input": {"prompt": "黄昏的山间湖泊,镜头缓慢掠过水面,配有自然风声。"},
"parameters": {"resolution": "720P", "ratio": "16:9", "duration": 5},
}
body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
try:
submitted = request_json(
"POST", "/api/v1/services/aigc/video-generation/video-synthesis",
body=body,
)
task_id = submitted["output"]["task_id"]
print("任务 ID(请保存):", task_id)
# 生产环境:将 task_id 关联到原业务单号。
deadline = time.monotonic() + 30 * 60
while True:
result = request_json("GET", f"/api/v1/tasks/{task_id}")
output = result["output"]
status = output["task_status"]
if status == "SUCCEEDED":
# 下载使用独立请求,不向素材域名发送平台 Authorization。
with requests.get(
output["video_url"], stream=True, timeout=(10, 120)
) as video:
video.raise_for_status()
with open("generated_video.mp4", "wb") as target:
for chunk in video.iter_content(chunk_size=1024 * 1024):
if chunk:
target.write(chunk)
print("已保存 generated_video.mp4;usage:", result.get("usage", {}))
break
if status in {"FAILED", "CANCELED", "UNKNOWN"}:
raise RuntimeError(
f"任务状态 {status}: {output.get('code', '')} / "
f"{output.get('message', '')}; task_id={task_id}; "
f"request_id={result['request_id']}"
)
if status not in {"PENDING", "RUNNING"}:
raise RuntimeError(f"未识别的状态 {status},请保留 task_id={task_id}")
if time.monotonic() >= deadline:
raise TimeoutError(f"客户端等待结束,任务可能仍在运行:{task_id}")
time.sleep(12 + random.random() * 3)
finally:
session.close()提交结果不明确时,先核实任务是否已受理。已拿到 task_id 时,使用该 ID 恢复查询。下载失败可重试下载或重新查询视频地址。
12. Node.js 完整调用示例
适用 Node.js 20+,使用内置 fetch,无需额外安装包。先设置与快速开始相同的 API_BASE_URL、PLATFORM_API_KEY,保存为 .mjs 后执行。
import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import { setTimeout as sleep } from "node:timers/promises";
const baseURL = (process.env.API_BASE_URL ?? "https://openapi.yhsapi.com")
.replace(/\/+$/, "");
const apiKey = process.env.PLATFORM_API_KEY;
if (!apiKey) throw new Error("请设置 PLATFORM_API_KEY");
const retryable = new Set([429, 500, 502, 503]);
async function requestJSON(method, path, body) {
const submitting = method === "POST";
const attempts = submitting ? 1 : 4;
const headers = {
Authorization: `Bearer ${apiKey}`,
"Accept-Language": "zh-CN",
};
if (submitting) {
Object.assign(headers, {
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
});
}
for (let attempt = 0; attempt < attempts; attempt++) {
const canRetry = attempt + 1 < attempts;
let response;
try {
response = await fetch(baseURL + path, {
method, headers, body, redirect: "error",
signal: AbortSignal.timeout(submitting ? 360_000 : 30_000),
});
} catch {
if (submitting) {
throw new Error("提交结果未确认,请先核实任务是否已受理");
}
if (!canRetry) {
throw new Error("查询请求失败,请保留任务 ID 稍后查询");
}
}
if (response) {
if (!canRetry || !retryable.has(response.status)) {
const data = await response.json().catch(() => {
throw new Error(
`响应不是 JSON,HTTP ${response.status};` +
`request_id=${response.headers.get("X-Request-ID") ?? ""}`
);
});
if (response.status !== 200) {
throw new Error(
`HTTP ${response.status}: ${data.code} / ${data.message}; ` +
`request_id=${data.request_id}`
);
}
return data;
}
await response.body?.cancel();
}
await sleep(2 ** (attempt + 1) * 1000 + Math.random() * 1000);
}
}
const body = JSON.stringify({
model: "wan3.0-video-prime",
input: { prompt: "清晨的森林,阳光穿过树叶,镜头缓慢前进,配有鸟鸣声。" },
parameters: { resolution: "720P", ratio: "16:9", duration: 5 },
});
const submitted = await requestJSON(
"POST", "/api/v1/services/aigc/video-generation/video-synthesis",
body
);
const taskId = submitted.output.task_id;
console.log("任务 ID(请保存):", taskId);
const deadline = Date.now() + 30 * 60 * 1000;
while (true) {
const result = await requestJSON("GET", `/api/v1/tasks/${taskId}`);
const output = result.output;
if (output.task_status === "SUCCEEDED") {
// 不向视频下载域名发送平台 Authorization。
const video = await fetch(output.video_url, {
signal: AbortSignal.timeout(120_000),
});
if (!video.ok || !video.body) throw new Error("下载失败,请保留任务 ID 重试下载");
await pipeline(
Readable.fromWeb(video.body), createWriteStream("generated_video.mp4")
);
console.log("已保存 generated_video.mp4;usage:", result.usage ?? {});
break;
}
if (["FAILED", "CANCELED", "UNKNOWN"].includes(output.task_status)) {
throw new Error(
`任务状态 ${output.task_status}: ${output.code ?? ""} / ` +
`${output.message ?? ""}; task_id=${taskId}; request_id=${result.request_id}`
);
}
if (!["PENDING", "RUNNING"].includes(output.task_status)) {
throw new Error(`未识别的状态,请保留 task_id=${taskId}`);
}
if (Date.now() >= deadline) {
throw new Error(`客户端等待结束,任务可能仍在运行:${taskId}`);
}
await sleep(12_000 + Math.random() * 3000);
}示例等待上限与网络超时可按业务调整。异常退出后,如已取得任务 ID,请用它恢复查询。若提交结果仍不明确,请先核实任务是否已受理。
13. 从百炼接口迁移
平台沿用百炼视频生成的 model / input / parameters 请求结构与 output / usage / request_id 响应结构,公开字段经过平台校验与安全处理。对照百炼原生 API 参考迁移时,请注意下表。
| 项目 | 本平台约定 |
|---|---|
| API 地址 | 使用 https://openapi.yhsapi.com,保留本文规定的完整原生接口路径 |
| API Key | 使用平台签发的 LT-... Key |
| Workspace / 地域 | 调用方无需填写 Workspace ID 或地域,平台负责渠道配置 |
X-DashScope-Async | 创建时仍须为 enable |
| 任务 ID | 返回并查询平台 UUID,不使用阿里云控制台任务 ID |
| 查询身份 | 必须使用创建该任务的同一平台 Key |
| 智能时长 | 暂不支持 duration: -1;省略时长为 5 秒 |
| 素材地址 | 仅支持公网 HTTP(S),不支持 Base64 或 oss:// |
| 计费 | 使用平台售价、积分与本文计费口径 |
| 结果地址 | 成功交付后返回平台视频地址;不要套用上游地址及其有效期 |
UNKNOWN | 表示结果 / 交付待核查;不存在或无权限的本地任务使用 HTTP 404 |
| HTTP 错误信封 | 顶层 code、message、request_id;不是 Web 业务的 code / msg / data,也不是 OpenAI 的 error 对象 |
| SDK | 本文提供原生 HTTP 示例;不能仅替换 OpenAI SDK 的 Base URL 调用聊天接口来生成视频 |
| 其他任务管理能力 | 本文仅开放创建和单任务查询;未开放取消、批量查询、任务列表、回调通知或 SSE 流式视频输出 |
不要直接将原厂全部可选字段、SDK 方法或其他模型参数套用到本接口。需要接入其他能力时,请先核对平台是否已提供对应接口。
14. 常见问题
为什么创建成功只得到任务 ID,没有视频地址?
创建接口只负责受理。使用返回的 task_id 调用查询接口,直到 SUCCEEDED 后再获取 video_url。
同一账户换一个 API Key,为什么查不到任务?
查询权限绑定创建时的 Key。请恢复原 Key;原 Key 已不可用时,保留任务编号联系平台处理。
只想生成静音视频,应该怎么传?
在 parameters 中传 "audio": false,使用 JSON 布尔值,不要传字符串 "false"。
能直接提交本地文件或 Base64 吗?
不能。先将素材保存到公网可访问的存储,再将其 HTTP(S) 地址放入 input.media。签名链接需在素材读取完成前保持有效。
想让输出时长自动匹配素材,能传 -1 吗?
暂不支持。需要传确定的整数输出时长;不传时固定使用 5 秒,不会自动匹配输入视频。
为什么输入 10.32 秒、输出 7 秒,计费不是 7 秒?
当前接口将输入参考视频与输出视频一起按秒计费,因此计费秒数为 17.32。实际单价按所选模型和输出分辨率确定。
UNKNOWN 后可以立刻重提或视为退款吗?
不可以直接这样判断。它表示执行结果或文件交付尚待核查,请保留 task_id 和 request_id 联系平台,避免产生重复任务与费用。
可以通过取消请求或停止查询来取消生成吗?
不能。关闭连接或停止轮询不等于取消平台已受理的任务;本文也未提供主动取消接口。
视频地址下载失败,需要重新生成吗?
先重试下载或使用原任务 ID 重新查询,并核对网络和链接有效性;不要直接重复提交生成任务。持续失败时提供任务 ID 联系平台。

