FLUX 3 Image bounding box API: boxes live inside the prompt

What this call is

FLUX 3 Image is the image part of Black Forest Labs' FLUX 3 family. The model page shows composition from boxes, edits that leave other regions alone, up to ten reference images, and native 2K and 4K output. The API contract is on FLUX 3 Image overview and the generate-an-image reference. This site is an independent layout guide. It is not Black Forest Labs.

Reseller APIs sometimes expose a field such as settings.boundingBoxes. That is their wrapper. On api.bfl.ai the published schema is Flux3ImageInputs with additionalProperties: false. Allowed fields are prompt, images, aspect_ratio, resolution, safety_tolerance, grounding, and version. A stray box field is a validation error, not a layout.

Draw the layout in the Playground first

The model page tells you to draw boxes by hand in the BFL Playground or to send the same layout to the API. The on-page walkthrough is four steps. Checked against that page on 3 October 2026.

1. Pick an aspect ratio. Whatever the shape, both axes are a 0 to 1000 grid.
2. Drag a box for every element that matters, and describe what goes in it.
3. Write one scene line that ties the elements together. The page's example cites each id, and the element table is a JSON array of id, bbox, and desc.
4. Generate. FLUX 3 Image is supposed to render each element inside its box.

The same page says you can skip boxes and send a plain prompt. Boxes are for compositions with strict relationships: type around a photo, panel grids, editorial spreads, crowded scenes. An agent can also draft the table from one line plus an aspect ratio. The page says a prompt upsampler may add suggested elements, but every box you drew is sent on with the same id and the same coordinates.

How to send a new layout

The bounding-box guide builds the prompt in three parts. Write one paragraph and mark each element with an angle-bracket id such as <title_1>. Add one JSON row per id. Join them with a single space: caption, space, JSON array. Send that string as prompt, and send the aspect ratio you designed the boxes for. The 0–1000 grid stretches with the frame, so a 16:9 box map is wrong on a 9:16 canvas.

A generation row has three fields: id, bbox, and desc. [0, 0, 500, 500] is the top-left quarter. Text gets its own row, with the exact words quoted in desc. The guide says boxes set placement and scale, not a clipping mask, and an element can extend slightly past its box.

curl -sS -X POST https://api.bfl.ai/v1/flux-3-image \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A square poster: cream serif title <title_1> across the top, a single red ceramic cup <cup_1> centered on a pale table. [{\"id\":\"title_1\",\"bbox\":[40,120,180,880],\"desc\":\"The words Morning List in a cream serif, one line.\"},{\"id\":\"cup_1\",\"bbox\":[280,300,820,700],\"desc\":\"A small red ceramic cup, handle on the right, soft shadow.\"}]",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "grounding": false
  }'

That body is a shortened illustration of the documented shape, not a copied launch prompt. resolution defaults to 1k. grounding defaults to true, which may run web and image search before generation. Set it false when you want the prompt alone. safety_tolerance is an integer from 0 (strictest) to 4, default 2. version defaults to latest.

The response is asynchronous. It returns id, polling_url, and cost in credits. Poll polling_url with the same x-key header until status is Ready, then download result.sample. The overview says to download that file within one hour. Status values listed on the get-result reference include Pending, Reasoning, Generating, Ready, Error, Request Moderated, Content Moderated, and Task not found. You can also GET /v1/get_result?id= with the task id.

Edit, move, or remove one element

Send the source image in images (one to ten items, each an http or https URL or base64, from 256 by 256 pixels up to 16 megapixels). The first image is ref_image_0. Edit rows replace bbox with from, src_bbox, and tgt_bbox. The guide's table:

State the change in the instruction as well as in the rows. Anchor anything that must not move with a keep row. With aspect_ratio set to auto (the default), a ratio named in the prompt wins; otherwise the output keeps the first reference framing. Several new rows in one request can change several elements at once. Multi-reference prompts cite images by position, up to ten, which the model page also shows in the Playground as tokens starting at ref_image_0.

To turn pixel rectangles into the grid, the guide uses round(top / height * 1000) and the same for left, bottom, and right. Design the numbers for the aspect ratio you will send.

Pricing and limits

Prices below are from the Black Forest Labs pricing page, fetched 3 October 2026. One credit equals $0.01. The page says Playground and API use the same price, and that the submit response includes cost. 1.5k is a legal resolution value and appears in the calculator on bfl.ai/pricing, but that docs table has no 1.5k row.

The marketing calculator's extracted text the same day showed both $0.048 and $0.024 on one rate line, without naming the selected resolution. Reseller pages (not Black Forest Labs) describe a 50 percent launch rate through 8 October 2026. The docs pricing page fetched here does not state that discount or an end date. Read cost on a real response before you budget. Commercial weights for self-hosting are a separate license on the model page. This guide does not apply for API keys.

Known limitations

• Boxes guide placement. They are not clipping masks, and an element can spill slightly past its box.
• In Black Forest Labs' own tests, a new element in a box of about 40 by 25 pixels often did not appear. Give new elements room.
• The guide says pixels outside edited boxes usually stay identical. That is not a promise that every untouched pixel is bit-locked, and news write-ups that say otherwise go past the guide.
• Unlisted areas usually hold, but the guide tells you to add a keep row for anything that must stay put. The instruction and the table should agree.
• The sample URL should be downloaded within one hour.
• Moderation can return Request Moderated or Content Moderated. safety_tolerance does not turn that off.
• Reference images outside 256 by 256 to 16 megapixels, or more than ten of them, are outside the documented input range.
• You need a Black Forest Labs API key. Nothing on this site generates images.

Related reading: FLUX 3 boxes compared with FLUX.2 prompt edits, the layout prompting guide, and image editing with boxes.