Guides

Task API quickstart

Create an asynchronous Task and handle polling, completion, failure, and callbacks.

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.