Async Tasks

Async Tasks API

Image and video generation both go through the /v1/tasks endpoint. Video models are asynchronous (create a task to get a task_id, then poll for the result), while image models (such as wan2.6-t2i) are synchronous and return results directly without polling. Video generation usually takes 1-5 minutes.

HTTP Call Flow

Create a task to get task_id

POSThttps://nexusflow.hk/v1/tasks

Poll the result by task_id

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

Note:

After successful creation, query the result using the returned id (the task_id). Do not recreate the task — just poll.
Image models (such as wan2.6-t2i) are synchronous: the create request returns results directly, no polling needed.
For video models, poll at a recommended interval of 10-15 seconds.
task_id queries are valid for 24 hours; after that they cannot be queried.
Output file URLs are valid for 24 hours; download and save them immediately.
Only image and video models support the /v1/tasks endpoint; use /v1/chat/completions for chat models.

Step 1: Create a Task

Example model:wan2.6-t2i

Request Parameters

Parameter	Type	Required	Description
`model`	string	*	Model ID, e.g. wan2.6-t2i. See the model docs for the full list.
`prompt`	string	*	Text prompt describing the image you want to generate.
`negative_prompt`	string	-	Negative prompt describing what you do not want to appear.
`size`	string	-	Output image size, e.g. 1024x1024 (default), 720x1280, 1280x720, etc.
`n`	integer	-	Number of images to generate, default 1, max 4.
`seed`	integer	-	Random seed; fixing the seed improves reproducibility.

Request Example

curl -X POST 'https://nexusflow.hk/v1/tasks' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2i",
    "prompt": "An orange cat standing on the lunar surface with Earth in the background, cyberpunk style, 4K ultra HD",
    "size": "1024x1024",
    "n": 1
  }'

Step 1 Response: Get task_id

On success, task information is returned (HTTP 202); the id is the task_id used for subsequent polling.

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

Field	Description
`id`	Task ID (task_id). Used to poll for video task results, valid for 24 hours.
`object`	Always "task".
`status`	Video models start as running; image models (such as wan2.6-t2i) are synchronous and return succeeded directly.
`model`	The model ID used.
`type`	Task type: "image" (image generation) or "video" (video generation).
`created_at`	Task creation time (ISO 8601 format).

Step 2: Poll the Result by task_id

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

Query Request

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

Image Task Succeeded

{
  "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"
}

Task Failed

{
  "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"
}

Response Parameters

Field	Type	Description
`id`	string	Task ID.
`object`	string	Always "task".
`status`	string	Task status: pending (queued) → running (processing) → succeeded / failed.
`model`	string	The model ID used.
`type`	string	Task type: "image" or "video".
`progress`	integer	Task progress percentage, 0-100.
`output`	object	Generation result (returned only when succeeded). Image tasks include image_url, video tasks include video_url. Links are valid for 24 hours.
`error`	string	Failure reason (returned only when failed).
`created_at`	string	Task creation time (ISO 8601 format).
`completed_at`	string	Task completion time (returned only in a terminal state).

List Tasks

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

Retrieve the current user's recent tasks. Use the limit parameter to control the number returned (default 20, max 100).

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

{
  "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
    }
  ]
}

Best Practices

Back off when polling

Poll image tasks every 5-10 seconds and video tasks every 10-15 seconds; avoid sub-second polling to reduce unnecessary requests.

Separate sync and async

Route chat requests through /v1/chat/completions and image/video through /v1/tasks to reduce interference.

Download results promptly

Output URLs are valid for 24 hours; download and save files immediately after a task completes.

Handle failure retries

When a task fails, check the error field. Fix parameter errors before retrying; for upstream timeouts, simply recreate the task.

HappyHorse API

View the dedicated HappyHorse video generation docs

Rate Limits

Limits and optimization tips for high concurrency

Full Pricing

View pricing for all models