跳转到正文
阅读设置
万相

万相 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 白名单允许本次调用。

所有提交和查询请求均使用:

http
Authorization: Bearer <平台 API Key>

平台 Key 的格式为 LT- 加 32 位英文字母或数字。请使用平台实际签发的完整值;百炼 Key、官网登录 JWT 和其他平台的 Key 不能用于本接口。

请从服务端调用 API,通过环境变量或密钥管理服务保存 Key。不要将 Key 写入前端页面、移动端安装包、公开仓库或 URL 查询参数。

2.2 接口地址 ​

操作Method完整地址
创建视频任务POSThttps://openapi.yhsapi.com/api/v1/services/aigc/video-generation/video-synthesis
查询视频任务GEThttps://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 示例。

第一步:准备环境变量 ​

bash
export API_BASE_URL="https://openapi.yhsapi.com"
export PLATFORM_API_KEY="替换为平台签发的完整 API Key"

第二步:提交任务 ​

bash
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:

json
{
  "output": {
    "task_id": "b5836ed1-f195-441d-990b-0eaec3b9f349",
    "task_status": "PENDING"
  },
  "request_id": "33c511a7-d546-49dd-bb06-6405b5c51873"
}

立即保存 output.task_id。此响应表示平台已受理,最终生成结果需要继续查询。

第三步:查询状态 ​

将变量替换为实际返回的任务 ID,后续查询使用创建任务时的同一 API Key:

bash
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. 创建视频生成任务 ​

http
POST /api/v1/services/aigc/video-generation/video-synthesis

4.1 请求头 ​

Header必填值与说明
Authorization是Bearer <平台 API Key>
Content-Type是application/json
X-DashScope-Async是固定为小写字符串 enable
Accept-Language否zh-CN、zh-Hant、en,默认简体中文

4.2 顶层请求体 ​

字段类型必填说明
modelstring是wan3.0-video-prime 或 wan3.0-video,区分大小写
inputobject是提示词和素材输入
parametersobject否生成参数;省略时输出时长为 5 秒、分辨率为 1080P

4.3 input 对象 ​

字段类型必填说明
promptstring条件必填描述主体、动作、场景、镜头和声音;与 media 至少提供一项
mediaarray of object条件必填1~20 项有序素材;纯文生视频时省略,与 prompt 至少提供一项

提示词建议控制在 20,000 字符以内,较长内容应自行精简;不要依赖上游自动截断。平台还可能按模型配置限制长度,且整个 JSON 正文始终受 65,535 字节上限约束。官方提示词参数说明

media 每一项的结构:

字段类型必填说明
typestring是素材类型表中的一种
urlstring是可从公网直接读取的 HTTP(S) 素材地址;签名 URL 按原始内容使用

4.4 parameters 对象 ​

字段类型默认行为取值与说明
resolutionstring平台补为 1080P480P、720P、1080P,必须大写
ratiostring省略后使用模型默认的 adaptiveadaptive、21:9、16:9、4:3、1:1、3:4、9:16
durationinteger平台补为 5输出视频时长,单位秒,2~30 的整数;输入参考视频时还需满足总时长限制
audioboolean省略后使用模型默认的 truetrue 生成声音,false 不生成音轨
seedinteger省略后由模型随机生成-1 或 0~2147483647;-1 表示随机,相同种子也不保证结果完全一致
prompt_extendboolean省略后使用模型默认的 true是否智能改写提示词;使用 file 或 link 时不得设为 false,建议显式传 true
watermarkboolean省略后使用模型默认的 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_idstring平台任务 ID,标准小写 UUID;用于后续查询
output.task_statusstring提交成功固定返回 PENDING。当前执行状态请调用查询接口
request_idstring本次提交请求的追踪 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 时长约束 ​

无输入参考视频时:

text
2 ≤ parameters.duration ≤ 30,且为整数

存在输入参考视频时,同时满足:

text
每段输入视频时长 ∈ [1, 15] 秒
输入视频总时长 ≤ 15 秒
输入视频总时长 + parameters.duration ≤ 30 秒

参考音频的时长约束独立计算,不计入上述“输入视频总时长”。不要在请求中自行添加输入视频时长字段,平台会读取素材实际时长。

视频延长场景中,duration 表示最终生成视频的总时长。例如原视频 5 秒、希望向后延长 2 秒,应传 duration: 7;该请求的输入与输出合计为 12 秒。官方延长时长说明

6. 常见场景请求示例 ​

以下均为创建接口的完整 JSON 请求体,Header 与快速开始相同。https://media.example.com/... 为素材占位地址,调用前必须替换为自己真实可访问的 URL。

6.1 文生视频:竖屏有声视频 ​

json
{
  "model": "wan3.0-video-prime",
  "input": {
    "prompt": "竖屏短片:雨后街角的咖啡店,店员推开木门,镜头缓慢推进,伴随轻柔爵士乐与雨滴声。"
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "9:16",
    "duration": 8,
    "audio": true,
    "prompt_extend": true,
    "watermark": false
  }
}

6.2 首帧生视频 ​

json
{
  "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 首尾帧生视频 ​

json
{
  "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 多模态参考 ​

json
{
  "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 文档 / 网页生视频 ​

json
{
  "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 视频编辑 ​

json
{
  "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 视频延长 ​

json
{
  "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. 查询任务与获取结果 ​

http
GET /api/v1/tasks/{task_id}
Authorization: Bearer <创建任务时使用的同一平台 API Key>

7.1 请求参数与查询范围 ​

参数位置类型必填说明
task_idPathstring是创建接口返回的平台标准小写 UUID,包含连字符
AuthorizationHeaderstring是创建该任务时使用的同一 API Key
Accept-LanguageHeaderstring否错误提示语言

查询不需要请求体,也不需要 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 和用量均为示意,真实字段以实际响应为准:

json
{
  "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 响应字段 ​

字段类型返回条件与含义
outputobject查询成功时返回
output.task_idstring平台任务 UUID,与提交所得 ID 相同
output.task_statusstring当前任务状态
output.submit_timestring可选,上游提供的提交时间,格式 YYYY-MM-DD HH:mm:ss.SSS
output.scheduled_timestring可选,上游提供的执行时间,格式同上
output.end_timestring可选,上游提供的结束时间,格式同上
output.orig_promptstring成功时按可用信息返回原始提示词;仅素材输入时可能省略
output.video_urlstringSUCCEEDED 时返回已交付的视频地址
output.codestringFAILED 或 UNKNOWN 时的错误 / 核查代码
output.messagestring对应的安全、本地化提示
usageobject成功且存在有效用量时返回;子字段也可能省略
usage.video_countinteger输出数量,返回时为 1
usage.durationnumber实际输入视频时长与输出视频时长之和,单位秒
usage.input_video_durationnumber实际输入视频总时长,单位秒,无输入视频时可为 0
usage.output_video_durationnumber实际输出视频时长,单位秒
usage.fpsinteger实际输出帧率
usage.SRinteger输出分辨率档位数值,例如 720;注意字段名为大写 SR
usage.ratiostring实际输出宽高比,例如 16:9
request_idstring本次查询的请求 ID

时间字段不带时区偏移,不应自行假设为 UTC;需要跨时区排序时,建议同时保存自己系统的请求与接收时间。实际用量采用 JSON 数值,客户端应允许小数,不要强转为整数。可选字段缺失时应正常处理。

7.5 失败与待核查响应 ​

已确认内容审核失败,HTTP 200:

json
{
  "output": {
    "task_id": "b5836ed1-f195-441d-990b-0eaec3b9f349",
    "task_status": "FAILED",
    "code": "DataInspectionFailed",
    "message": "内容未通过审核,请调整输入后重试"
  },
  "request_id": "91472d54-521d-4473-8e1a-97a612609928"
}

结果待核查,HTTP 200:

json
{
  "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。

bash
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 请求错误 ​

请求未成功完成时,响应使用顶层错误格式:

json
{
  "code": "InvalidApiKey",
  "message": "API Key 无效或已过期",
  "request_id": "33c511a7-d546-49dd-bb06-6405b5c51873"
}

以上 message 为示意,实际内容随错误原因和语言变化。客户端应根据 HTTP 状态码与 code 分支,不要依赖固定文案匹配。

HTTPcode常见原因建议处理
400InvalidParameterJSON / 参数类型错误、缺字段、非法枚举、素材组合或时长不符、素材无法读取、模型不可用等检查请求和素材;修正后作为新业务请求提交
401InvalidApiKey平台 Key 缺失、格式错误、已停用或过期检查 Key,不盲目重试
403AccessDenied用户被停用、IP 不被允许、模型未授权、余额或 Key 额度不足调整账户、授权或额度
403UnsupportedOperationduration: -1改用 2~30 的整数,并检查总时长
404NotFound任务不存在、跨用户 / 跨 Key 查询,或任务不属于本协议使用原 Key 和本接口返回的任务 ID
405UnsupportedOperationHTTP Method 不正确按接口要求使用 POST 或 GET
413RequestEntityTooLargeJSON 正文超过 65,535 字节缩短正文或 URL,素材使用公网链接
429Throttling触发请求速率、RPM 或并发限制降低频率,减少并行任务
500InternalError平台内部异常查询可有限重试,持续发生时提供请求 ID
503ServiceUnavailable服务依赖异常、模型维护、暂无可用渠道等查询可退避重试,持续发生时联系平台

上游生成调用在平台受理后异步执行,因此生成过程的问题通常通过任务状态返回,并不一定在创建请求中同步返回 HTTP 错误。任务查询的语言化提示位于 output.message;HTTP 请求错误的提示位于顶层 message。

9.2 任务错误与核查代码 ​

任务状态output.code含义与处理
FAILEDDataInspectionFailed内容未通过审核,调整提示词或素材后再创建新任务
FAILEDServiceUnavailable已确认生成失败;可在确认结果与账户记录后按需创建新任务
UNKNOWNTaskStatusUnknown无法确认执行结果;保留任务 ID 以便核查,不自动重提
UNKNOWNDeliveryNeedsReview视频已生成,交付需要核查;不要重新创建相同任务

CANCELED 可能不附带 code 或 message,应直接按状态处理。平台返回经过安全处理的公开错误,不透传上游原始错误全文;排障时请提供模型名、任务 ID、请求 ID、发生时间和 HTTP 状态,不要提供完整 API Key。

10. 计费与调用限制 ​

10.1 计费口径 ​

当前接口在任务受理时按确定的输出规格计算费用并一次扣款:

text
计费秒数 = 输入参考视频实际总时长 + 请求输出时长
费用基础 = 计费秒数 × 对应模型、输出分辨率的每秒单价
实际扣减积分按平台当时的售价及积分换算规则计算
场景输入视频总时长请求输出时长计费秒数
纯文生视频 / 图片参考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。安装客户端依赖并设置环境变量:

bash
python -m pip install requests
export API_BASE_URL="https://openapi.yhsapi.com"
export PLATFORM_API_KEY="替换为平台签发的完整 API Key"

示例发送一次创建请求,随后轮询任务状态并流式下载视频。查询遇到临时故障时会有限重试,轮询等待上限设为 30 分钟。

python
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 后执行。

javascript
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 联系平台。