万相 Wan 3.0 API

01快速开始

异步任务：提交拿 id，轮询到 completed 后取成片。

端点别用错。本系列走 POST /v1/videos，不能用 /v1/chat/completions —— 用对话接口调会直接 404。

Base URL: https://www.salpx.com/v1
鉴权: Authorization: Bearer <SalpX Token>
提交任务: POST /v1/videos
查询状态: GET /v1/videos/{id}
模型名: wan3.0-480p、wan3.0-720p、wan3.0-1080p
线路（可选）: line：kd / bl / hm / rh / rhp，首选线路，不传为 kd
自动换线（可选）: auto_switch：默认 true；传 false 则只走首选线路、失败不换线（见 02 节）
必填参数: model、prompt、duration（整数秒）
客户端超时: 建议轮询总超时 ≥ 900 秒

分辨率由模型名决定，不用传。请求体里的 size / resolution 会被改成模型名对应的档位。

02模型与价格

按秒计费，单价 × 计费秒数 = 总价。价格单位为人民币元 / 秒。

模型名	分辨率	kd	bl	hm	rh	rhp（高速）
`wan3.0-480p`	480P	¥0.21 / 秒	¥0.21 / 秒	¥0.28 / 秒	¥0.32 / 秒	¥0.65 / 秒
`wan3.0-720p`	720P	¥0.42 / 秒	¥0.42 / 秒	¥0.56 / 秒	¥0.63 / 秒	¥1.29 / 秒
`wan3.0-1080p`	1080P	¥0.83 / 秒	¥0.84 / 秒	¥1.11 / 秒	¥1.26 / 秒	¥2.57 / 秒

首选线路 line：请求体顶层加 "line": "kd"（或 bl、hm、rh、rhp），不传默认 kd。rhp 是万相 3.0 高速版，出片更快；rh、rhp 不支持首帧 / 尾帧（first_frame / last_frame），只能用参考图 / 视频 / 音频与文档 / 网页素材。

自动换线 auto_switch（默认开）：首选线路提交失败或生成失败，会按 kd → bl → hm → rh → rhp 的顺序（从首选线路往后，再回到前面）自动换下一条线路重做，按实际出片的线路单价计费（换线时多退少补）。传 "auto_switch": false 则只走首选线路，失败直接报错、全额退款，扣费一定是首选线路的单价。

各线路请求参数和返回格式完全相同（rhp 为高速版，其余为标准版）。返回内容和使用日志里的 model 都是 wan3.0-*，日志里会注明实际线路。

参考图、参考音频、文档 / 网页素材不加价；有声 / 无声同价。kd、hm 线路只按出片秒数计费，参考视频不计费；bl、rh、rhp 线路的参考视频计费见下一节。

03计费方式

提交成功即预扣；任务失败或超时自动全额退回。

情形	计费公式
不带参考视频	单价 × 出片秒数
带参考视频（`reference_video`），kd / hm 线路	单价 × 出片秒数（参考视频不计费）
带参考视频（`reference_video`），bl / rh / rhp 线路	单价 ×（出片秒数 + 参考视频总秒数）

bl、rh、rhp 线路：参考视频的秒数按出片同价计费（上游规则）。提交时还不知道参考视频多长，先按参考视频上限 15 秒预扣；任务完成后按上游返回的实际参考视频秒数（不足 1 秒按 1 秒）多退少补。

例：wan3.0-720p 走 bl 线路，出片 5 秒、带一段 6 秒参考视频 → 提交时预扣 ¥0.42 × (5 + 15) = ¥8.40，完成后按 ¥0.42 × (5 + 6) = ¥4.62 结算，退回 ¥3.78。

04素材规则

素材 `type`	上限	说明
`first_frame`	1	首帧（只传首帧即首帧图生视频）
`last_frame`	1	尾帧，配合首帧做首尾帧
`reference_image`	10	参考图，按顺序在 prompt 里称「图1」「图2」…
`reference_video`	5	参考视频，总时长 ≤ 15 秒，称「视频1」…（按秒计费，见 03 节）
`reference_audio`	5	参考音频，总时长 ≤ 15 秒，称「音频1」…
`file`	1	文档生视频（pdf / docx / pptx / xlsx / txt / md 等，≤ 100MB、≤ 50 页）
`link`	1	公开网页生视频（无需登录的页面）

组合规则：first_frame / last_frame 不能和 reference_*、file、link 混用；file 和 link 二选一，可与 reference_* 组合；三种 reference_* 之间可自由组合。

素材	格式与限制
图片	JPEG / PNG（不含透明通道）/ BMP / WEBP；单边 240 – 8000 像素，长宽比 ≤ 8:1，≤ 20MB
视频	mp4 / mov；单段 1 – 15 秒，帧率 ≥ 16fps，单边 240 – 4096 像素，≤ 100MB
音频	wav / mp3；单段 1 – 15 秒，≤ 15MB
出片时长	2 – 30 秒整数；带参考视频时参考视频秒数 + 出片秒数 ≤ 30

媒体地址必须是公网可直接下载的 URL，也可以用 data:{MIME};base64,...。私有云链接、需要登录或带防盗链的地址会导致任务失败。

05提交任务

5.1 请求格式

文本放顶层 prompt，素材放 metadata.media，每项是 {"type": ..., "url": ...}，type 取值见第 04 节。

参数	位置	说明
`duration`	顶层	必填，出片秒数，2 – 30 整数
`ratio`	顶层	可选：`adaptive`（默认）、`16:9`、`9:16`、`4:3`、`3:4`、`1:1`、`21:9`
`input_reference`	顶层	可选，首帧图 URL 的简写，等同 `metadata.media` 里一项 `first_frame`
`metadata.parameters.audio`	metadata	是否生成声音，默认 `true`，同价
`metadata.parameters.seed`	metadata	随机种子，0 – 2147483647
`metadata.parameters.prompt_extend`	metadata	提示词智能改写，默认 `true`（文档 / 网页生视频必须为 `true`）

5.2 纯文生视频

curl

curl -X POST https://www.salpx.com/v1/videos \
  -H "Authorization: Bearer $SALPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-720p",
    "line": "kd",
    "auto_switch": false,
    "prompt": "一只橘猫在窗台上伸懒腰，阳光洒进来，镜头缓慢推近",
    "duration": 5,
    "ratio": "16:9"
  }'

5.3 首帧 / 首尾帧

curl

curl -X POST https://www.salpx.com/v1/videos \
  -H "Authorization: Bearer $SALPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-720p",
    "prompt": "从第一张图自然过渡到第二张图",
    "duration": 5,
    "metadata": {
      "media": [
        {"type": "first_frame", "url": "https://your-cdn.com/first.png"},
        {"type": "last_frame",  "url": "https://your-cdn.com/last.png"}
      ]
    }
  }'

只做首帧图生视频时，也可以直接用顶层 "input_reference": "https://your-cdn.com/first.png"。

5.4 多素材参考（参考图 + 参考视频 + 参考音频）

curl

curl -X POST https://www.salpx.com/v1/videos \
  -H "Authorization: Bearer $SALPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-1080p",
    "prompt": "图1的角色跟着视频1的动作跳舞，节奏贴合音频1",
    "duration": 8,
    "ratio": "16:9",
    "metadata": {
      "media": [
        {"type": "reference_image", "url": "https://your-cdn.com/char.png"},
        {"type": "reference_video", "url": "https://your-cdn.com/dance.mp4"},
        {"type": "reference_audio", "url": "https://your-cdn.com/bgm.mp3"}
      ]
    }
  }'

带了 reference_video：kd、hm 线路不加价；bl、rh、rhp 线路参考视频秒数也按单价计费，见第 03 节。

5.5 文档 / 网页生视频

curl

curl -X POST https://www.salpx.com/v1/videos \
  -H "Authorization: Bearer $SALPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-720p",
    "prompt": "把这份产品介绍做成一段 30 秒的宣传短片",
    "duration": 30,
    "metadata": {
      "media": [
        {"type": "file", "url": "https://your-cdn.com/intro.pdf"}
      ]
    }
  }'

网页生视频把 type 换成 link，url 填公开网页地址。

5.6 提交成功的响应

返回的是 SalpX 的任务 ID（task_ 开头），后续查询都用这个 ID。

200 response

{
  "id": "task_xeYwLgSoqtHyMKrKDeFcuzfkzFPRB8uu",
  "task_id": "task_xeYwLgSoqtHyMKrKDeFcuzfkzFPRB8uu",
  "object": "video",
  "model": "wan3.0-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1791960031
}

06轮询与取片

用 GET /v1/videos/{id} 轮询，建议间隔 15 秒。

curl · 查询状态

curl https://www.salpx.com/v1/videos/task_xeYwLgSoqtHyMKrKDeFcuzfkzFPRB8uu \
  -H "Authorization: Bearer $SALPX_KEY"

`status`	含义
`queued`	排队中
`in_progress`	生成中
`completed`	已完成，成片地址在 `metadata.url`
`failed`	失败，原因在 `error`；已自动退款

成片地址在 metadata.url，不在顶层。取值写法：resp["metadata"]["url"]。

200 response · completed

{
  "id": "task_xeYwLgSoqtHyMKrKDeFcuzfkzFPRB8uu",
  "object": "video",
  "model": "wan3.0-720p",
  "status": "completed",
  "progress": 100,
  "created_at": 1791960031,
  "completed_at": 1791960222,
  "metadata": {
    "url": "https://dashscope-xxxx.oss-accelerate.aliyuncs.com/xxxx.mp4?Expires=..."
  }
}

成片链接 24 小时后失效，请及时下载转存。

07错误处理

HTTP	典型信息	处理
404	bad response status code 404	用了 `/v1/chat/completions`，改用 `POST /v1/videos`
400	duration 不在允许范围	2 – 30 秒整数
400	prompt is required	`prompt` 必填
—	任务 `failed`：InvalidParameter … mutually exclusive	首尾帧和 `reference_*` / `file` / `link` 混用了，见 04 节组合规则
—	任务 `failed`：素材下载失败	媒体 URL 需公网可直接下载
403	token quota is not enough	余额不足（带参考视频的任务需按 15 秒上限预扣），充值或换令牌
503	No available channel	模型名拼错或令牌分组未开通

失败自动退款。提交被拒、上游失败、超时或任务进入 failed，已扣额度全额退回。