> For the complete documentation index, see [llms.txt](https://docs.qolaba.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qolaba.ai/api-platform/image-generation/image-to-image.md).

# Image-to-Image

Edit, transform, and compose images using Nano Banana Flash and Nano Banana Pro — Google Gemini-powered models that understand both text and images simultaneously.

Image-to-Image  API

`POST /api/v1/images/generate`

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### Model Overview

|                                      | `vertex/nano-banana-flash`     | `vertex/nano-banana-pro`   |
| ------------------------------------ | ------------------------------ | -------------------------- |
| **Underlying model**                 | gemini-3.1-flash-image-preview | gemini-3-pro-image-preview |
| **Provider**                         | Google Gemini / Vertex AI      | Google Gemini / Vertex AI  |
| **Speed**                            | Faster                         | Slower                     |
| **Quality**                          | High                           | Excellent                  |
| **Max resolution**                   | 4K                             | 4K                         |
| **Quality tiers**                    | `512`, `1K`, `2K`, `4K`        | `1K`, `2K`, `4K`           |
| **Max source images** (`image_urls`) | 14                             | 14                         |
| **Max reference images**             | 14                             | 14                         |
| **Search grounding**                 | Yes                            | No                         |
| **Text rendering**                   | Good                           | Excellent                  |
| **Subject consistency**              | Good                           | Excellent                  |
| **Cost per image (2K)**              | \~$0.08                        | \~$0.161                   |

***

### Capabilities

Both models support the following image-to-image operations:

| Capability                      | Description                                                       |
| ------------------------------- | ----------------------------------------------------------------- |
| **Image editing**               | Modify specific parts of an image based on a text instruction     |
| **Style transfer**              | Apply the visual style of one image to another                    |
| **Background replacement**      | Swap the background while keeping the subject                     |
| **Multi-image composition**     | Combine elements from multiple source images into one             |
| **Reference-based consistency** | Keep a character, product, or style consistent across generations |
| **Variations**                  | Generate alternative versions of an existing image                |
| **Object placement**            | Insert a logo, product, or object into a scene                    |
| **Appearance change**           | Change clothing, color, texture, or features                      |
| **Search-grounded editing**     | Edit using real-world knowledge (Flash only)                      |

***

### Request Reference

#### Required Fields

| Field        | Type                | Description                                            |
| ------------ | ------------------- | ------------------------------------------------------ |
| `model`      | `string`            | `vertex/nano-banana-flash` or `vertex/nano-banana-pro` |
| `prompt`     | `string` (max 4000) | Editing instruction or description.                    |
| `image_urls` | `string[]`          | One or more publicly accessible source image URLs.     |

#### Valid `aspect_ratio` Values

```
1:1   1:4   1:8   2:3   3:2   3:4   4:1   4:3   4:5   5:4   8:1   9:16   16:9   21:9
```

***

### Use Cases & Payloads

***

#### 1. Edit a Specific Part of an Image

Change a targeted element while leaving everything else untouched.

**Flash — fast iteration:**

```json
{
  "model": "vertex/nano-banana-flash",
  "prompt": "Change the car color to matte black, keep everything else exactly the same",
  "image_urls": ["https://cdn.qolaba.ai/1778648845113_9i9sl6e255.jpeg"],
  "quality": "2K",
  "aspect_ratio": "16:9",
  "temperature": 0.8
}
```

**Pro — production output:**

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Change the color of the sofa to deep emerald green, keep the rest of the room unchanged",
  "image_urls": ["https://cdn.qolaba.ai/1778648845113_9i9sl6e255.jpeg"],
  "quality": "4K",
  "aspect_ratio": "16:9",
  "temperature": 0.75
}
```

***

#### 2. Style Transfer

Apply the visual style, mood, or artistic look of a reference image to a source image.

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Redraw this photo in the style of the reference image — apply the same painterly brush strokes, warm color palette, and impressionist lighting. Preserve the original composition and subject.",
  "image_urls": ["https://cdn.qolaba.ai/1778648845113_9i9sl6e255.jpeg"],
  "reference_images": [
    {
      "url": "https://your-cdn.com/van-gogh-style.jpg",
      "description": "Artistic style to apply — impressionist oil painting with swirling brushwork"
    }
  ],
  "quality": "2K",
  "aspect_ratio": "1:1",
  "temperature": 1.1
}
```

**Text-only style transfer (no reference image):**

```json
{
  "model": "vertex/nano-banana-flash",
  "prompt": "Convert this photo into a watercolor painting with soft edges, muted pastel tones, and visible paper texture. Keep the original subject and composition.",
  "image_urls": ["https://cdn.qolaba.ai/1778648845113_9i9sl6e255.jpeg"],
  "quality": "2K",
  "aspect_ratio": "16:9",
  "temperature": 1.0
}
```

***

#### 3. Replace Background

See the dedicated Replace Background guide for full documentation.

**Quick reference:**

```json
{
  "model": "vertex/nano-banana-flash",
  "prompt": "Replace the background with a modern city skyline at golden hour, keep the subject exactly as-is",
  "image_urls": ["https://cdn.qolaba.ai/1778648845113_9i9sl6e255.jpeg"],
  "quality": "2K",
  "aspect_ratio": "16:9"
}
```

***

#### 4. Multi-Image Composition

Combine elements from multiple source images into a single coherent output.

**Merge two scenes:**

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Combine these two images: place the person from the first image into the environment shown in the second image. Match lighting and perspective.",
  "image_urls": [
    "https://cdn.qolaba.ai/1778648845113_9i9sl6e255.jpeg",
    "https://cdn.qolaba.app/1778662155240_ydyuksjbp2b.jpeg"
  ],
  "quality": "2K",
  "aspect_ratio": "16:9",
  "temperature": 0.9
}
```

**Extract and composite a product:**

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Take the bottle from the first image and place it on the table in the second image. Match the lighting, shadow, and perspective of the scene.",
   "image_urls": [
    "https://cdn.qolaba.ai/1778648845113_9i9sl6e255.jpeg",
    "https://cdn.qolaba.app/1778662155240_ydyuksjbp2b.jpeg"
  ],
  "quality": "4K",
  "aspect_ratio": "1:1",
  "temperature": 0.85
}
```

***

#### 5. Character / Product Consistency with References

Keep a specific subject (person, character, product) visually consistent across multiple generations using `reference_images`.

**Consistent character across scenes:**

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Generate an image of this character sitting in a cozy coffee shop reading a book. Maintain exact visual consistency — same face, hairstyle, clothing, and proportions as shown in the reference images.",
  "image_urls": [],
  "reference_images": [
    {
      "url": "https://your-cdn.com/character-front.jpg",
      "description": "Character reference — front view"
    },
    {
      "url": "https://your-cdn.com/character-side.jpg",
      "description": "Character reference — side view"
    },
    {
      "url": "https://your-cdn.com/character-detail.jpg",
      "description": "Character reference — clothing and accessory detail"
    }
  ],
  "quality": "2K",
  "aspect_ratio": "4:3",
  "temperature": 0.85
}
```

**Consistent product in a lifestyle scene:**

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Show this exact product placed on a rustic wooden kitchen counter with morning sunlight. Keep every product detail — shape, label, color, and texture — identical to the reference.",
  "image_urls": [],
  "reference_images": [
    {
      "url": "https://your-cdn.com/product-front.jpg",
      "description": "Product front view reference"
    },
    {
      "url": "https://your-cdn.com/product-label.jpg",
      "description": "Product label and branding detail reference"
    }
  ],
  "quality": "4K",
  "aspect_ratio": "16:9",
  "temperature": 0.8
}
```

***

#### 6. Image Upscale & Re-render

Re-render a low-quality or low-resolution image at higher quality with enhanced detail.

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Re-render this image at high resolution. Enhance sharpness, add fine detail, improve lighting quality, and increase overall visual fidelity. Do not change the composition, colors, or content.",
  "image_urls": ["https://your-cdn.com/low-res.jpg"],
  "quality": "4K",
  "aspect_ratio": "1:1",
  "temperature": 0.7
}
```

**Upscale with artistic enhancement:**

```json
{
  "model": "vertex/nano-banana-flash",
  "prompt": "Upscale this image and enhance the details. Make textures more realistic, sharpen edges, and improve the lighting while keeping the exact same scene and composition.",
  "image_urls": ["https://your-cdn.com/draft.jpg"],
  "quality": "4K",
  "aspect_ratio": "16:9",
  "temperature": 0.75
}
```

***

#### 7. Outfit & Appearance Change

Modify what a subject is wearing or change their visual appearance.

**Change outfit:**

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Change the person's outfit to a formal navy blue business suit with a white shirt and tie. Keep their face, hairstyle, body, and the background exactly the same.",
  "image_urls": ["https://your-cdn.com/person.jpg"],
  "quality": "2K",
  "aspect_ratio": "3:4",
  "temperature": 0.8
}
```

**Change hair color:**

```json
{
  "model": "vertex/nano-banana-flash",
  "prompt": "Change the person's hair color to platinum blonde. Keep everything else — face, clothing, background, and pose — identical.",
  "image_urls": ["https://your-cdn.com/portrait.jpg"],
  "quality": "2K",
  "aspect_ratio": "1:1",
  "temperature": 0.75
}
```

**Product color variant:**

```json
{
  "model": "vertex/nano-banana-flash",
  "prompt": "Change the color of the sneakers to all-black with a white sole. Keep the exact same shoe design, angle, lighting, and background.",
  "image_urls": ["https://your-cdn.com/sneaker-white.jpg"],
  "quality": "2K",
  "aspect_ratio": "1:1",
  "temperature": 0.7,
  "num_images": 4
}
```

***

#### 8. Logo / Object Placement into a Scene

Insert a product, logo, or object into an existing scene naturally.

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Place the logo from the reference image on the front of the white t-shirt worn by the person. The logo should be centered on the chest, sized proportionally, and match the fabric texture and lighting of the shirt.",
  "image_urls": ["https://your-cdn.com/person-white-tshirt.jpg"],
  "reference_images": [
    {
      "url": "https://your-cdn.com/brand-logo.png",
      "description": "Brand logo to place on the t-shirt"
    }
  ],
  "quality": "2K",
  "aspect_ratio": "3:4",
  "temperature": 0.8
}
```

**Product mockup on billboard:**

```json
{
  "model": "vertex/nano-banana-pro",
  "prompt": "Place this product image on the blank billboard in the urban street photo. The product image should fill the billboard naturally, matching the perspective and lighting of the scene.",
  "image_urls": [
    "https://your-cdn.com/street-with-billboard.jpg",
    "https://your-cdn.com/product-ad.jpg"
  ],
  "quality": "2K",
  "aspect_ratio": "16:9",
  "temperature": 0.8
}
```

***

### Prompt Writing Guide

#### State the edit clearly upfront

Start the prompt with what you want to change before describing the result.

```
# Clear
"Change the jacket color to red. Keep the person's face, body, and the background unchanged."

# Unclear
"A person in a red jacket in a park on a sunny day"
```

#### Explicitly protect what should not change

The model won't know what to preserve unless you say so.

```
# Safer
"Change the table material to marble. Keep the objects on the table, the room, the lighting, and the camera angle exactly the same."

# Risky
"A marble table in a living room"
```

#### Separate the subject from the edit

Describe the original subject, then describe the change.

```
"This is a product photo of a glass perfume bottle on a white surface.
Change the background surface from white to dark polished obsidian.
Keep the bottle, its reflection, and the overhead lighting unchanged."
```