异步任务 / Async Tasks

异步任务 API

图像与视频生成统一走 /v1/tasks 接口。视频模型为异步调用（先创建任务获取 task_id，再轮询查询结果），图像模型（如 wan2.6-t2i）为同步调用，直接返回结果无需轮询。视频生成通常需要 1-5 分钟。

HTTP 调用流程

创建任务获取 task_id

POSThttps://nexusflow.hk/v1/tasks

根据 task_id 轮询结果

GEThttps://nexusflow.hk/v1/tasks/{task_id}

注意：

创建成功后，使用返回的 id（即 task_id）查询结果。请勿重复创建任务，轮询获取即可。
图像模型（如 wan2.6-t2i）为同步接口，创建请求直接返回结果，无需轮询。
视频模型轮询建议间隔 10-15 秒。
task_id 查询有效期 24 小时，超时后无法查询。
输出文件 URL 有效期 24 小时，获取后请立即下载保存。
仅图像和视频模型支持 /v1/tasks 接口，聊天模型请使用 /v1/chat/completions。

步骤1：创建任务

示例模型：wan2.6-t2i

请求参数

参数	类型	必选	说明
`model`	string	*	模型 ID，例如 wan2.6-t2i。完整列表见模型文档。
`prompt`	string	*	文本提示词，描述期望生成的图像内容。
`negative_prompt`	string	-	负面提示词，描述不希望出现的内容。
`size`	string	-	输出图像尺寸，如 1024x1024（默认）、720x1280、1280x720 等。
`n`	integer	-	生成图片数量，默认 1，最多 4。
`seed`	integer	-	随机种子，固定 seed 可提升可复现性。

请求示例

curl

curl -X POST 'https://nexusflow.hk/v1/tasks' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2i",
    "prompt": "一只橘色的猫站在月球表面，背景是地球，赛博朋克风格，4K 超高清",
    "size": "1024x1024",
    "n": 1
  }'

步骤1 响应：获取 task_id

创建成功后返回任务信息（HTTP 202），id 即为 task_id，用于后续轮询查询。

json

{
  "id": "task_0385dc79-5ff8-4d82-xxxx",
  "object": "task",
  "status": "running",
  "model": "wan2.6-t2i",
  "type": "image",
  "created_at": "2026-06-01T10:00:00.000Z"
}

字段	说明
`id`	任务 ID（task_id）。视频任务用于轮询查询结果，有效期 24 小时。
`object`	固定值 "task"。
`status`	视频模型初始状态为 running；图像模型（如 wan2.6-t2i）为同步接口，直接返回 succeeded。
`model`	所使用的模型 ID。
`type`	任务类型："image"（图像生成）或 "video"（视频生成）。
`created_at`	任务创建时间（ISO 8601 格式）。

步骤2：根据 task_id 轮询结果

GEThttps://nexusflow.hk/v1/tasks/{task_id}

查询请求

curl

curl https://nexusflow.hk/v1/tasks/task_0385dc79-5ff8-4d82-xxxx \
  -H "Authorization: Bearer $API_KEY"

图像任务执行成功

json

{
  "id": "task_0385dc79-5ff8-4d82-xxxx",
  "object": "task",
  "status": "succeeded",
  "model": "wan2.6-t2i",
  "type": "image",
  "progress": 100,
  "output": {
    "image_url": "https://nexusflow.hk/storage/xxx.png"
  },
  "created_at": "2026-06-01T10:00:00.000Z",
  "completed_at": "2026-06-01T10:00:22.000Z"
}

任务执行失败

json

{
  "id": "task_0385dc79-5ff8-4d82-xxxx",
  "object": "task",
  "status": "failed",
  "model": "wan2.6-t2i",
  "type": "image",
  "error": "InvalidParameter: The parameter is invalid.",
  "created_at": "2026-06-01T10:00:00.000Z",
  "completed_at": "2026-06-01T10:00:05.000Z"
}

响应参数

字段	类型	说明
`id`	string	任务 ID。
`object`	string	固定值 "task"。
`status`	string	任务状态：pending（排队中）→ running（处理中）→ succeeded（成功）/ failed（失败）。
`model`	string	所使用的模型 ID。
`type`	string	任务类型："image" 或 "video"。
`progress`	integer	任务进度百分比 0-100。
`output`	object	生成结果（仅 succeeded 时返回）。图像任务包含 image_url，视频任务包含 video_url。链接有效期 24 小时。
`error`	string	失败原因（仅 failed 时返回）。
`created_at`	string	任务创建时间（ISO 8601 格式）。
`completed_at`	string	任务完成时间（仅终态时返回）。

查询任务列表

GEThttps://nexusflow.hk/v1/tasks?limit=20

获取当前用户的近期任务列表。可通过 limit 参数控制返回数量（默认 20，最大 100）。

curl

curl 'https://nexusflow.hk/v1/tasks?limit=5' \
  -H "Authorization: Bearer $API_KEY"

json

{
  "object": "list",
  "data": [
    {
      "id": "task_0385dc79-5ff8-4d82-xxxx",
      "object": "task",
      "status": "succeeded",
      "model": "wan2.6-t2i",
      "type": "image",
      "progress": 100,
      "created_at": "2026-06-01T10:00:00.000Z",
      "completed_at": "2026-06-01T10:00:22.000Z"
    },
    {
      "id": "task_a1b2c3d4-e5f6-7890-yyyy",
      "object": "task",
      "status": "running",
      "model": "happyhorse-1.0-t2v",
      "type": "video",
      "progress": 45,
      "created_at": "2026-06-01T10:05:00.000Z",
      "completed_at": null
    }
  ]
}

最佳实践

轮询做退避

图像任务 5-10 秒轮询，视频任务 10-15 秒轮询，避免亚秒级轮询以减少不必要的请求。

拆分同步与异步

聊天请求走 /v1/chat/completions，图像/视频走 /v1/tasks，减少互相干扰。

及时下载结果

输出 URL 有效期 24 小时，任务完成后应立即下载保存文件。

处理失败重试

任务失败时根据 error 字段判断原因。参数错误需修正后重试，上游超时可直接重新创建任务。

HappyHorse API

查看 HappyHorse 视频生成专用文档