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:

{
  "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:

{
  "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.

{
  "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):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

{
  "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:

{
  "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."