images.combine (Flux Kontext Multi)

Combine two images using the Flux Kontext Multi model, which provides high-quality image combination based on text prompts and exactly two input images.

Signature:

client.images.combine(input: CombineImageInput): Promise<GenerateImageOutput>

Flux Kontext Multi Model

Use this method when you want to combine exactly 2 images using the advanced Flux Kontext Multi model.

Parameters

• input: CombineImageInput
  • prompt: string - Text description of how to combine the images (required)
  • input_image_1: string - URL of the first image to combine (option 1 for flux-kontext-multi)
  • input_image_2: string - URL of the second image to combine (option 1 for flux-kontext-multi)
  • run_id_1: string - Run ID of the first image to combine (option 2 for flux-kontext-multi)
  • run_id_2: string - Run ID of the second image to combine (option 2 for flux-kontext-multi)
  • model: "flux-kontext-multi" - Model type (required)
  • aspect_ratio: string - Aspect ratio for the combined image (required)
  • seed?: number - Random seed for reproducible results (optional)

Supported Aspect Ratios

• "1:1" - Square
• "16:9" - Widescreen
• "9:16" - Portrait
• "4:3" - Standard
• "3:4" - Portrait standard
• "3:2" - Classic photo
• "2:3" - Portrait photo
• "4:5" - Portrait
• "5:4" - Landscape
• "21:9" - Ultra-wide
• "9:21" - Ultra-tall
• "2:1" - Panoramic
• "1:2" - Tall panoramic

Returns

• GenerateImageOutput - Contains the combined image details and status
• Throws: On validation, network, or API error

Example (Using Image URLs)

const client = new ImagineoAIClient(apiUrl, { apiKey: 'sk-...' });

// Combine using direct image URLs
const result = await client.images.combine({
  prompt: 'Combine these two landscapes into a seamless panoramic view',
  input_image_1: 'https://example.com/landscape1.jpg',
  input_image_2: 'https://example.com/landscape2.jpg',
  model: 'flux-kontext-multi',
  aspect_ratio: '21:9', // Ultra-wide for panoramic
  seed: 42, // Optional, for reproducible results
});

console.log('Combine run ID:', result.run_id);
console.log('Status:', result.status); // 'pending'

// Use webhooks or polling to get the final result
// When complete, the run will have an image_url

Example (Using Run IDs)

const client = new ImagineoAIClient(apiUrl, { apiKey: 'sk-...' });

// Combine using run IDs from previously generated images
const result = await client.images.combine({
  prompt: 'Merge these two generated images into a cohesive artistic piece',
  run_id_1: 'run-uuid-1', // First generated image run ID
  run_id_2: 'run-uuid-2', // Second generated image run ID
  model: 'flux-kontext-multi',
  aspect_ratio: '16:9',
  seed: 123,
});

console.log('Combine run ID:', result.run_id);
console.log('Status:', result.status); // 'pending'

Example (Basic Usage)

const client = new ImagineoAIClient(apiUrl, { apiKey: 'sk-...' });

// Simple image combination
const result = await client.images.combine({
  prompt: 'Merge these two portraits into a single artistic composition',
  input_image_1: 'https://example.com/portrait1.jpg',
  input_image_2: 'https://example.com/portrait2.jpg',
  model: 'flux-kontext-multi',
  aspect_ratio: '1:1', // Square composition
  seed: 123,
});

console.log('Combine run ID:', result.run_id);
console.log('Status:', result.status); // 'pending'

Example (Creative Combinations)

// Artistic style transfer using URLs
const artisticResult = await client.images.combine({
  prompt: 'Blend the subject from the first image with the artistic style and background of the second image',
  input_image_1: 'https://example.com/subject.jpg',
  input_image_2: 'https://example.com/artistic-style.jpg',
  model: 'flux-kontext-multi',
  aspect_ratio: '4:3',
});

// Seasonal transformation using run IDs from previous generations
const seasonalResult = await client.images.combine({
  prompt: 'Transform the summer scene into a winter wonderland using elements from both images',
  run_id_1: 'summer-scene-run-id', // Previously generated summer scene
  run_id_2: 'winter-elements-run-id', // Previously generated winter elements
  model: 'flux-kontext-multi',
  aspect_ratio: '16:9',
});

Notes

• Flux Kontext Multi requires exactly 2 input images via input_image_1+input_image_2 OR run_id_1+run_id_2
• Aspect ratio is required when using flux-kontext-multi model
• SDK always sends data as JSON - all images must be provided as URLs, not file uploads
• Asynchronous Processing: All Flux Kontext Multi operations are asynchronous and use webhook-based processing for optimal performance
• Seed parameter: Use the same seed value to get reproducible results
• The API endpoint (/api/v1/images/combine) supports both JSON and FormData, but the SDK only uses JSON
• Input is validated with Zod (CombineImageInputSchema)
• Makes a POST request to /api/v1/images/combine

Comparison with GPT-Image-1

Feature	GPT-Image-1	Flux Kontext Multi
Input Images	2+ images	Exactly 2 images (URLs or run IDs)
Model Parameter	"gpt-image-1" (default)	"flux-kontext-multi"
Aspect Ratio	Not required	Required
Seed Support	No	Yes
Processing	Sync only	Async with webhooks
Quality	Good	High-quality
Processing	Fast	Advanced processing

See the API Reference for details on input/output types.