Wan3 查询任务
本接口用于查询已创建的 Wan3 视频生成任务，获取任务状态、视频结果、实际用量和错误信息。适用于 wan3.0-video 和 wan3.0-video-prime。
准备工作
请前往 UniGateway API Keys 创建或获取 API Key。查询时使用创建任务所用的 API Key，并准备创建响应中的 id。
将 API Key 保存到服务端环境变量 UNIGATEWAY_API_KEY 或受控的密钥管理服务中，不要写入公开代码、浏览器端代码或日志。
模型能力、价格和可用性以 UniGateway 模型库、控制台或当前账户的接口实时返回为准。
接口与鉴权
| 项目 | 值 |
|---|---|
| 请求方法 | GET |
| Base URL | https://api.unigateway.ai |
| 请求路径 | /v1/videos/{task_id} |
| 鉴权请求头 | Authorization: Bearer <YOUR_UNIGATEWAY_API_KEY> |
| 请求体 | 无 |
完整请求地址为 https://api.unigateway.ai/v1/videos/{task_id}。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
task_id | string | 是 | 创建响应中 id 字段返回的公开任务 ID |
将路径中的 {task_id} 替换为实际任务 ID，不要保留花括号或示例占位值。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 公开任务 ID |
object | string | 资源类型，值为 video |
model | string | 请求使用的模型 |
status | string | 任务状态，用于判断是否完成 |
progress | number | 进度参考值，不保证线性增长 |
created_at | integer | 创建时间，Unix 秒级时间戳 |
metadata.status | string | 任务的详细状态标识 |
metadata.url | string | 视频结果 URL；未完成时可能为空 |
metadata.usage | object 或 null | 实际用量信息；未完成时可能为 null |
error | object | 错误信息，存在时包含 code 和 message |
是否完成以 status 为准。即使响应包含 completed_at，也不能仅凭该字段或 progress 判断任务已经成功。
任务状态与轮询
status | metadata.status | 含义与处理 |
|---|---|---|
queued | PENDING | 排队中，稍后继续查询 |
in_progress | RUNNING | 生成中，稍后继续查询 |
completed | SUCCEEDED | 生成成功，读取 metadata.url |
failed | FAILED 或 CANCELED | 失败或取消，查看错误信息 |
unknown | UNKNOWN 或未识别状态 | 状态尚不明确，不应当作成功或确定失败 |
建议每隔约 15 秒查询一次，并设置合理的客户端等待期限。达到等待期限不代表任务已经失败，也不会自动取消任务。
任务完成或明确失败后停止常规轮询。长时间未获得明确状态时，保留任务 ID、请求时间和错误响应，联系技术支持核查。不要在排查信息中包含 API Key。
成功响应示例
以下为关键字段示例，任务 ID 和视频地址为占位值；实际响应可能包含其他字段。
{
"id": "PUBLIC_TASK_ID",
"object": "video",
"model": "wan3.0-video-prime",
"status": "completed",
"progress": 100,
"metadata": {
"status": "SUCCEEDED",
"url": "https://example.com/generated-video.mp4",
"usage": {
"duration": 10,
"input_video_duration": 5,
"output_video_duration": 5,
"fps": 30,
"ratio": "16:9",
"video_count": 1,
"SR": 720
}
}
}
用量字段与计费
以下字段位于 metadata.usage 中。
| 字段 | 类型 | 说明 |
|---|---|---|
input_video_duration | number | 实际输入视频时长，单位为秒 |
output_video_duration | number | 实际输出视频时长，单位为秒 |
duration | number | 视频用量时长字段，不应再次加入计费公式 |
fps | number | 输出视频帧率 |
ratio | string | 输出视频画面比例 |
video_count | integer | 输出视频数量 |
SR | number | 分辨率标识，例如 720 |
时长可能包含小数，请保留精度。计费时长计算方式为：
计费时长 = input_video_duration + output_video_duration
上述示例为 5 + 5 = 10 秒，不能再加上 duration=10。
请求中的 duration 表示生成要求，最终计费时长以实际输入和输出时长为准。metadata.usage 表示用量，不表示金额。单价、折扣、币种换算和最终费用以控制台及账单为准。
获取与保存视频
当 status=completed 且 metadata.url 非空时，可访问该地址获取视频。保留完整 URL 及签名查询参数，并在地址失效前保存需要的文件。
任务尚未完成时，视频地址可能为空，用量可能为 null。任务成功后若缺少结果地址或用量，请保留任务 ID 和响应进行排查，不要直接重新创建任务。
错误处理
Q: 查询接口返回 HTTP 错误怎么办？
检查请求地址是否为 https://api.unigateway.ai/v1/videos/{task_id}，任务 ID 是否来自创建响应，以及鉴权请求头是否携带创建任务时使用的 API Key。根据实际错误响应修正请求后重新查询。查询请求失败不等同于生成任务失败。
Q: 任务状态为 failed 怎么办？
检查 error.code、error.message 和 metadata.status。存在输入问题时，修正提示词、素材或参数后再决定是否创建新任务，不要重复提交未经修正的请求。
Q: 任务长期处于 unknown 怎么办？
保留任务 ID、请求时间和最近响应，联系技术支持确认状态。状态未知不代表任务成功、失败或免费，不应据此重复创建相同任务。
Q: 查询超时或网络异常怎么办？
适当退避后重新查询同一个任务。客户端等待超时不会自动取消任务；需要继续获取结果时，仍使用原任务 ID 查询。