;
};
Multi-reference editing combines several input images into one output. Use it to restyle a photo after an artwork, put a product into a scene, dress a person in garments from other photos, or keep a character consistent across variations. In the prompt, clarify the purpose of each image and how the pieces fit together.
## FLUX 3 example: put an object from one image into another
Image 1 is the scene and image 2 supplies the object, and the prompt names both roles. It also says how the new object should fit: the van takes the lighting of image 1. The result is landscape like the turntable because `aspect_ratio: "auto"` follows the first reference.
## How FLUX 3 reads multiple references
**Send up to 10 images.** FLUX 3 Image takes 1 to 10 entries in `images`, as URLs or base64 strings. Each must be at least 256 × 256 pixels and at most 16 megapixels.
**Refer to each image by position.** "Image 1" is the first entry in `images`, "image 2" the second, and so on. Use the same words every time you mention an image.
**Specify what each image supplies.** A reference can supply more than one feature, such as both the material and the background. Name those roles explicitly:
| Role | What it supplies | Example phrasing |
| - | - | - |
| Subject | A person, animal, or character to keep recognizable | “the woman in image 2” |
| Product | An object whose shape, color, and label you want to keep | “the bottle from image 3, label facing the camera” |
| Setting | The scene, room, or background everything goes into | “the kitchen in image 1” |
| Style | Palette, medium, texture, or lighting to apply | “in the style of image 4” |
**Say how the pieces relate.** Name positions and interactions, not only the parts: "the woman in image 2 sits on the swing in image 1, with the cat from image 3 on her lap."
**Put the base image first.** With `aspect_ratio: "auto"` (the default), the output takes its aspect ratio from image 1. Put the setting or base photo you are editing first, or set `aspect_ratio` explicitly when no reference has the shape you want.
## Specify an object’s position
A written instruction such as "put the lamp from image 2 on the sideboard" lets FLUX 3 choose the position. To specify it, add box rows to the end of the prompt. A row with `from: "ref_image_1"` takes an element from the second image: `src_bbox` marks the object in image 2, and `tgt_bbox` marks where it belongs in the output. Anchor rows (`from: "ref_image_0"` with the same source and target box) ask the model to keep those elements in place.
```python theme={null}
import json
room = "https://example.com/living-room.jpg" # image 1: the scene to edit
lamp = "https://example.com/ceramic-lamp.jpg" # image 2: the product
record = (
"Modify by placing the ceramic table lamp on the left end "
"of the oak sideboard . Keep the rest of the room exactly unchanged, "
"preserving the framed print above the sideboard."
)
rows = [
{"id": "lamp_1", "from": "ref_image_1", "src_bbox": [80, 250, 950, 750], "tgt_bbox": [300, 120, 560, 280], "desc": "a ceramic table lamp with a linen shade"},
{"id": "sideboard_1", "from": "ref_image_0", "src_bbox": [540, 60, 880, 940], "tgt_bbox": [540, 60, 880, 940], "desc": "an oak sideboard"},
{"id": "print_1", "from": "ref_image_0", "src_bbox": [120, 330, 420, 670], "tgt_bbox": [120, 330, 420, 670], "desc": "a framed botanical print"},
]
generate({
"prompt": f"{record} {json.dumps(rows)}",
"images": [room, lamp],
}, name="lamp_on_sideboard")
```
The coordinates are illustrative: measure the boxes on your own images, as `[top, left, bottom, right]` on a 0–1000 grid. `generate()` is the helper from [FLUX 3 Text to Image](/flux_3/flux3_image_generate#quickstart). Placement is a strong hint, not a hard constraint, and multi-reference compositions can place an element partly outside its box. [Edit with boxes](/flux_3/flux3_image_bounding_boxes#edit-an-image) covers every row type.
## More examples
These examples were generated with FLUX 3 Image. Hover an input to highlight where the prompt refers to it.
### Paintings on coins, from four references
One image sets the scene and three supply artwork. Each painting appears on its own coin, and the hand and page stay the same.
### A tower sinking into the sea
The tower is tilted and cut off at the waterline, with waves where it meets the sea.
### A knife made of candy
The shape comes from image 2 and the material and background come from image 1, including the loose candies around the edge.
### A heart in paper
Only the material changes. The shape, the veins, and the black background stay the same.
## Use cases
The categories below cover the most common multi-reference tasks, each with the prompt that produced the result. The "Animal placed in scene", "Pattern onto plate", "Fill bottles with liquid", and "Logo engraved in tree" results were generated with FLUX 3 Image. The rest were generated with FLUX.2.
***
### Scene Compositing
Combine elements from multiple source images into a single coherent scene.
FLUX.2 result:
FLUX.2 result:
***
### Style & Material Transfer
Apply the visual style, texture, or material of one image onto the content of another.
FLUX.2 result:
FLUX.2 result:
***
### Object Replacement
Replace or fill objects with elements from another reference image.
***
### Logo & Branding
Place logos from one image onto objects or scenes in another.
FLUX.2 result:
***
## Checklist: vague to specific
| Instead of | Write | What it adds |
| - | - | - |
| “Combine these images” | “Place the couple from image 2 at the table in image 4, with the view from image 1 through the window.” | A role and a position for each image |
| “Use the style of the other one” | “Turn image 1 into the style of image 2, keeping the temple’s shape and layout.” | Which image is which, and what to keep |
| “Add the product” | “Put the bottle from image 3 on the counter in image 1, label facing the camera, lit by the window on the left.” | The product’s placement, orientation, and light |
| “Make them wear it” | “The person from image 1 wears the jacket from image 2 and stands in the kitchen from image 3.” | How the pieces relate |
Write the instruction for one image, with a catalog of edit types.
Place and anchor elements with box rows.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.