Tasks

Every generation is a task. Creating one returns at once with status: queued; the video is produced in the background and the task moves through its statuses until it reaches a terminal one.

Lifecycle

Status	Meaning	What is set
`queued`	Accepted and waiting. Tasks with input files also download and prepare them in this phase.	`queue.position` when known
`processing`	The model is generating.	`started_at`
`completed`	The video is ready. Terminal.	`output`, `credits.charged`, `completed_at`, `expires_at`
`failed`	The task could not finish. Terminal.	`error`, `completed_at`
`cancelled`	You cancelled it. Terminal.	`completed_at`

A task never leaves a terminal status.

The task object

{
  "id": "task_01J9X7Z0K7Q8W3F2P1N6M5V4R3",
  "object": "task",
  "model": "wan/v3.0-spark/image-to-video",
  "task": "image-to-video",
  "status": "completed",
  "input": {
    "image_url": "https://assets.example.com/inputs/portrait.jpg",
    "prompt": "slow push-in, soft morning light, hair moving in the breeze",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive"
  },
  "output": {
    "video": {
      "url": "https://openassets.fiveapi.ai/x2v/results/551fe9fa/openapi_1793171336.mp4",
      "content_type": "video/mp4",
      "file_size": 4823119,
      "width": 720,
      "height": 1280,
      "duration": 5.04,
      "fps": 24,
      "cover_url": "https://openassets.fiveapi.ai/x2v/results/61f69823/openapi_1793171336.jpg"
    },
    "actual_prompt": "A slow cinematic push-in on a young woman in soft morning light, her hair moving gently in the breeze."
  },
  "error": null,
  "credits": { "estimated": 60, "charged": 60 },
  "webhook_url": "https://hooks.example.com/fiveapi",
  "metadata": { "order_id": "ord_8812" },
  "created_at": "2026-10-23T06:21:02.127Z",
  "started_at": "2026-10-23T06:21:40.512Z",
  "completed_at": "2026-10-23T06:23:05.004Z",
  "expires_at": "2026-10-30T06:23:05.004Z"
}

Field	Description
`id`	`task_` followed by 26 characters. Store it: it is how you find the task again.
`model`, `task`	The model id the task was created with, and its task type.
`input`	The accepted request body, without `webhook_url` and `metadata`.
`output.video`	The MP4: `url`, `content_type`, `file_size` (bytes), `width`, `height`, `duration` (seconds), `fps`, and `cover_url` (first frame, JPG) when available.
`output.actual_prompt`	The prompt after prompt expansion, when it was rewritten.
`error`	Always present: `null`, or `{code, message, retryable, reason}` on a failed task.
`credits`	`estimated` (held at creation) and `charged` (set on completion).
`queue.position`	Position in the model’s queue while `queued`; lower starts sooner.
`webhook_url`, `metadata`	As you sent them.
`created_at`, `started_at`, `completed_at`, `expires_at`	ISO 8601 UTC timestamps.

Members that have no value are omitted, except error. New fields may appear at any time: ignore the ones you don’t know.

Get the result

You have two ways to learn that a task finished.

Webhooks (recommended)
Polling

Pass webhook_url when you create the task, or set a default endpoint in the console. Five API sends a signed task.completed, task.failed or task.cancelled event with the full task object. See Webhooks.

Call GET /v1/tasks/{task_id} until the status is terminal. Start with a short delay and back off:

import time
import requests

def wait_for(task_id: str, api_key: str, timeout_s: int = 900) -> dict:
    delay, deadline = 3, time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(
            f"https://api.fiveapi.ai/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=15,
        ).json()
        if task["status"] in ("completed", "failed", "cancelled"):
            return task
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

Polling counts against your rate limit. Every few seconds per task is plenty.

List tasks

GET /v1/tasks returns the tasks of your account, newest first, across all of its keys. Filter with status, model and created_after, and page with limit (1–100, default 20) and starting_after:

curl "https://api.fiveapi.ai/v1/tasks?status=completed&limit=20" \
  -H "Authorization: Bearer $FIVEAPI_API_KEY"

# next page: pass the id of the last task you received
curl "https://api.fiveapi.ai/v1/tasks?status=completed&limit=20&starting_after=task_01J9X7Z0K7Q8W3F2P1N6M5V4R3" \
  -H "Authorization: Bearer $FIVEAPI_API_KEY"

Keep paging while has_more is true. Requests that were rejected at creation (for example with 402) never became tasks and are not listed.

Cancel a task

curl -X POST https://api.fiveapi.ai/v1/tasks/task_01J9X7Z0K7Q8W3F2P1N6M5V4R3/cancel \
  -H "Authorization: Bearer $FIVEAPI_API_KEY"

A queued or processing task becomes cancelled immediately and its held credits return to your balance in the same step. A task.cancelled webhook follows. If the model finishes the video after the cancel, the result is discarded and never charged. Cancelling a task that is already cancelled answers 200 again. Cancelling a completed or failed task answers 409 task_already_terminal.

Retention

output and the video file stay available until expires_at, 7 days after completion.
After that the task is still readable, but without output, and the file URL stops working.
Download the video (and cover_url if you use it) as soon as the task completes, and keep your own copy.

Get started

Core concepts

Guides

Build with AI

Resources

Lifecycle

The task object

Get the result

List tasks

Cancel a task

Retention

​Lifecycle

​The task object

​Get the result

​List tasks

​Cancel a task

​Retention

Lifecycle

The task object

Get the result

List tasks

Cancel a task

Retention