Skip to main content
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

# 1. Create
curl -X POST https://api.budgetpixel.com/v1/images \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"...","modelName":"flux-2-klein"}'
# -> { "job_id": 3436, "status": "pending" }

# 2. Poll
curl https://api.budgetpixel.com/v1/images/3436 \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
Image job ids are integers; video job ids are UUIDs. Poll each at its own endpoint. 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."
  }
}
StatusWhen
400Malformed request, missing/model_not_available model.
401Missing or invalid API key.
403Plan not enabled, ownership, or restriction.
404Job not found (or not yours).
429Rate or queue limit reached — retry after a short delay.