Guides

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 the callback events listed in that endpoint’s API Reference.

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 "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -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.

Prevent duplicate Task creation

Task-creation endpoints accept an optional Idempotency-Key header with an opaque value of up to 512 characters. Generate one value for each logical Task and keep it with the request until you know whether it was accepted.

If a timeout or connection failure leaves the result unknown, retry the exact same Task creation request with the same key. RunAPI returns the original Task instead of creating and charging for a second one. Reusing a key with a different Task creation request returns 409 Conflict. Generate a new key for an intentionally new Task, and do not use X-Client-Request-Id as this key.

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 callback events documented for that endpoint:

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"
}

Each callback body matches one lifecycle event in the endpoint’s API Reference and omits polling-only billing details. Terminal callbacks include the same result fields as terminal polling responses; some endpoints also send documented processing callbacks. Return a successful HTTP response quickly and keep polling available for reconciliation when delivery is delayed or your callback handler is unavailable.

Read Callbacks to create a Callback Secret, verify signatures, and handle retries safely.