Flux RouterDocumentation

POST /v1/images/generations and /v1/images/edits

The exact contract for Flux image generation and image edits: request fields, the streaming events, the response, headers and every error.

Generate an image from a prompt, or edit one with reference images. For a guided tour, see Make and edit images.

EndpointBodyStatus
POST https://api.fluxrouter.ai/v1/images/generationsJSONLive
POST https://api.fluxrouter.ai/v1/images/editsmultipart formLive

Both take your Flux key as Authorization: Bearer sk-flux... (or x-api-key). Both need a paid, cleared plan, and the key's model allowlist must include the model you ask for.

Generations: request

FieldTypeRequiredNotes
promptstringYesWhat to draw.
modelstringNoAn image model id. Leave it out for the default, flux-image. The list is on GET /v1/models with capability set to image.
nintegerNoHow many images. Default 1. Each image is billed.
sizestringNoDefault 1024x1024. Most models make their own fixed size and ignore it.
qualitystringNoChanges the price, not the request shape.
response_formatstringNoDefault b64_json.
categorystringNoStandard (default), Plus, Pro or Ultra. Picks a model for that price class when you do not name one.
max_pricenumberNoThe most you will pay, in US dollars, checked against the final price. Over it, the call answers 402 price_exceeds_max_price, returns no image and charges nothing.
streambooleanNotrue for server-sent events (below).
partial_imagesintegerNoWith stream, how many rough previews to send first, from 0 to 3. Higher values are lowered to the maximum, not refused.

A chat-shaped body works too: send messages with "tools": [{ "type": "image_generation" }] and no prompt, and the prompt is taken from the last user message.

Edits: request

A multipart/form-data body.

FieldRequiredNotes
image[] (or image)YesBetween one and 4 reference images: PNG, JPEG or WebP. Each up to 10 MB, and up to 20 MB in total.
promptYesThe change to make.
modelNoDefault flux-image. Edits work on flux-image and flux-image-pro; other models answer 400 edit_unsupported.
size, quality, response_format, category, max_priceNoAs for generations.

An edit always returns exactly one image, and does not stream.

Response

json
{
  "created": 1790000000,
  "data": [{ "b64_json": "iVBORw0KGgo..." }]
}

  • data holds one entry per image, each with b64_json (or url).

  • An edit response also carries model and a usage object that includes the cost.

  • The response may carry other fields. Ignore any you do not use.

  • A generation response does not carry its cost. Use max_price to cap it, and see each call on your usage page.

  • In an edit response, usage.cost is what the call cost, in US dollars, once the charge has landed.

Generation times out after 60 seconds, and an edit after 90 seconds. Image calls do not count against the shared per-minute limit for audio and search.

Streaming events

With "stream": true on a generation, the response is text/event-stream:

Event typeCarries
image_generation.partial_imagepartial_image_index and a rough b64_json. Only on models that support previews, and only when you set partial_images.
image_generation.completeddata, shaped like the normal response, and the final b64_json
errorAn error object, when something fails after the stream has started

The stream ends with data: [DONE]. Models without previews send only the completed event, so one client handles every model.

data: {"type":"image_generation.partial_image","created":1790000000,"partial_image_index":0,"b64_json":"..."}

data: {"type":"image_generation.completed","created":1790000000,"data":[{"b64_json":"..."}],"b64_json":"..."}

data: [DONE]

Errors

Most errors use the ability shape, {"error": {"message", "type", "code"}}. A credit refusal can arrive wrapped as {"detail": {"error": {...}}}; read detail.error when error is missing.

StatuscodeMeaningFix
400noneprompt missing, or n not a whole numberFix the body.
400edit_unsupportedThe model cannot edit.Use flux-image or flux-image-pro.
400invalid_reference_imageA reference image is the wrong type, too big, or there are too many.Check the file limits above.
400moderation_blockedThe prompt was refused (type image_generation_user_error).Change the prompt. Retrying the same prompt fails again.
401, 403permission_errorThe key is missing or wrong, or its allowlist does not include this model.Check the key and its allowlist on your keys page.
402premium_lockedImages need a paid, cleared plan. Nothing was made or charged.Upgrade in Billing.
402price_exceeds_max_priceThe final price was above your max_price. No image is returned and nothing is charged.Raise max_price, or pick a cheaper model.
403organization_must_be_verifiedThe chosen model is not available for this request.Pick another model.
404noneImages are not switched on for this account.Contact support.
502capability_unavailableThe image could not be made or priced. Not charged.Retry shortly.

Fixes in more detail are on Image problems.