---
title: Quickstart | RunAPI
description: Create an asynchronous Task and handle polling, completion, failure,
  and callbacks.
url: https://runapi.ai/docs/guides/task-api/quickstart.md
canonical: https://runapi.ai/docs/guides/task-api/quickstart
locale: en
---

> HTML version: https://runapi.ai/docs/guides/task-api/quickstart
> Site index for agents: https://runapi.ai/llms.txt

# 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 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.

## Recover an interrupted synchronous request

Slow synchronous endpoints normally keep the connection open and return
the same terminal response as before. No polling changes are required
for existing integrations.

For an intentionally shorter connection budget, send `Prefer: wait=N`.
If the Task is still running after that explicit budget, RunAPI returns
`202 Accepted` with the same Task `id`, an opaque `Location` URL for
recovery, and `Retry-After` for the suggested query delay. Follow
`Location` exactly rather than constructing a result URL. A completed
Task Result preserves the terminal HTTP status, allowed headers, content
type, and body; decode `response.body` according to
`response.content_type`, which is not always JSON.

## 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](https://runapi.ai/docs/guides/task-api/callbacks.md) to create a Callback
Secret, verify signatures, and handle retries safely.

---

## More from RunAPI

- [Home](https://runapi.ai/.md)
- [Model Catalog](https://runapi.ai/models.md)
- [Pricing](https://runapi.ai/pricing.md)
- [Providers](https://runapi.ai/models)
- [Documentation](https://runapi.ai/docs/guides)
- [SDKs](https://runapi.ai/sdk.md)
- [CLI](https://runapi.ai/cli.md)
- [MCP Server](https://runapi.ai/mcp.md)
- [Claude Code vs Cursor](https://runapi.ai/claude-code-vs-cursor.md)
- [Cursor API Setup](https://runapi.ai/cursor-api-setup.md)
- [RunAPI vs OpenRouter](https://runapi.ai/openrouter-alternative.md)
- [Enterprise](https://runapi.ai/contact.md)
- [Contact](https://runapi.ai/contact.md)
- [Terms](https://runapi.ai/terms.md)
- [Privacy](https://runapi.ai/privacy.md)
- [Site index for agents](https://runapi.ai/llms.txt)

Contact: contact@runapi.ai

## Structured data

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "en",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "en",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/icon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "en",
    "@type": "TechArticle",
    "headline": "Quickstart",
    "description": "Create an asynchronous Task and handle polling, completion, failure, and callbacks.",
    "url": "https://runapi.ai/docs/guides/task-api/quickstart",
    "mainEntityOfPage": "https://runapi.ai/docs/guides/task-api/quickstart"
  }
]
```