Async jobs

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

Create, then poll

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

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

# 1. Create — endpoint is the model slug
curl -X POST https://api.budgetpixel.com/v1/videos/seedance-1.5-pro \
  -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"

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

Errors

All errors share one envelope so you can branch on type and code:

{
  "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.
401	Missing or invalid API key.
403	Plan not enabled, ownership, or restriction.
404	Job not found (or not yours).
429	Rate or queue limit reached — retry after a short delay.

Get Started

MCP

Concepts

Lifecycle

Create, then poll

Errors

​Lifecycle

​Create, then poll

​Errors

Lifecycle

Create, then poll

Errors