Developer docs

Generation lifecycle

Statuses, polling, waiting, listing, cancelling and idempotency.

Statuses

Status	Meaning	Credits
`QUEUED`	Accepted, waiting for a worker	reserved
`PROCESSING`	Running at the provider; `progress` updates	reserved
`SUCCEEDED`	`outputs[]` ready	captured
`FAILED`	`error.code` / `error.message` explain why	refunded
`CANCELED`	Cancelled while queued	refunded

Read one

text

GET /v1/generations/{id}

Wait (long-poll)

text

GET /v1/generations/{id}/wait?timeout=30000

Holds the connection until the job reaches a terminal state or timeout ms (max 60 000) pass, then returns the generation. Loop on it for simple scripts; prefer webhooks in production.

List

text

GET /v1/generations?limit=24&cursor=…&modality=image&status=SUCCEEDED&model=gpt-image&q=mug

Returns { items, nextCursor }. Pass nextCursor back as cursor to page.

Cancel

text

POST /v1/generations/{id}/cancel

Only QUEUED jobs can be cancelled; the reservation is refunded. A job that already started cannot be cancelled (409 CONFLICT).

Delete

text

DELETE /v1/generations/{id}

Removes the generation and its outputs from your library and CDN.

Idempotency

Pass idempotencyKey (any string ≤ 128 chars, unique per account) when creating a job. Retrying the same request returns the existing generation instead of billing you twice. Keys never expire.

Error object

Failed generations carry:

json

"error": { "code": "CONTENT_BLOCKED", "message": "The provider rejected this prompt." }

`error.code`	Meaning
`CONTENT_BLOCKED`	Provider safety filter rejected prompt or image
`PROVIDER_ERROR`	Upstream failure after retries
`TIMEOUT`	Provider did not finish in time
`INVALID_INPUT`	Input image could not be fetched or was too large
`RATE_LIMITED`	Provider capacity; retry later

Credits are always refunded on failure.