FLUX 3 Image: a guide to layout boxes and targeted edits

FLUX 3 Image lets you describe where individual elements should go, using rectangles as part of an image prompt. The same system supports edits to a reference image: each element can have a source position, a destination and a description of what should change. Black Forest Labs added the image endpoint to its release notes on October 1, 2026.

For designers and creators, the useful distinction is between planning a whole composition and changing an element in an existing image. This guide explains how to choose between them, translate a rectangle into the required coordinates, and retrieve an API result. This is a documentation-only guide, checked October 3, 2026. BIG CHANGE did not generate or edit an image with the product.

The big change

• What changed: BFL's October 1 release documents composition and editing through v1/flux-3-image. A scene description and JSON element table share one prompt, with boxes specifying positions or edits. BFL release notes
• Why it matters: Creators can translate a planned rectangle into coordinates, then specify which reference elements to keep, move or replace. The practical choice is how much to define: a whole composition, a simple instruction or an explicit editing table. BFL box tutorial
• What to watch: Choose a resolution and budget before submitting: the listed 1k and 4k prices are $0.048 and $0.607 per image. Inspect the full result because boxes can allow spillover and an edit can affect nearby lighting, shadows or reflections. BFL pricing, editing limits

Choose the browser or API route

BFL's product page describes two entry points: draw boxes in its browser Playground or send a layout prompt through the API. The documentation links to Playground for use without code. Use the browser route if you want to draw the regions directly; use the API if you need to supply coordinates in a request and retrieve the output programmatically. We have not inspected the current Playground controls, so the instructions below explain the documented request format rather than a sequence of browser buttons.

For the API, create a BFL account, add credits and obtain a key from the dashboard. Submit JSON with a POST request to https://api.bfl.ai/v1/flux-3-image, using Content-Type: application/json and the key in the x-key header. Only prompt is required. BFL generation guide, pricing and setup

FLUX 3 Image and FLUX 3 Dev must be kept distinct: these instructions cover BFL's hosted Image endpoint. The Image product page offers a commercial weights license through sales. The sources checked for this guide do not establish an open-weight download for FLUX 3 Image. FLUX 3 Image access

Decide how much of the image to specify

BFL says a simple edit can automatically acquire a box during prompt expansion. For explicit control, supply your own table. In ordinary instructions, "image 1" means the first reference; in editing rows, the same reference is ref_image_0. BFL editing guide

References go in images as URLs or base64 data, as a string or list. When supplied, there can be 1 to 10, each from 256 × 256 pixels to 16 megapixels. The default aspect_ratio is auto: it follows the first reference, or produces a square when no reference is supplied. Set it explicitly when your layout needs a particular shape. BFL endpoint overview

Translate a rectangle into a box

Every box is [top, left, bottom, right], with integer coordinates from 0 to 1000. Vertical coordinates come first. Each axis spans the whole image independently, so the grid stretches to fit a landscape or portrait canvas. BFL box format

To convert pixel positions, divide the top and bottom by the image height, and the left and right by its width. Multiply each answer by 1000 and round. BFL's documented conversion uses a 1920 × 1080 canvas:

The box is therefore [100, 200, 900, 800]. Its vertical span is 10% to 90% of the frame; its horizontal span is 20% to 80%. This arithmetic explains why swapping width and height, or entering left before top, changes the intended region. Keep the aspect ratio used to design the layout. BFL coordinate conversion

Compose a new image

Write a description of the whole composition, naming elements with <id> markers. Append a JSON array with an id, bbox and desc for each element. The array is text inside prompt, not another top-level API field.

BFL's documented running-silhouette example has a background covering the canvas and a figure occupying the central box. This shortened request follows that example's layout; it has not been run by BIG CHANGE:

{
  "prompt": "A black running silhouette <silhouette_1> on a chartreuse background <background_1>. [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"Chartreuse background with paper texture\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"Black running silhouette with stippled texture\"}]",
  "aspect_ratio": "1:1",
  "resolution": "1k"
}

For a layout containing text, give each line its own row and put the exact requested words in desc. Boxes guide placement and scale; BFL warns that an element can extend beyond its rectangle. They are not hard clipping masks. BFL composition tutorial and limits

Edit an existing image

Supply the source in images. Editing rows retain id and desc but replace bbox with these fields:

Join the instruction and editing array into prompt, as with composition. Describe additions and removals in both places. Add keep rows for elements that must stay in place. BFL's guide says pixels outside boxes usually remain the same, but nearby lighting, reflections and shadows can change. Compare the whole output with the source before accepting an edit. BFL also reports that new elements in boxes around 40 × 25 pixels often failed to appear in its own tests; this is a vendor observation, not a universal minimum or a BIG CHANGE test. BFL editing guidance, editing row schema

Choose resolution and budget

The overview lists 768sq, 1k, 1.5k, 2k and 4k, with 1k the default. The pricing page publishes the following rates; it does not list a 1.5k price. Check that option's cost before using it. BFL overview

These are BFL's listed US dollar prices, checked October 3. The ten-request column is arithmetic, not measured spending. BFL lists the same price for API and Playground, with one credit equal to $0.01. The submission response includes cost. A 4k request is about 12.6 times the listed cost of 1k; choose the output size your task requires and budget for additional attempts. Changing resolution is a new request, and this guide does not establish that two requests will produce the same composition. BFL pricing

The optional grounding setting defaults to true, enabling web and image search before generation. BFL says turning it off gives faster results using only the prompt. We have not measured that speed difference or verified the accuracy of grounded output. BFL grounding documentation

Submit, poll and save the output

After submitting, retain the returned polling_url and poll that exact URL with your API key. It points to the region holding the task. Pending, Reasoning and Generating mean the task is still running. At Ready, download result.sample; its signed link expires after one hour. Do not send your x-key header to the download URL. The result also contains result.prompt, showing the expanded instruction, and result.duration, the generation time. BFL retrieval instructions

A blocked or failed task needs a different response from a running one. Request Moderated means an input was blocked; Content Moderated means the output was blocked. Adjust the input before another attempt. For Error, inspect the response; an unknown or expired task returns Task not found. BFL warns that a failed task can arrive as HTTP 503 with a normal JSON body, so read its status before retrying. Oversized references produce 400; an unknown field, invalid value, blank prompt or undersized image can produce 422. Fields such as seed, width and input_image from other endpoints are not accepted here. BFL generation and error guide

The attempt is complete when you have saved the output and inspected its placement, any requested text and the surrounding areas of an edit. A Ready response establishes that a result is available; your visual review determines whether it meets the task.

Sources & further reading

• FLUX 3 Image product page: establishes the browser/API routes and commercial weights access. Its demonstrations are vendor material, not our test results.
• October 1 release notes: dates the image release and describes the shared endpoint. Broad control claims are read alongside the narrower limitations in the tutorials.
• Endpoint overview: supplies parameters, reference limits, resolution choices and grounding behavior.
• Bounding-box tutorial: explains the two row schemas and the running-silhouette example adapted above.
• Editing guide: supports coordinate conversion, reference ordering and the caveats about small regions and surrounding pixels.
• Generation guide: documents authentication, asynchronous retrieval, expiring links and errors.
• Pricing: supplies the rates used in our arithmetic. Recheck prices and request parameters before paying for an attempt; these are live documents.