Topview API Console

Wan 3.0

文档更新于 2026-08-08

纯透传阿里云百炼 DashScope 异步任务协议，平台代管上游鉴权、并发与视频转存。

wan3.0-videowan3.0-video-intl

两个模型 ID 对应中国内地与海外两个服务区，同一个账号无需申请即可混用，由请求体的 model 决定走哪个服务区。两者能力与协议完全一致，仅单价与并发额度分开计算。

文档信息

适用环境：生产环境
Base URL：https://api.topview.ai
模型：wan3.0-video（国内）、wan3.0-video-intl（海外）
协议版本：阿里云百炼 DashScope 异步任务协议
更新时间：2026-08-08

本接口完整保持百炼 wan3.0-video 的请求与响应结构。你只需把 Base URL 换成 https://api.topview.ai、把 Authorization 换成 Topview API Key，官方示例即可直接运行，请求体与响应体无需做任何改动。

平台负责上游鉴权、任务归属隔离、积分扣费与视频转存，客户端无需持有百炼 API Key。

1. 接口概览

当前开放以下接口：

text

POST /api/v1/services/aigc/video-generation/video-synthesis
GET  /api/v1/tasks/{task_id}

路径与百炼官方完全一致。本期不开放批量查询与取消任务接口。

国内与海外共用同一个 Base URL 和同一个 API Key，走哪个服务区由请求体中的 model 决定，详见 4.3。

2. 鉴权与通用约定

使用 Topview 平台签发的 API Key：

http

Authorization: Bearer sk-你的TopviewAPIKey
Content-Type: application/json

通用约定：

请求与响应均采用 JSON。
客户端无需传递 Topview-Uid 或 Topview-Team-Id。
创建接口返回的 task_id 即后续查询所用的 ID，平台不做替换。
本接口无回调机制，原生协议不支持在请求体中指定回调地址，请使用轮询获取结果。
成功视频会转存到 Topview 存储，output.video_url 返回平台交付地址。
终态任务的查询结果由平台保存，不受上游 24 小时任务有效期限制。

3. 推荐调用流程

调用创建接口提交生成参数，注意必须带 X-DashScope-Async: enable 请求头。
保存响应中的 output.task_id。
通过查询接口轮询任务状态，建议间隔不低于 15 秒。
当 output.task_status 为 SUCCEEDED 时，从 output.video_url 获取视频。
当为 FAILED 时，读取 output.code 与 output.message。

4. 创建视频生成任务

4.1 接口

http

POST https://api.topview.ai/api/v1/services/aigc/video-generation/video-synthesis

4.2 请求头

头	必填	说明
`Content-Type`	是	固定 `application/json`
`Authorization`	是	`Bearer sk-你的TopviewAPIKey`
`X-DashScope-Async`	是	固定 `enable`。该协议仅支持异步调用，缺失会被上游拒绝

4.3 请求字段

model

类型：string
必填：是
取值：wan3.0-video 或 wan3.0-video-intl

wan3.0 是全能（All-in-One）模型，文生视频、首帧生视频、首尾帧生视频、参考生视频、文件生视频、网页生视频全部由同一个模型承载，不存在 t2v / i2v / turbo / plus 之类的分型号，生成模式由 input.media[].type 决定。

两个 model 的能力、请求结构与响应结构完全相同，区别只在服务区与单价：

model	服务区	说明
`wan3.0-video`	中国内地	与百炼官方模型 ID 一致，官方示例可原样使用
`wan3.0-video-intl`	海外	Topview 平台标识，用于路由到海外服务区

同一个账号可以随时混用这两个 model，无需申请或切换配置。海外版单价更高（见第 6 节），若无数据出境或访问时延方面的要求，建议优先使用 wan3.0-video。

传入未开通的 model 会返回 400 InvalidParameter。

input.prompt

类型：string
必填：与 input.media 二选一，至少有其一
说明：中英文均可，最多 20000 个字符（每个汉字或字母算 1 个字符），超出部分会被自动截断。

在参考生视频模式下，可以用「图1」「视频1」「音频1」指代 media 数组中对应顺序的素材。

input.media

类型：array
必填：与 input.prompt 二选一，至少有其一
说明：素材数组，每个元素包含 type 与 url。

支持的 type：

type	数量上限	说明
`first_frame`	1	首帧图片
`last_frame`	1	尾帧图片
`reference_image`	10	参考图片
`reference_video`	5	参考视频，总时长不超过 15 秒
`reference_audio`	5	参考音频，总时长不超过 15 秒
`file`	1	文档，用于文件生视频
`link`	1	公开网页地址，用于网页生视频

url 支持公网 HTTP(S) 地址，或 data:{MIME};base64,{data} 形式的 Base64（仅图像）。

两种模式互斥，混用会导致任务失败：

参考模式：reference_image、reference_video、reference_audio、file、link
首尾帧模式：first_frame、last_frame

此外 file 与 link 也不能同时传。平台会在创建时校验这两条规则并直接返回 400，避免你等待数分钟后才拿到 FAILED。

parameters.resolution

类型：string
必填：否
支持值：480P、720P、1080P
默认值：1080P

请务必显式指定 resolution。 不传时默认使用 1080P，这是单价最高的档位，费用是 480P 的 4 倍。

parameters.ratio

类型：string
必填：否
支持值：adaptive、16:9、4:3、1:1、3:4、9:16
默认值：adaptive，即根据输入素材与意图自动推荐

parameters.duration

类型：integer
必填：否
默认值：5

取值规则：

无视频输入时：2 到 30 之间的整数。
有视频输入时：输入视频总时长 + 输出时长不超过 30 秒。
传 -1 表示智能时长模式，由模型决定输出长度。

parameters.audio

类型：boolean
必填：否
默认值：true
说明：是否生成带声音的视频。开启与关闭声音价格相同。

parameters.seed

类型：integer
必填：否
取值范围：0 到 2147483647

parameters.watermark

类型：boolean
必填：否
默认值：false

4.4 文生视频示例

bash

curl -X POST \
  'https://api.topview.ai/api/v1/services/aigc/video-generation/video-synthesis' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'X-DashScope-Async: enable' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "电影级镜头，一艘飞船穿过深紫色星云，镜头缓慢推进。"
    },
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5,
      "audio": true
    }
  }'

4.5 首帧生视频示例

json

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "镜头缓慢拉近，人物转头看向远方。",
    "media": [
      { "type": "first_frame", "url": "https://example.com/first-frame.png" }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": 5
  }
}

4.6 首尾帧生视频示例

json

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "画面从白天平滑过渡到夜晚。",
    "media": [
      { "type": "first_frame", "url": "https://example.com/first-frame.png" },
      { "type": "last_frame", "url": "https://example.com/last-frame.png" }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": 8
  }
}

4.7 参考生视频示例

json

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "视频1中的人物抱着图2，坐在图3的椅子上弹奏一支舒缓的民谣。",
    "media": [
      { "type": "reference_video", "url": "https://example.com/role.mp4" },
      { "type": "reference_image", "url": "https://example.com/object2.png" },
      { "type": "reference_image", "url": "https://example.com/object3.png" }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": 5,
    "audio": true
  }
}

4.8 文件生视频示例

json

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "把这份产品介绍做成一段讲解视频。",
    "media": [{ "type": "file", "url": "https://example.com/deck.pptx" }]
  },
  "parameters": {
    "resolution": "720P",
    "duration": 15
  }
}

4.9 媒体限制

图片（first_frame、last_frame、reference_image）：

支持 JPEG、JPG、PNG、BMP、WEBP，PNG 不支持透明通道。
单张不超过 20 MB。
单边范围为 240～8000 px。
长宽比不超过 8:1。

参考视频：

支持 MP4、MOV。
单文件不超过 100 MB，最多 5 个。
单段时长 1～15 秒，总时长不超过 15 秒。
单边范围为 240～4096 px，长宽比不超过 8:1。

参考音频：

支持 WAV、MP3。
单文件不超过 15 MB，最多 5 个。
单段时长 1～15 秒，总时长不超过 15 秒。

文件：

支持 docx、doc、xlsx、xls、pptx、ppt、pdf、txt、key、pages、numbers、md。
单文件不超过 100 MB，不超过 50 页。

网页：仅支持无需登录即可访问的公开网页。

4.10 创建成功响应

json

{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-示例任务ID"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-示例请求ID"
}

4.11 创建失败响应

创建阶段失败时，错误码在响应体顶层，同时返回非 200 的 HTTP 状态：

json

{
  "code": "InvalidParameter",
  "message": "错误详情",
  "request_id": "示例请求ID"
}

5. 查询视频生成任务

5.1 接口

http

GET https://api.topview.ai/api/v1/tasks/{task_id}

5.2 请求示例

bash

curl -X GET \
  'https://api.topview.ai/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-示例任务ID' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey'

5.3 任务状态

PENDING：排队中。
RUNNING：生成中，或生成已完成但平台仍在交付处理。
SUCCEEDED：生成、扣费与视频转存均已完成。
FAILED：任务失败。
CANCELED：任务已取消。
UNKNOWN：任务不存在，或该任务不属于当前账号。

5.4 成功响应

json

{
  "request_id": "示例请求ID",
  "output": {
    "task_id": "0385dc79-5ff8-4d82-bcb6-示例任务ID",
    "task_status": "SUCCEEDED",
    "submit_time": "2026-08-08 10:01:35.452",
    "scheduled_time": "2026-08-08 10:01:35.507",
    "end_time": "2026-08-08 10:13:33.838",
    "orig_prompt": "电影级镜头，一艘飞船穿过深紫色星云，镜头缓慢推进。",
    "video_url": "https://平台交付地址/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"
  }
}

平台仅在以下步骤全部完成后才返回 SUCCEEDED：

上游生成成功。
平台完成积分扣费。
视频已转存到平台存储。
output.video_url 已改写为平台交付地址。

在上游已生成、平台仍在转存的短暂窗口内，查询会继续返回 RUNNING。这是为了保证 SUCCEEDED 与「video_url 立即可用」始终一致，通常只持续数秒。

output.video_url 是有有效期的签名地址，每次查询会重新生成，请拿到后尽快下载保存，不要长期缓存该 URL 本身。

5.5 失败响应

任务执行阶段失败时 HTTP 状态为 200，错误码在 output 内（注意与创建失败时的顶层位置不同）：

json

{
  "request_id": "示例请求ID",
  "output": {
    "task_id": "0385dc79-5ff8-4d82-bcb6-示例任务ID",
    "task_status": "FAILED",
    "code": "InvalidParameter",
    "message": "The two modes are mutually exclusive. Do not pass reference_xx and first_frame/last_frame at the same time."
  }
}

5.6 任务不存在

查询不存在的任务，或查询不属于当前账号的任务，均返回：

json

{
  "request_id": "示例请求ID",
  "output": {
    "task_id": "被查询的任务ID",
    "task_status": "UNKNOWN"
  }
}

6. 计费规则

计费按视频秒数计算，单价由请求的 model 与 resolution 档位共同决定。

`wan3.0-video`（中国内地）

resolution	积分/秒
480P	0.3
720P	0.6
1080P	1.2

`wan3.0-video-intl`（海外）

resolution	积分/秒
480P	0.37471
720P	0.74942
1080P	1.49884

1 元人民币对应 1 平台积分。海外版单价约为国内版的 1.25 倍，源自上游的区域定价差异。

两个 model 在接口路径、请求响应结构、状态机与错误码上完全一致，差异仅在单价。

计费时长

输入视频与输出视频都计费：

text

计费时长 = usage.input_video_duration + usage.output_video_duration

这一点请在做参考生视频、视频续写时特别注意：你传入的参考视频秒数同样计入费用。纯文生视频与图生视频没有视频输入，input_video_duration 为 0，只按输出时长计费。

计费公式

text

原价积分 = 计费时长 × 该 model 对应分辨率的每秒单价
最终扣费积分 = 原价积分 × 账号折扣率

结果保留 6 位小数，四舍五入。

计费说明

创建任务时会检查账户可用余额，余额不足返回 HTTP 402。
FAILED、CANCELED 任务不扣费。
SUCCEEDED 后根据 usage 后置扣费。
同一任务只扣费一次。
首次扣费会保存价格与折扣快照，后续价格调整不影响该任务。
扣费未完成前不会交付最终视频地址。
audio 开关不影响价格。
支持按账号配置折扣，两个 model 的折扣需分别约定，不会互相继承。
你账号生效的模型折扣可在 Overview 页的 Model discounts 查看，未列出的 model 按标准价计费。

计费示例

以下示例一至示例三按 wan3.0-video 单价计算。

示例一，5 秒 720P 文生视频，无视频输入：

text

(0 + 5) × 0.6
= 3.00 积分

示例二，参考生视频，传入 8 秒参考视频，输出 5 秒 720P：

text

(8 + 5) × 0.6
= 7.80 积分

注意这里输入的 8 秒同样计费，总计费时长是 13 秒而不是 5 秒。

示例三，未指定 resolution，按默认 1080P 输出 10 秒：

text

(0 + 10) × 1.2
= 12.00 积分

同样 10 秒，若显式指定 480P 则为 10 × 0.3 = 3.00 积分，相差 4 倍。

示例四，把示例一的 model 换成 wan3.0-video-intl，其余参数不变：

text

(0 + 5) × 0.74942
= 3.7471 积分

同一场景 wan3.0-video 为 3.00 积分，差异仅来自单价。

若账号折扣为 8 折，在上述结果上再乘 0.8。示例二即：

text

7.80 × 0.8
= 6.24 积分

7. 并发与限流

并发按「账号 + model」控制，与其他视频模型服务相互隔离。

两个 model 各有独立额度：wan3.0-video 占满时不影响 wan3.0-video-intl 的调用，反之亦然，两者不共享槽位。

以下情况会拒绝创建并返回 HTTP 429：

账号未配置该 model 的并发额度。
账号的该 model 能力已停用。
该 model 当前运行任务数达到上限。

任务进入 SUCCEEDED、FAILED 或 CANCELED 后会释放并发槽位。

8. 错误响应

错误码有两个出现位置，请分别处理：

创建失败：非 200 HTTP 状态，code 与 message 在响应体顶层。
任务执行失败：HTTP 200，code 与 message 在 output 内。

常见 HTTP 状态：

400：请求参数错误，或素材模式互斥校验未通过。
401：API Key 缺失、无效或已过期。
402：账户余额不足。
429：账号并发额度不足或上游限流。
500：服务端或上游调用异常。
503：服务当前未开放。

常见错误码：

code	含义
`InvalidParameter`	参数非法，含两种素材模式混用、model 未开通
`InsufficientBalance`	平台积分余额不足
`Throttling.Concurrency`	并发数超上限
`DataInspectionFailed`	内容安全审核未通过
`InvalidFile.DownloadFailed`	素材 URL 下载失败
`InvalidFile.Format`	素材格式不支持
`InvalidFile.Resolution`	素材分辨率超限
`InvalidFile.Duration`	素材时长超限
`InternalError`	服务端内部错误，可重试

上游返回的非 2xx 错误会保留原始 HTTP 状态和响应体。

排查问题时，请向技术支持提供完整的 request_id 和 task_id，不要提供 API Key。

9. 接入注意事项

不要在前端、日志或工单中暴露 API Key。
媒体 URL 必须可被公网访问。
建议轮询间隔不低于 15 秒，生成通常耗时 1～5 分钟。
务必显式指定 resolution，默认的 1080P 是最贵档位。
无特殊要求时优先用 wan3.0-video，wan3.0-video-intl 单价高约 25%。
参考生视频要把输入视频秒数计入成本预算。
素材两种模式互斥，请在提交前自查。
收到 SUCCEEDED 后请及时下载保存视频。
遇到 HTTP 429 时应采用指数退避重试。
对 HTTP 400、401、402 等确定性错误不应自动重试。

10. 官方协议参考

百炼 wan3.0 视频生成 API 参考：https://help.aliyun.com/zh/model-studio/wan3-video-generation-api-reference
百炼错误码：https://help.aliyun.com/zh/model-studio/error-code

对接文档

文档信息

1. 接口概览

2. 鉴权与通用约定

3. 推荐调用流程

4. 创建视频生成任务

4.1 接口

4.2 请求头

4.3 请求字段

model

input.prompt

input.media

parameters.resolution

parameters.ratio

parameters.duration

parameters.audio

parameters.seed

parameters.watermark

4.4 文生视频示例

4.5 首帧生视频示例

4.6 首尾帧生视频示例

4.7 参考生视频示例

4.8 文件生视频示例

4.9 媒体限制

4.10 创建成功响应

4.11 创建失败响应

5. 查询视频生成任务

5.1 接口

5.2 请求示例

5.3 任务状态

5.4 成功响应

5.5 失败响应

5.6 任务不存在

6. 计费规则

wan3.0-video（中国内地）

wan3.0-video-intl（海外）

计费时长

计费公式

计费说明

计费示例

7. 并发与限流

8. 错误响应

9. 接入注意事项

10. 官方协议参考

`wan3.0-video`（中国内地）

`wan3.0-video-intl`（海外）