Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Anil-matcha/Open-Higgsfield-AI/llms.txt

Use this file to discover all available pages before exploring further.

Some image-to-image models support multiple reference images in a single generation, enabling advanced editing workflows like style transfer, composition, and multi-view editing.

​
Overview

Multi-image input allows you to:

Combine Multiple References

Feed up to 14 images into a single generation for style transfer, composition, or multi-view editing.

Order-Based Processing

Images are processed in the order you select them, giving you control over priority and influence.

Batch Upload

Select multiple files at once from your file dialog for faster workflow.

Visual Selection

Checkboxes with order numbers show exactly which images are active and their processing order.

​
Supported Models

Not all image-to-image models support multiple images. Here are the models with multi-image support and their maximum image counts:
ModelMax ImagesKey Features
Nano Banana 2 Edit14Google Gemini · 1K/2K/4K resolution · Google Search enhancement
Nano Banana Edit10Original Nano Banana with multi-image support
Flux Kontext Dev I2I10High-quality context-aware editing
Kling O1 Edit Image10Kuaishou’s editing model
GPT-4o Edit10OpenAI’s multi-image editing
GPT Image 1.5 Edit10OpenAI’s image editing model
Bytedance Seedream Edit v410ByteDance editing with quality presets
Bytedance Seedream Edit v4.510Enhanced version of v4
Vidu Q2 Reference to Image7Chinese model with reference-based generation
When you select a model that supports multiple images, the upload picker automatically switches to multi-select mode with checkboxes and order indicators.

​
How Multi-Select Works

​
Automatic Mode Switching

The upload picker adapts based on the selected model:
1

Single-Image Mode (Default)

When you select a model that supports only 1 image:
  • Instant selection — Click any image to select and close immediately
  • No checkboxes — Simple click-to-select interaction
  • Replace on select — New selection replaces previous
2

Multi-Image Mode (Automatic)

When you select a multi-image model like Nano Banana 2 Edit:
  • Checkboxes appear — Toggle multiple images on/off
  • Order numbers — Each selected image shows its order (1, 2, 3…)
  • “Use Selected” button — Confirm your selection
  • Count badge — Trigger button shows how many images are selected
  • Capacity indicator — “X of Y selected” in the panel

​
Using Multi-Select

1

Select a Multi-Image Model

In Image Studio, click the model button and choose a model that supports multiple images (e.g., Nano Banana 2 Edit with 14 max images).The upload picker automatically switches to multi-select mode.
2

Open Upload Picker

Click the upload button (📤 icon) to open the reference image picker.
3

Select Images in Order

Click images to toggle them on/off:
  • First click → Image selected, shows badge “1”
  • Second click on another → Shows badge “2”
  • Third click on another → Shows badge “3”
  • Click selected image → Deselect, order numbers reflow
Images are sent to the model in the order you select them. Order can affect the result for some models (e.g., first image = primary reference, others = style/composition).
4

Upload New Images (Optional)

If you need more images, click “Upload files” (note: plural in multi-mode):
  • Multi-file selection enabled — Choose multiple files at once
  • Auto-upload — All selected files upload in parallel
  • Auto-select — Newly uploaded images are automatically selected (up to remaining slots)
  • Panel stays open — Continue selecting more images
5

Check Selection Status

The panel shows your selection status:
  • Bottom bar: “3 of 14 selected”
  • Dimmed images: Unselectable images when at max capacity
  • Count badge: Trigger button shows “3” or ”+” if room for more
6

Confirm Selection

Click the “Use Selected” button (appears in header and bottom bar) or “Done (3)” button to close the panel and confirm your selection.The trigger button updates to show:
  • Thumbnail of first selected image
  • Count badge (“3” in a yellow circle)

​
Upload Picker UI States

​
Trigger Button States

Appearance: Upload icon (📤), no border colorTooltip: “Add up to X images” (multi-mode) or “Reference image” (single-mode)Action: Opens picker panel

​
Panel States

Content: Empty state illustration with upload iconMessage: “No uploads yet”Action: Click “Upload new” to add first images

​
Upload Workflow

​
Batch Upload (Multi-Mode)

1

Open File Dialog

Click “Upload files” in the picker panel.
2

Select Multiple Files

In the file dialog:
  • Mac: Cmd + Click or Shift + Click to select multiple
  • Windows/Linux: Ctrl + Click or Shift + Click
You can select up to the remaining slots (e.g., if 14 max and 4 selected, you can add up to 10 more).
3

Upload Starts

All selected files upload in parallel to Muapi.ai. The trigger button shows a spinner.
4

Auto-Save to History

Each uploaded image is automatically saved to upload history with:
  • Hosted URL from Muapi.ai
  • Thumbnail (80x80px base64 JPEG)
  • Filename and timestamp
5

Auto-Select (Multi-Mode)

Newly uploaded images are automatically added to your selection (up to the remaining slots).The picker panel stays open so you can continue adjusting your selection.
6

Confirm Selection

Click “Use Selected” to close the panel and proceed with generation.

​
Single Upload (Single-Mode)

1

Open File Dialog

Click “Upload new” in the picker panel (or click the trigger when empty).
2

Select One File

Choose a single image file.
3

Upload & Save

The image uploads to Muapi.ai and saves to history.
4

Auto-Select & Close

The image is automatically selected and the picker closes immediately. The onSelect callback fires with the image URL.

​
Reordering Images

Currently, images are ordered by selection order. To reorder:
  1. Deselect all images — Click each selected image to deselect
  2. Reselect in desired order — Click images in the new order (1, 2, 3…)
A drag-and-drop reordering UI is planned for a future update. For now, use the click-to-reorder workflow above.

​
Upload History Integration

Multi-image input is tightly integrated with Upload History:
  • No re-uploading — All uploaded images are saved to history and reused across sessions
  • Persistent storage — Up to 20 uploads saved in browser localStorage
  • Cross-studio access — Upload history is shared between Image Studio and Video Studio
  • Thumbnail generation — 80x80px thumbnails generated client-side for fast preview

​
API Integration

When you generate with multiple images, the API receives all image URLs in a single request: 
const result = await muapi.generateI2I({
  model: 'nano-banana-2-edit',
  images_list: [
    'https://api.muapi.ai/uploads/img1.jpg',
    'https://api.muapi.ai/uploads/img2.jpg',
    'https://api.muapi.ai/uploads/img3.jpg'
  ],
  image_url: 'https://api.muapi.ai/uploads/img1.jpg', // backward compat
  prompt: 'Combine these styles into a single image',
  aspect_ratio: '1:1',
  resolution: '2k'
});
The image_url field is included for backward compatibility with single-image models. Multi-image models use the images_list array.

​
Best Practices

  • 2-3 images — Best for style transfer (content + style references)
  • 4-6 images — Good for composition and multi-view editing
  • 7-10 images — Advanced workflows like mood boards or multi-reference generation
  • 10-14 images — Experimental, for models like Nano Banana 2 Edit
More images ≠ better results. Start with 2-3 images and add more only if needed.
For most models:
  • First image = Primary reference (content, composition)
  • Second image = Secondary reference (style, color palette)
  • Remaining images = Additional influences (textures, details, mood)
Experiment with different orders to see how models prioritize references.
  • Upload high-resolution images — Better input = better output
  • Mix sizes OK — Models handle different resolutions
  • Aspect ratios — No need to match; models adapt
  • File formats — JPEG, PNG, WebP all supported
  • Be specific — “Use the composition from the first image and colors from the second”
  • Reference order — “Apply the style of image 2 to the subject in image 1”
  • Describe intent — “Combine these into a cohesive portrait”
  • Experiment — Try with and without prompts to see what works

​
Troubleshooting

Cause: You selected a single-image modelSolution: Switch to a multi-image model (e.g., Nano Banana 2 Edit, Flux Kontext Dev I2I)
Cause: You’ve reached the max image capacity for the selected modelSolution: Deselect some images or switch to a model with higher capacity
Cause: Cached state or UI not re-renderingSolution: Deselect all and reselect, or close and reopen the picker
Cause: Network issue, file too large, or invalid formatSolution:
  • Check file sizes (keep under 10MB per image)
  • Ensure files are valid images (JPEG, PNG, WebP)
  • Try uploading files one at a time

​
Keyboard Shortcuts

  • Escape — Close picker panel
  • Enter (when picker open) — Click “Use Selected” (multi-mode)
  • Tab — Navigate between images in picker

Image Studio

Learn about image-to-image generation

Upload History

Manage and reuse uploaded images

Generation History

Browse past generations

Build docs developers (and LLMs) love

Get started for freeTalk to us