Markdown edition

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

> Use FLUX 3 Image layout boxes and reference images for composition or targeted edits. A documentation-based guide to coordinates, retrieval, prices and limits.

By BIG CHANGE Editorial

Published: 2026-10-03T04:10:59.237Z
Updated: 2026-10-03T04:10:59.237Z
Canonical: https://bigchange.ai/blog/flux-3-image-layout-editing-guide

![Conceptual charcoal illustration of one right hand placing a flat runner cutout on an orange square art backing.](https://bigchange.ai/api/media/file/flux-layout-collage-hero-v1.png)
AI-generated conceptual editorial illustration by BIG CHANGE.

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](https://docs.bfl.ai/release-notes).

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](https://docs.bfl.ai/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](https://docs.bfl.ai/flux_3/flux3_image_bounding_boxes)
- **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](https://docs.bfl.ai/quick_start/pricing), [editing limits](https://docs.bfl.ai/flux_3/flux3_image_layout)

## Choose the browser or API route

BFL's [product page](https://bfl.ai/models/flux-3-image) describes two entry points: draw boxes in its browser Playground or send a layout prompt through the API. The [documentation links to Playground](https://playground.bfl.ai) 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](https://dashboard.bfl.ai). 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](https://docs.bfl.ai/flux_3/flux3_image_generate), [pricing and setup](https://docs.bfl.ai/quick_start/pricing)

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](https://bfl.ai/models/flux-3-image)

## Decide how much of the image to specify

| Task | Documented input | Control to use |
| --- | --- | --- |
| Generate a new composition | A scene prompt, optionally followed by an element table | `bbox` for each element whose placement matters |
| Change an identifiable detail | An instruction and one reference image | A precise description can be enough; inspect the expanded prompt |
| Choose exactly which elements to edit | An instruction, reference image and editing table | Source and target boxes, with keep rows for elements to preserve |
| Combine references | A prompt explaining their roles and 2 to 10 images | Identify which image supplies each subject, object or setting |

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](https://docs.bfl.ai/flux_3/flux3_image_layout)

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](https://docs.bfl.ai/flux_3/flux3_image_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](https://docs.bfl.ai/flux_3/flux3_image_bounding_boxes#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:

| Edge | Pixel position | Calculation | Grid value |
| --- | --- | --- | --- |
| Top | 108 | 108 ÷ 1080 × 1000 | 100 |
| Left | 384 | 384 ÷ 1920 × 1000 | 200 |
| Bottom | 972 | 972 ÷ 1080 × 1000 | 900 |
| Right | 1536 | 1536 ÷ 1920 × 1000 | 800 |

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](https://docs.bfl.ai/flux_3/flux3_image_layout#send-a-request)

## 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:

```json
{
  "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](https://docs.bfl.ai/flux_3/flux3_image_bounding_boxes)

## Edit an existing image

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

| Operation | `from` | `src_bbox` | `tgt_bbox` |
| --- | --- | --- | --- |
| Keep an element | `"ref_image_0"` | Its source box | The same box |
| Move or resize it | `"ref_image_0"` | Its source box | A different destination box |
| Add, replace or recolor | `null` | `null` | The desired output box |
| Remove it | `"ref_image_0"` | Its source box | `null` |

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](https://docs.bfl.ai/flux_3/flux3_image_layout), [editing row schema](https://docs.bfl.ai/flux_3/flux3_image_bounding_boxes#edit-an-image-box-by-box)

## 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](https://docs.bfl.ai/flux_3/flux3_image_overview)

| Resolution | Documented output size | Price per image | Ten requests, calculated |
| --- | --- | --- | --- |
| `768sq` | 768 × 768 | $0.041 | $0.41 |
| `1k` | About 1 megapixel | $0.048 | $0.48 |
| `2k` | About 4 megapixels | $0.100 | $1.00 |
| `4k` | About 16 megapixels | $0.607 | $6.07 |

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](https://docs.bfl.ai/quick_start/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](https://docs.bfl.ai/flux_3/flux3_image_overview#ground-the-prompt)

## 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](https://docs.bfl.ai/flux_3/flux3_image_generate#results-and-errors)

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](https://docs.bfl.ai/flux_3/flux3_image_generate)

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](https://bfl.ai/models/flux-3-image): establishes the browser/API routes and commercial weights access. Its demonstrations are vendor material, not our test results.
- [October 1 release notes](https://docs.bfl.ai/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](https://docs.bfl.ai/flux_3/flux3_image_overview): supplies parameters, reference limits, resolution choices and grounding behavior.
- [Bounding-box tutorial](https://docs.bfl.ai/flux_3/flux3_image_bounding_boxes): explains the two row schemas and the running-silhouette example adapted above.
- [Editing guide](https://docs.bfl.ai/flux_3/flux3_image_layout): supports coordinate conversion, reference ordering and the caveats about small regions and surrounding pixels.
- [Generation guide](https://docs.bfl.ai/flux_3/flux3_image_generate): documents authentication, asynchronous retrieval, expiring links and errors.
- [Pricing](https://docs.bfl.ai/quick_start/pricing): supplies the rates used in our arithmetic. Recheck prices and request parameters before paying for an attempt; these are live documents.

## Sources

- [FLUX 3 Image](https://bfl.ai/models/flux-3-image) — establishes the browser/API routes and commercial weights access. Its demonstrations are vendor material, not our test results. The checked sources do not establish an open-weight download for this Image endpoint.
- [FLUX 3 Image overview](https://docs.bfl.ai/flux_3/flux3_image_overview) — supplies parameters, reference limits, resolution choices and grounding behavior.
- [FLUX 3 Image layout and editing](https://docs.bfl.ai/flux_3/flux3_image_layout) — supports coordinate conversion, reference ordering and the caveats about small regions and surrounding pixels.
- [FLUX 3 Image generation](https://docs.bfl.ai/flux_3/flux3_image_generate) — documents authentication, asynchronous retrieval, expiring links and errors.
- [Release notes](https://docs.bfl.ai/release-notes) — dates the image release and describes the shared endpoint. Broad control claims are read alongside the narrower limitations in the tutorials.
- [Pricing](https://docs.bfl.ai/quick_start/pricing) — supplies the rates used in our arithmetic. Recheck prices and request parameters before paying for an attempt; these are live documents.
- [FLUX 3 Image bounding boxes](https://docs.bfl.ai/flux_3/flux3_image_bounding_boxes) — explains the two row schemas and the running-silhouette example adapted above.