Generations

A generation is one request to one model. Its id (prefixed gen_) is also returned as the x-request-id response header and is what you quote to support.

Create a generation

POST /v1/generations

Returns 202 Accepted and a generation object. Check its status, credits and credits_refunded; a replay can return a completed generation, and a submission that was immediately refunded can already be failed.

All request fields are top-level, alongside model. Seedream 5.0 Lite rejects unknown fields; Nano Banana models ignore them. See each model reference for its exact contract. Validation failures return 400 invalid_request with an issues array naming each field.

curl https://flux1.ai/api/v1/generations \
  -H "Authorization: Bearer $FLUX1_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: portrait-edit-6ee93274-535c-47da-af94-395ac1b92327" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "replace the background with a quiet forest, keep the person unchanged",
    "images": ["https://example.com/portrait.jpg"],
    "aspect_ratio": "4:5",
    "resolution": "2K"
  }'

Retry safely with Idempotency-Key

Send an Idempotency-Key header when creating a generation. Generate one unique value per intended generation and keep that value and the JSON body unchanged across retries. A UUID works well. The header is optional; requests without it are independent and may each generate an image and spend credits.

• Keys contain 1–128 printable ASCII characters without spaces. Each API key has its own namespace; changing your API key starts a separate namespace.
• The first reserved request owns the key. Repeated requests return the original generation ID and its current state, without another debit or provider submission. x-request-id is also the original ID. Concurrent retries can initially see queued with credits: 0 while the first request is preparing its debit.
• Reusing a key with a different JSON body returns 409 idempotency_conflict. Object property order does not matter; array order, prompt whitespace, omitted versus explicit defaults, and otherwise ignored fields do matter. The fingerprint covers the full input, including inline images and prompt text omitted from the usage log.
• A recorded pre-debit rejection, such as insufficient credits, keeps its original error and request ID on retry. After fixing that condition, use a new key for a new attempt. Validation failures or concurrency rejection before a reservation do not claim the key.
• Keys are retained with request records for at least 180 days. After a terminal record is removed, its key can be treated as new. Pending requests and unresolved recovery records remain protected from cleanup.
• Replays still require an active API key and current whitelist access, and count toward request rate limits. They do not use an additional concurrent generation slot.

On a timeout or 500 / 502 / 503, retry with the same key and body, or query the generation ID if you received one. Do not switch to a new key merely because a response was lost. If provider acceptance cannot be confirmed, the original request remains under review; retries do not resend it to the provider.

Get a generation

GET /v1/generations/{id}

Returns the current state. The body has the same shape at every stage. credits records the actual debit and stays at that amount after a refund; credits_refunded records whether the refund completed.

{
  "id": "gen_5Qa9…",
  "status": "failed",
  "credits": 10,
  "credits_refunded": true,
  "output": null,
  "error": { "code": "generation_failed", "message": "model error" },
  …
}

completed_at is recorded when we observe the result, so it is accurate to within your polling interval.

List generations

GET /v1/generations

Your account's requests, newest first, including rejected ones. Cursor-paginated.

curl "https://flux1.ai/api/v1/generations?limit=20&status=failed" \
  -H "Authorization: Bearer $FLUX1_API_KEY"

{
  "data": [ { "id": "gen_…", "status": "failed", … } ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0wNlQwMjo1ODowMS4wMDBaIiwiaWQiOiJnZW5f…"
}

next_cursor is null on the last page.