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

# Async Jobs: Create, Poll, Complete

> How asynchronous generation works in the BudgetPixel API — create a job at the model's endpoint, poll its status, and fetch the result when it succeeds.

Generation is **asynchronous**. You submit a job, receive an id immediately, then
poll until the job reaches a terminal state.

## Lifecycle

A job moves through these statuses:

```
pending → starting → processing → completing → succeeded
                                              ↘ failed
                                              ↘ timeout
```

`succeeded`, `failed`, and `timeout` are **terminal** — stop polling once you see
one. On `succeeded`, the result is available on the status response (an `images`
array for image jobs, a `video_url` for video jobs, an `audio_url` for music and
sound-effect jobs).

Video jobs also report `video_codec`. Most outputs are H.264, but a few
high-definition tiers deliver H.265 (HEVC), which does not play in every browser —
see [video output format](/concepts/models#video-output-format).

## Create, then poll

Image, video, and audio jobs are all created at per-model endpoints
(`POST /v1/images/{model-name}`, `POST /v1/videos/{model-name}`,
`POST /v1/audios/{model-name}`), then polled at the matching status endpoint.

<CodeGroup>
  ```bash Image theme={null}
  # 1. Create — endpoint is the model slug
  curl -X POST https://api.budgetpixel.com/v1/images/flux-2-pro \
    -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"prompt":"...","num_images":1}'
  # -> { "id": "img_a1b2c3d4e5f6", "status": "pending" }

  # 2. Poll
  curl https://api.budgetpixel.com/v1/images/img_a1b2c3d4e5f6 \
    -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
  ```

  ```bash Video theme={null}
  # 1. Create — endpoint is the model slug
  curl -X POST https://api.budgetpixel.com/v1/videos/seedance-2.0 \
    -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"prompt":"...","length_seconds":5}'
  # -> { "id": "...", "status": "pending" }

  # 2. Poll
  curl https://api.budgetpixel.com/v1/videos/{id} \
    -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
  ```
</CodeGroup>

<Note>
  Job ids are opaque — treat them as strings and poll each at its own type's status
  endpoint (`/v1/images/{id}`, `/v1/videos/{id}`, or `/v1/audios/{id}`). A reasonable
  polling interval is every few seconds — images and sound effects typically finish in
  seconds, music and video in a few minutes.
</Note>

## Errors

Errors share one envelope so you can branch on `type` and `code` (the exception is
content moderation blocks, which use a flatter shape — see below):

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "model_not_available",
    "message": "Model 'xyz' is not available via the API."
  }
}
```

| Status | When |
| - | - |
| 400 | Malformed request, missing/`model_not_available` model, or content moderation block (see below). |
| 401 | Missing or invalid API key. |
| 403 | Plan not enabled, ownership, or account restriction. |
| 404 | Job not found (or not yours). |
| 429 | Rate or queue limit reached — retry after a short delay. |

### Content moderation blocks

When a prompt or input image is blocked by content moderation, the request fails
with **400** and a response carrying a stable `restriction_reason` you can branch
on. The block is about the request's content, not your account or key — reword the
prompt or change the input media and retry:

```json theme={null}
{
  "error": "Generation of sexually explicit content is not permitted. Please adjust your input image or prompt.",
  "restriction_reason": "input_explicit_adult"
}
```

| `restriction_reason` | Meaning |
| - | - |
| `input_explicit_adult` | Prompt or input media describes sexually explicit content. |
| `input_upload_nudity` | An uploaded photo contains nudity. |
| `input_celebrity_likeness` | Input photo appears to depict a real public figure. |
| `strict_model_nsfw` | Prompt contains explicit terms this model's provider prohibits. |
| `input_csam` | Prompt appears to sexualize minors. |


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