> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bfl.ml/llms.txt
> Use this file to discover all available pages before exploring further.

# FLUX 3 Image Editing

> Edit an image with a written instruction, combine up to ten references, and use bounding boxes to place elements or target an edit with FLUX 3 Image.

FLUX 3 Image

# FLUX 3 Image Editing

Edit an image with a written instruction, combine up to ten references, and add bounding boxes to place elements or target an edit.

## Quickstart

Send an image in `images` and say what to change. This request recolors an owl
and keeps the rest of the photo as it was. Drag the handle to compare:

Previous clip

Next clip

Set `BFL_API_KEY` to a key from the [BFL dashboard](https://dashboard.bfl.ai), then submit:

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.bfl.ai/v1/flux-3-image",
    headers={"x-key": os.environ["BFL_API_KEY"]},
    json={
        "prompt": "In this image, change <owl_subject>, previously described as \"a short-eared owl in flight with brown and tan mottled feathers and yellow eyes\", to: a short-eared owl in flight with striking snowy white and charcoal grey mottled feathers and bright yellow eyes. Keep everything else in the image — composition, other elements, lighting, background — exactly unchanged.",
        "images": ["https://cdn.sanity.io/images/2gpum2i6/production/1731db585c799dbb4e2c48731ea0b5bfc92a47d7-1800x1193.webp"],
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```bash cURL theme={null}
curl --fail-with-body https://api.bfl.ai/v1/flux-3-image \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "In this image, change <owl_subject>, previously described as \"a short-eared owl in flight with brown and tan mottled feathers and yellow eyes\", to: a short-eared owl in flight with striking snowy white and charcoal grey mottled feathers and bright yellow eyes. Keep everything else in the image — composition, other elements, lighting, background — exactly unchanged.",
    "images": ["https://cdn.sanity.io/images/2gpum2i6/production/1731db585c799dbb4e2c48731ea0b5bfc92a47d7-1800x1193.webp"]
  }'
```

`aspect_ratio` defaults to `auto`, so the edit has the same aspect ratio as the
image you send. The output is `1k`. For the same size as the input image, up to 4MP,
set `resolution` to `match_input`. Poll the returned `polling_url` until `status` is `Ready`, then
download the image from `result.sample` within 1 hour.
[FLUX 3 Text to Image](https://docs.bfl.ml/flux_3/flux3_image_generate.md#quickstart) has complete
clients that submit, poll, and save.

## Edit with an instruction

These examples call `generate()` from the
[complete clients](https://docs.bfl.ml/flux_3/flux3_image_generate.md#quickstart), which submits a
request, polls until it is ready, and saves the image.

Send the image in `images` and write the change as an instruction. Name the
element precisely enough that only one thing in the image matches. This
request changes the color of one bird in a flock:

Previous clip

Next clip

```python theme={null}
generate({
    "prompt": "change the color of only one bird in the middle to #e01075",
    "images": ["https://cdn.sanity.io/images/2gpum2i6/production/4792198dfeba9223bf3ecf020fed2942de7f0bd7-1800x1200.webp"],
}, name="pink_bird")
```

With `aspect_ratio` left at `auto`, the output keeps the aspect ratio of the
image you send.

You don't have to draw a box for a single edit. Before it generates, FLUX 3
Image expands your instruction into a detailed prompt, and for many edits it
also finds the element you named and adds a box for it. The expanded prompt,
including any boxes it added, comes back in `result.prompt`. To control exactly
which elements change, use [bounding boxes](https://docs.bfl.ml/flux_3/flux3_image_bounding_boxes.md#edit-an-image).

## Multi reference

Refer to each image by its position or by what it shows. "Image 1" is the
first entry in `images`, "image 2" the second, and so on up to ten. Here,
image 1 is the scene and image 2 supplies the object to place in it:

replace the cartridge from image 1 with the van in image 2, adjust the lighting on the van to integrate well within image 1

```python theme={null}
generate({
    "prompt": "replace the cartridge from image 1 with the van in image 2, adjust the lighting on the van to integrate well within image 1",
    "images": [
        "https://cdn.sanity.io/images/2gpum2i6/production/ec365238b6efa1b29f573e83b774c6d539408ea8-1800x1200.webp",
        "https://cdn.sanity.io/images/2gpum2i6/production/ff3bf81b5a8b38f0d870561217b68a72964259ab-1131x1414.webp",
    ],
}, name="turntable_van")
```

With `aspect_ratio` at `auto`, the output uses the aspect ratio of the first
image in `images`. The turntable is first, so the result is landscape. For a
different shape, put a different image first or set `aspect_ratio`.

For product shots, try-ons, and group compositions, say how the images relate:
"the person from image 1 wears the jacket from image 2 and stands in the
kitchen from image 3".

## Examples

Each example shows the inputs, the result, and the prompt that produced it.

### Single Image Reference

Send one image and write the change as an instruction. Drag the handle to
compare:

Previous clip

Next clip

### Multi Image Reference

Refer to each image by its position in `images`. The output keeps the
aspect ratio of image 1.

**Replace an object with a new design**

use image 2 texture and shape to create a bag, and replace the bag in image 1. use #CC5500, #F5A623 #6B8E23 colors for the new bag.

**Add elements from several images**

Use image 1 as the main image. Insert the lake from image 2 on the left side of image 1, and make sure it blends naturally with the surroundings as if it is part of the garden view. Insert the ducks from image 3 into image 1, and make them appear as if they are near the lake on the grass

**Furnish a room**

Furnish the exact room in image 1 with the following items: the bed from image 2 on the left side of the room near the wall. on top of the bed the cushion from image 3. on the floor the carpet from image 4

### Edit with Bboxes

Each edit changes one boxed element and anchors the rest. Select an
example, then switch between before and after.

## Send a request

Copy a request body from the [bounding box examples](https://docs.bfl.ml/flux_3/flux3_image_bounding_boxes.md#examples)
and paste it where indicated below, including its outer braces. To adapt an edit to your image, update the image URL, element
descriptions, and source and target boxes.

```python Python theme={null}
import json

body = r'''
Paste the complete copied JSON body here.
'''
generate(json.loads(body))
```

```bash cURL theme={null}
curl --fail-with-body https://api.bfl.ai/v1/flux-3-image \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
Paste the copied request body here.
EOF
```

`generate()` is defined in the [complete clients](https://docs.bfl.ml/flux_3/flux3_image_generate.md#quickstart).
It submits the request, polls until the image is ready, and saves it. With
cURL, poll the returned `polling_url` until `status` is `Ready`, then download
`result.sample`.

> [accordion] Coordinate conversion and editing tips
>
> Use the aspect ratio you designed the layout for, because the grid
> stretches with the frame. For edits, `auto`
> follows the first reference; without a reference, it produces a square.
>
> ```python theme={null}
> def to_bbox(left, top, right, bottom, width, height):
>     return [round(top / height * 1000), round(left / width * 1000),
>             round(bottom / height * 1000), round(right / width * 1000)]
>
> to_bbox(384, 108, 1536, 972, 1920, 1080)  # [100, 200, 900, 800]
> ```
>
> To move or resize an element, use different source and target boxes.
> Use matching boxes to ask for it to stay in place. State additions and
> removals in the written instruction as well as the rows.
>
> Very small boxes can fail. In our tests, a new element in a box about
> 40 × 25 pixels often did not appear, so give new elements a larger box.
>
> Give text its own box and quote the words in `desc`.
> See [Layout prompts](https://docs.bfl.ml/guides/prompting_layout.md) for more examples.

> [accordion] Try drawing a box
>
> Draw over a marked region, or choose one below the image, then select
> an object. This demo uses saved edits and makes no API requests.
>
> Place an object
>
> Draw over a marked region and choose an object to see a saved edit in that region.
>
> Pre-generated edits
>
> ![A storybook forest clearing](https://docs.bfl.ml/images/flux3/bbox/base.webp)
>
> Reset edits

> [accordion] Pixel-perfect edits
>
> Pixels outside the boxes usually stay the same. Shadows, reflections,
> or nearby lighting may still change.
>
> Compare each input with its edit. Switch to Changed pixels to see which
> areas the edit touched.

## Keep exploring

> [card] [FLUX 3 Text to Image](https://docs.bfl.ml/flux_3/flux3_image_generate.md)
>
> Complete clients that submit, poll, and save, plus edits and
> multi-reference requests.

> [card] [API reference](https://docs.bfl.ml/api-reference/utility/generate-an-image-with-flux-3.md)
>
> The full request schema, limits, and response codes.

> [card] [Layout prompts](https://docs.bfl.ml/guides/prompting_layout.md)
>
> How to write the caption and element table for a layout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.