# Reference Images

Reference images give the model a visual anchor for generation. Instead of generating entirely from a text prompt, you provide one or more images that the model uses to guide composition, style, subject, or structure — producing outputs that stay visually consistent with your input material.

***

#### What Reference Images Do

When you upload a reference image, the model uses it to influence how the generated output looks. Depending on your prompt and the model selected, reference images can guide:

* **Style and aesthetic** — the visual tone, color palette, and rendering style of the output
* **Composition and structure** — how subjects and elements are arranged in the frame
* **Subject consistency** — keeping a specific person, product, or object visually consistent across multiple generations
* **Environment and setting** — the spatial context and background characteristics

Reference images are most powerful when combined with a clear prompt that specifies what to change and what to preserve.

***

#### Uploading Reference Images

**To upload a reference image:**

1. Click the **Upload** area or drag and drop your image into the reference image zone
2. Select your file from your device
3. The image thumbnail appears confirming it is attached
4. Write your prompt describing what to generate from or around the reference
5. Configure output settings and generate

**To select from history:** Instead of re-uploading, select previously generated or uploaded images directly from your workspace history. Use the **All** view to see both generated and uploaded images in a unified library — saving time when iterating on existing assets.

***

#### Per-Model Reference Image Limits

Reference image support varies by model. Only the following models support image uploads:

| Model               | Max Reference Images |
| ------------------- | -------------------- |
| **Nano Banana Pro** | Up to 13             |
| **Nano Banana 2**   | Up to 13             |
| **GPT Image 2**     | Up to 15             |
| **Flux 1.1 Pro**    | Up to 8              |
| **Flux Dev**        | Up to 8              |

See [Image Models →](/model-reference/image-models.md) for full model capabilities.

***

#### Supported Formats & Limits

| File Type  | Supported Formats | Size Limit          |
| ---------- | ----------------- | ------------------- |
| **Images** | JPG, PNG          | Max 20 MB per image |

***

#### Using Multiple Reference Images

Models that support multiple reference images — Nano Banana Pro, Nano Banana 2, and GPT Image 2 — allow you to upload several references simultaneously. The model blends elements from all uploaded images to produce the output.

This is useful for:

* **Style + subject separation** — upload a subject reference and a separate style reference, then prompt the model to apply the style to the subject
* **Multi-element composition** — upload references for different elements in a scene (subject, environment, lighting) and let the model combine them
* **Brand consistency** — upload multiple brand asset references so the model understands the visual language before generating new assets

**Example:** A brand wants to generate a new product lifestyle image consistent with their existing photography. Upload 3–5 existing product photos as references, write a prompt describing the new scene, and the model generates an output that matches the established visual style.

***

#### Writing Prompts for Reference-Guided Generation

When using reference images, structure your prompt to specify what to change and what to preserve:

**What to change:**

```
Change the background to a snowy mountain landscape.
Replace the clothing with a medieval knight's armor.
Apply a watercolor painting style to this photograph.
```

**What to preserve:**

```
Keep the facial features and expression unchanged.
Maintain the product shape and proportions exactly.
Preserve the overall composition and subject positioning.
```

**Combined example:**

```
Transform this product photograph into a cinematic studio shot —
keep the product shape and proportions unchanged, replace the
background with a deep navy gradient, add dramatic key lighting
from the upper left, highly detailed, 4K.
```

***

#### Best Practices

* **Use clean, high-quality source images** — blurry, low-resolution, or heavily compressed references produce lower quality outputs
* **Match aspect ratio to your output dimensions** — uploading a portrait reference for a landscape output results in cropping or distortion
* **Be explicit in your prompt** — reference images guide the model but your prompt directs it. The clearer your prompt, the more accurately the model uses the reference
* **Start with one reference before adding more** — if results are inconsistent, reduce the number of references rather than adding mo


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qolaba.ai/image-generation/input-controls/reference-images.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.