异步任务工作流

视频生成是异步操作。提交任务后，你会先获得 AionRouter 生成的公开 task_ ID。保存该 ID，用它查询状态和下载结果；不要使用上游服务返回的内部任务 ID。

POST 创建任务 → 保存 task_ ID → GET 轮询 → completed / SUCCESS → 下载内容

公共请求头

除 PixVerse 的文件上传外，视频接口使用 JSON 请求。所有接口都需要 API 密钥。

Header	必填	说明
`Authorization`	是	`Bearer <API_KEY>`。
`Content-Type`	JSON 请求时是	`application/json`。使用 `multipart/form-data` 上传文件时，由客户端自动设置。

提交任务

使用 POST /v1/video/generations 创建统一任务。提交成功时，接口立即返回扁平的视频对象；此时视频通常仍在队列中。

{
  "id": "task_01HZX7Q8K6P3Y4M2N9R5T1V0AB",
  "task_id": "task_01HZX7Q8K6P3Y4M2N9R5T1V0AB",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1780000000
}

字段	类型	说明
`id`	string	公开任务 ID。后续查询和下载优先使用此字段。
`task_id`	string	与 `id` 相同的兼容字段。
`object`	string	固定为 `video`。
`model`	string	本次提交使用的模型名。
`status`	string	新任务通常为 `queued`。
`progress`	integer	当前进度百分比。刚提交时通常为 `0`。
`created_at`	integer	Unix 秒级时间戳。

提交成功只表示任务已受理，不表示视频已生成。请继续查询任务状态。

查询统一任务

使用 GET /v1/video/generations/{task_id} 查询统一任务详情。响应使用 {code, message, data} 包装，统一状态位于 data.status。

curl "https://router.aionclaw.ai/v1/video/generations/task_01HZX7Q8K6P3Y4M2N9R5T1V0AB" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY"

任务完成时的示例响应：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_01HZX7Q8K6P3Y4M2N9R5T1V0AB",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://media.example.com/generated-video.mp4",
    "submit_time": 1780000000,
    "start_time": 1780000004,
    "finish_time": 1780000042,
    "properties": {
      "origin_model_name": "MiniMax-H3"
    }
  }
}

字段	类型	说明
`code`	string	成功时为 `success`。
`data.task_id`	string	公开任务 ID。
`data.status`	string	统一任务状态。用它判断是否继续轮询。
`data.progress`	string	进度百分比，例如 `30%` 或 `100%`。
`data.result_url`	string	成功后的视频地址，可能是上游临时地址或 Router 代理地址。建议使用下文的 `/content` 接口下载。
`data.fail_reason`	string	失败原因。仅任务失败时有值。
`data.submit_time` / `start_time` / `finish_time`	integer	Unix 秒级时间戳。未进入相应阶段时可能为 `0`。
`data.properties.origin_model_name`	string	实际提交的模型名。
`data.data`	object	上游原始任务数据。其内部结构随模型而变，不应作为跨模型集成的稳定字段。

统一状态

`data.status`	含义	下一步
`NOT_START`、`SUBMITTED`、`QUEUED`、`IN_PROGRESS`	尚未完成	等待后继续查询。
`SUCCESS`	已完成	下载 `data.result_url` 或调用 `/content`。
`FAILURE`	失败	读取 `data.fail_reason` 并停止轮询。

查询 OpenAI 兼容任务

如果你使用 POST /v1/videos 创建任务，请使用 GET /v1/videos/{task_id} 查询。它返回扁平视频对象，不使用 {code, data} 包装。

{
  "id": "task_01HZX7Q8K6P3Y4M2N9R5T1V0AB",
  "object": "video",
  "model": "PixVerse/v6",
  "status": "completed",
  "progress": 100,
  "created_at": 1780000000,
  "completed_at": 1780000042,
  "metadata": {
    "url": "https://media.example.com/generated-video.mp4"
  }
}

`status`	对应统一任务状态	含义
`queued`	`SUBMITTED`、`QUEUED`	排队中。
`in_progress`	`IN_PROGRESS`	生成中。
`completed`	`SUCCESS`	已完成。
`failed`	`FAILURE`	失败。错误信息在 `error.message`。

不要混用两套查询响应：统一格式读取 data.status，OpenAI 兼容格式读取顶层 status。

下载视频

任务完成后，用公开任务 ID 调用内容接口。该接口会返回视频二进制流。

curl -L "https://router.aionclaw.ai/v1/videos/task_01HZX7Q8K6P3Y4M2N9R5T1V0AB/content" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY" \
  --output result.mp4

接口	成功响应	说明
`GET /v1/videos/{task_id}/content`	`video/mp4` 二进制流	仅能下载你有权限访问且已完成的任务。

请将需要长期保留的视频转存到自己的存储。上游视频地址可能会过期。

轮询建议

首次查询前等待数秒。未完成时逐步增加间隔，例如 5 秒、10 秒、15 秒。不要高频轮询，也不要假设不同模型的生成时间相同。

​公共请求头

​提交任务

​查询统一任务

​统一状态

​查询 OpenAI 兼容任务

​下载视频

​轮询建议

公共请求头

提交任务

查询统一任务

统一状态

查询 OpenAI 兼容任务

下载视频

轮询建议