了解 Wan3 视频生成的模型、输入方式、异步调用流程与用量计费规则。

Wan3 概览

UniGateway 为 Wan3 模型提供异步视频生成接口。提交请求后，接口返回任务 ID；应用随后查询任务状态，并在生成完成后获取视频结果。

支持的模型

模型 ID	说明
`wan3.0-video`	Wan3 普通版
`wan3.0-video-prime`	Wan3 Prime 版

两个模型使用相同的创建和查询接口，分别计价并控制访问权限。模型能力、价格和可用性以 UniGateway 模型库、控制台或当前账户的接口实时返回为准。

准备工作

请前往 UniGateway API Keys 创建或获取 API Key。

调用前确认 API Key 已启用、具有目标模型的访问权限，并且工作区余额和消费限额满足调用要求。将 API Key 保存到服务端环境变量或受控的密钥管理服务中，不要写入公开代码、浏览器端代码或日志。

API 地址与鉴权

项目	值
Base URL	`https://api.unigateway.ai`
创建任务	`POST /v1/videos`
查询任务	`GET /v1/videos/{task_id}`
鉴权请求头	`Authorization: Bearer <YOUR_UNIGATEWAY_API_KEY>`

Base URL 不包含 /v1，接口路径已经包含 /v1，拼接时不要重复添加。创建任务的完整地址为：

https://api.unigateway.ai/v1/videos

输入方式

输入方式	请求内容
文本生成视频	在 `prompt` 中描述视频内容
首帧或首尾帧生成	使用 `first_frame`、`last_frame` 图像
参考素材生成	使用 `reference_image`、`reference_video`、`reference_audio`
文件或链接输入	使用 `file` 或 `link`，并启用 `prompt_extend`

有效提示词与非空素材列表至少提供一项。参考素材直接放在 metadata.input.media 中，无需先创建素材库。

各素材类型的单次请求数量上限分别为：首帧图像 1 张、尾帧图像 1 张、参考图像 10 张、参考视频 5 个、参考音频 5 段。file 和 link 各最多 1 项，且不能同时使用。首尾帧不能与参考素材、file 或 link 混用。

素材 URL 应在任务处理期间保持有效且可由服务端访问。素材格式、编码、实际时长和内容必须通过服务端校验。

调用流程

调用 POST /v1/videos 创建任务。
保存创建响应中的公开任务 ID id。
使用该 ID 调用 GET /v1/videos/{task_id}。
当 status=completed 且 metadata.url 非空时，获取视频结果。
读取 metadata.usage 查看实际用量，并在控制台查看账单。

建议以约 15 秒的间隔查询。创建成功表示任务已受理，不表示视频已经生成完成。

默认生成参数

生成参数放在 metadata.parameters 中。

参数	默认值	可选值
`resolution`	`1080P`	`480P`、`720P`、`1080P`
`ratio`	`adaptive`	`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`
`duration`	`5`	`-1` 或 2 至 30 的整数，单位为秒
`audio`	`true`	`true`、`false`
`prompt_extend`	`true`	`true`、`false`

duration=-1 表示自动选择生成时长，最终以实际结果为准。需要明确控制生成要求时，请显式设置分辨率、时长及音频选项。

请求与响应示例

以下示例使用 Prime 模型；调用普通版时，将 model 改为 wan3.0-video，并确认当前 API Key 具有相应权限。

{
  "model": "wan3.0-video-prime",
  "prompt": "A golden retriever running along a quiet beach at sunrise, cinematic, smooth camera movement",
  "metadata": {
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5,
      "audio": false,
      "prompt_extend": true,
      "watermark": false,
      "seed": 0
    }
  }
}

创建响应关键字段示意如下，任务 ID 为占位值：

{
  "id": "PUBLIC_TASK_ID",
  "object": "video",
  "model": "wan3.0-video-prime",
  "status": "queued",
  "progress": 0
}

使用响应中的 id 查询任务。查询结果中，queued 表示排队，in_progress 表示生成中，completed 表示成功，failed 表示失败或取消，unknown 表示状态尚不明确。

用量与计费

计费时长使用任务实际用量：

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

无输入视频、实际输出 5 秒：计费时长为 5 秒。
实际输入视频 5 秒、实际输出 5 秒：计费时长为 10 秒。

不要再次累加 metadata.usage.duration，也不要使用请求中的 duration 代替实际计费时长。时长可能包含小数，请保留精度。

费用根据模型、分辨率、实际计费时长、适用价格、折扣和币种换算计算。普通版与 Prime 分别计价，当前单价和实际费用以控制台及账单为准。

任务明确失败或取消时不收取生成费用。状态未知或用量尚未返回时，不能据此判断任务免费。

结果保存与异常处理

视频结果地址可能包含签名和有效期。保留完整 URL，并及时保存需要的视频。
参数校验失败时，按错误响应修正请求后再提交。
创建请求超时或发生通信异常时，先核查是否已创建任务，避免盲目重复提交。
查询请求发生网络异常时，可适当退避后查询同一任务。
以 status 判断是否完成，不要仅依据进度或时间戳。长时间处于 unknown 时，保留任务 ID 并联系技术支持。

Wan3 概览#

支持的模型#

准备工作#

API 地址与鉴权#

输入方式#

调用流程#

默认生成参数#

请求与响应示例#

用量与计费#

结果保存与异常处理#