# 任务与下载

https://video-doc.1route.dev/zh/docs/tasks



## 创建一次，查询多次 [#创建一次查询多次]

成功提交会返回 `id`，例如 `task_EXAMPLE`。立即保存完整编号，再调用 `GET /v1/videos/{id}` 查询。查询需要 API Key。

| 本站状态          | 意义        | 怎么做                                    |
| ------------- | --------- | -------------------------------------- |
| `queued`      | 排队        | 继续查询                                   |
| `in_progress` | 正在处理或准备文件 | 继续查询                                   |
| `completed`   | 视频可下载     | 读取 `metadata.url`，立即保存                 |
| `failed`      | 任务失败      | 记录 `error.code` 与 `error.message`，查看用量 |
| `expired`     | 本站缓存已过期   | 停止查询下载；检查是否已有本地副本                      |

未知状态不要当成功。进度数值不是剩余时间，也不保证单调增加。建议每 15 秒查询一次。

## 下载链接在哪里 [#下载链接在哪里]

完成响应里的 `metadata.url` 是本站签名地址。使用原始 URL，保留 `expires` 和 `sig` 参数；不要自行拼下载路径，也不需要向签名链接额外发送 Key。

视频由本站转存后提供。当前文件从准备好起临时保留约 **10 分钟**，单个签名链接最长约 **5 分钟**，并且不会超过文件保留期限。

`expires_at` 对应本站缓存文件的到期时间；链接自身的到期时间在 URL 的 `expires` 参数中，可能更早。首次打开页面、首次查询或刷新任务都不会重新开始文件保留期。

## 地址过期还能找回吗 [#地址过期还能找回吗]

文件还在保留期内时，重新查询原任务可获得新链接。如果已经 `expired` 或下载返回 `410`，该缓存已不可用。先找本地下载副本，再决定是否付费重新生成。

## 网络中断怎么办 [#网络中断怎么办]

查询 GET 失败时可以稍后重查。创建 POST 超时或未收到编号时，任务可能已经受理；保留提交时间、请求编号，核对控制台记录或联系客服，不要自动再创建。

本站没有向本客户端承诺幂等创建或取消接口。停止本地等待不等于取消任务，不代表退款。程序应保存任务编号并支持恢复，等待 30 分钟后也不应自动新建。

完整的 [Python 客户端示例](/examples/wan3_client.py) 支持从已保存任务继续查询。