combine

Combines multiple images into a single output image using the ImagineoAI API. Supports three models: GPT-Image-1 (default) for combining 2+ images, Flux Kontext Multi for high-quality combination of exactly 2 images, and Nanobanana for advanced AI-powered combination of 2-10 images.

Signature:

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

• input: CombineImageInput (see src/types.ts for the full Zod schema)
  • For GPT-Image-1: Requires at least 2 images via reference_urls or files
  • For Flux Kontext Multi: Requires exactly 2 images via input_image_1+input_image_2 OR run_id_1+run_id_2
  • For Nanobanana: Requires 2-10 images via reference_urls, files, or run_ids
• Returns: GenerateImageOutput (see src/types.ts)
• Throws: On validation, network, or API error.

Example (GPT-Image-1 - Default Model)

const client = new ImagineoAIClient(apiUrl, { apiKey: 'sk-...' });
const result = await client.images.combine({
  reference_urls: [
    'https://example.com/image1.png',
    'https://example.com/image2.png',
    'https://example.com/image3.png', // Can combine 2+ images
  ],
  prompt: 'Combine these images into a single output image',
  model: 'gpt-image-1' // Optional, this is the default
});
console.log(result.image_url);

Example (Flux Kontext Multi - Advanced Model)

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

// Option 1: Using image URLs
const result1 = await client.images.combine({
  input_image_1: 'https://example.com/image1.png',
  input_image_2: 'https://example.com/image2.png', // Exactly 2 images
  prompt: 'Blend these two images into a seamless artistic composition',
  model: 'flux-kontext-multi',
  aspect_ratio: '16:9', // Required for flux-kontext-multi
  seed: 42, // Optional, for reproducible results
});

// Option 2: Using run IDs from previous generations
const result2 = await client.images.combine({
  run_id_1: 'run-uuid-1', // First generated image
  run_id_2: 'run-uuid-2', // Second generated image
  prompt: 'Combine these previously generated images',
  model: 'flux-kontext-multi',
  aspect_ratio: '1:1',
  seed: 123,
});

console.log(result1.image_url);
console.log(result2.image_url);

Example (Nanobanana - Advanced AI Model)

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

// Combine multiple images with Nanobanana
const result = await client.images.combine({
  reference_urls: [
    'https://example.com/scene1.png',
    'https://example.com/scene2.png',
    'https://example.com/scene3.png',
    'https://example.com/scene4.png',
    // Can combine 2-10 images
  ],
  prompt: 'Create a panoramic landscape combining all these scenes naturally',
  model: 'nanobanana'
});

// Or using previous generation run IDs
const resultFromRuns = await client.images.combine({
  run_ids: ['run-uuid-1', 'run-uuid-2', 'run-uuid-3'],
  prompt: 'Merge these AI-generated images seamlessly',
  model: 'nanobanana'
});

console.log(result.image_url);

Model Comparison

Feature	GPT-Image-1	Flux Kontext Multi	Nanobanana
Input Images	2+ images	Exactly 2 images (URLs or run IDs)	2-10 images
Model Parameter	"gpt-image-1" (default)	"flux-kontext-multi"	"nanobanana"
Aspect Ratio	Not required	Required	Not required
Seed Support	No	Yes	No
Processing	Sync only	Async with webhooks	Async with webhooks
Quality	Good	High-quality	Advanced AI blending
Best For	Quick combinations	Artistic blending	Complex scene merging

Notes

• SDK always sends data as JSON—all images/files must be provided as URLs, not file uploads.
• The API endpoint (/api/v1/images/combine) supports both application/json (for URLs) and multipart/form-data (for direct file uploads), as seen in the images.ts route handler. The SDK only uses JSON.
• Input is validated with Zod (CombineImageInputSchema).
• Makes a POST request to /api/v1/images/combine.
• For detailed Flux Kontext Multi usage, see Flux Kontext Multi Combine.
• For detailed Nanobanana usage, see Nanobanana Model.
• See the API Reference for details on input/output types.