> ## Documentation Index
> Fetch the complete documentation index at: https://testweb2-docs-openapi.test765.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Five API is a video generation REST API. Base URL: https://api.fiveapi.ai. Authenticate with the header Authorization: Bearer <API key>; read the key from the FIVEAPI_API_KEY environment variable and never hard-code it.
> Every generation is an asynchronous task: POST /v1/{brand}/{version}/{task} returns a queued task, then poll GET /v1/tasks/{task_id} or receive a signed webhook, and download output.video.url before expires_at (7 days).
> The OpenAPI spec is at https://docs.fiveapi.ai/api-reference/openapi.yaml. An installable agent skill: npx skills add https://docs.fiveapi.ai

# Tasks

> The lifecycle of a generation task: statuses, polling, the result, cancellation and retention.

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

```mermaid theme={null}
stateDiagram-v2
    [*] --> queued: create the task
    queued --> processing: generation starts
    processing --> completed: video ready (credits charged)
    queued --> failed: input problem
    processing --> failed: error.code explains why (hold released)
    queued --> cancelled: you cancel
    processing --> cancelled: you cancel, hold released
    completed --> [*]
    failed --> [*]
    cancelled --> [*]
```

| 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

```json theme={null}
{
  "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](https://testweb2-docs-openapi.test765.com/concepts/models.md#common-request-fields), 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)**

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](https://testweb2-docs-openapi.test765.com/concepts/webhooks.md).

**Polling**

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

```python theme={null}
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](https://testweb2-docs-openapi.test765.com/concepts/rate-limits.md). 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`:

```bash theme={null}
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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.