---
title: Task API quickstart
url: https://runapi.ai/docs/guides/task-api/quickstart.md
canonical: https://runapi.ai/docs/guides/task-api/quickstart
locale: en
---

# Task API quickstart

RunAPI uses Tasks for asynchronous image, video, audio, and music
generation. A create request returns quickly; your application then
polls the Task or receives a callback when it reaches a terminal state.

## Create a Task

Choose a model and endpoint in the Catalog, then send the endpoint's
required inputs. This example starts a Flux 2 text-to-image Task:

```shell
curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'
```

An accepted asynchronous request returns `202 Accepted` with a Task
identifier:

```json
{
  "id": "task_id",
  "status": "processing"
}
```

Store `id` with your application record. It is the stable identifier
used for polling, support, and callback reconciliation.

## Poll a Task

Append the Task identifier to the same endpoint path:

```shell
curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Continue while `status` is `processing`. Use bounded backoff between
requests instead of polling continuously. A Task becomes terminal when
its status is `completed` or `failed`.

## Handle completion

A `completed` response includes the Task `id`, terminal `status`, and
the endpoint-specific result fields. Persist the result you need and
stop polling. Consult the endpoint's API Reference for the exact result
shape rather than assuming every media endpoint returns the same fields.

## Handle failure

A `failed` response includes the Task `id`, terminal `status`, and a
RunAPI-authored `error` when one is available. Stop polling, record the
identifier and error, and retry only when your application has
classified the failure as transient. A retry creates a new Task
identifier.

## Receive a callback

Add a public HTTPS `callback_url` to the create request when you want
RunAPI to send the terminal payload to your application:

```json
{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}
```

The callback body has the same public shape as the terminal polling
response. Return a successful HTTP response quickly, process the event
idempotently by Task `id`, and keep polling available for reconciliation
when delivery is delayed or your callback handler is unavailable.