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 for a generation slot. Tasks with input files also download and prepare them in this phase.	—
`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/Five_API_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/Five_API_1793171336.jpg"
    }
  },
  "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.
`error`	Always present: `null`, or `{code, message, retryable, reason}` on a failed task.
`credits`	`estimated` (held at creation) and `charged` (set on completion).
`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 = 5, 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 the request rate limit of your account: on the standard plan 10 requests per second and 300 per minute, every key and endpoint included. Past that the gateway answers 429 rate_limit_exceeded with a Retry-After header. Poll each task every 5–10 seconds and back off to 30 seconds; at that pace the budget follows dozens of tasks at once. To follow many tasks, one GET /v1/tasks?status=processing call returns up to 100 of them, or let webhooks tell you.

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"

On your account the cancel is immediate and final: a queued or processing task becomes cancelled at once, its held credits return to your balance in the same step, and a task.cancelled webhook follows. Stopping the generation itself is best-effort: Five API asks the pipeline to stop, but a task that is already running on a GPU may still finish internally; its result is discarded and never charged. The 200 response therefore confirms that the task is cancelled for you, not that the GPU has stopped. 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