Async Jobs: Create, Poll, Complete

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

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.

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

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.

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

{
  "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:

{
  "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.

Get Started

MCP

Stock Images

ComfyUI

WordPress

Embeds

Concepts

Async Jobs: Create, Poll, Complete

Lifecycle

Create, then poll

Errors

Content moderation blocks

​Lifecycle

​Create, then poll

​Errors

​Content moderation blocks

Lifecycle

Create, then poll

Errors

Content moderation blocks