Skip to main content
Version: 1.11.0-beta

Gemini 2.5 Flash Image Preview

Google's Gemini 2.5 Flash Image Preview model provides state-of-the-art image generation, editing, and combination capabilities with advanced prompt understanding and multimodal processing.

Overview​

The Gemini 2.5 integration offers three main operations:

  • Generate: Create images from text prompts with optional reference images
  • Combine: Intelligently combine 2-10 images with text guidance
  • Edit: Edit images with text prompts and optional masks for precise modifications

Installation​

npm install @imagineoai/javascript
# or
yarn add @imagineoai/javascript
# or
bun add @imagineoai/javascript

Authentication​

import { ImagineoAIClient } from '@imagineoai/javascript';

const client = new ImagineoAIClient({
  apiKey: 'your_api_key_here'
});

Image Generation​

Generate images using Gemini 2.5's advanced text-to-image capabilities.

Basic Generation​

const result = await client.images.generate({
  prompt: "A serene Japanese garden with cherry blossoms at sunset",
  model_type: "gemini-2.5",
  aspect_ratio: "16:9"
});

console.log(result.image_url);

Generation with Reference Image​

const result = await client.images.generate({
  prompt: "Transform this into a cyberpunk scene",
  model_type: "gemini-2.5",
  reference_image_url: "https://example.com/city.jpg",
  aspect_ratio: "1:1"
});

Image Combination​

Combine multiple images into a cohesive composition with AI guidance.

Combine with Run IDs​

const result = await client.images.combine.gemini25.json({
  prompt: "Blend these fashion items into a cohesive outfit presentation",
  run_ids: ["run_id_1", "run_id_2", "run_id_3"],
  aspect_ratio: "4:3"
});

console.log(result.image_url);

Combine with Image URLs​

const result = await client.images.combine.gemini25.json({
  prompt: "Create a panoramic landscape from these images",
  image_urls: [
    "https://example.com/mountain1.jpg",
    "https://example.com/mountain2.jpg",
    "https://example.com/mountain3.jpg"
  ],
  aspect_ratio: "21:9"
});

Combine with File Upload​

const formData = new FormData();
const files = [file1, file2, file3]; // File objects from input

const result = await client.images.combine.gemini25.formData({
  prompt: "Combine these product images into a lifestyle shot",
  files: files,
  aspect_ratio: "16:9"
});

Mixed Input Sources​

// Combine files, URLs, and run IDs in a single operation
const result = await client.images.combine.gemini25.formData({
  prompt: "Create a mood board from these elements",
  files: [file1, file2],
  image_urls: ["https://example.com/texture.jpg"],
  run_ids: ["previous_run_id"],
  aspect_ratio: "1:1"
});

Image Editing​

Edit existing images with text prompts and optional masks.

Basic Edit with Run ID​

const result = await client.images.edit.gemini25.json({
  prompt: "Change the sky to a starry night",
  original_run_id: "run_123",
  aspect_ratio: "16:9"
});

console.log(result.image_url);

Edit with Image URL​

const result = await client.images.edit.gemini25.json({
  prompt: "Add autumn colors to the trees",
  image_url: "https://example.com/forest.jpg",
  aspect_ratio: "4:3"
});

Edit with Mask (Inpainting)​

const result = await client.images.edit.gemini25.json({
  prompt: "Replace the car with a bicycle",
  image_url: "https://example.com/street.jpg",
  mask_url: "https://example.com/car-mask.png",
  aspect_ratio: "16:9"
});

Edit with File Upload​

const result = await client.images.edit.gemini25.formData({
  prompt: "Remove all people from the scene",
  file: imageFile, // File object
  aspect_ratio: "1:1"
});

Edit with File and Mask Upload​

const result = await client.images.edit.gemini25.formData({
  prompt: "Replace the sky with sunset colors",
  file: imageFile,
  mask: maskFile,
  aspect_ratio: "16:9"
});

Parameters​

Generation Parameters​

ParameterTypeRequiredDescription
promptstringYesText description of the desired image
model_typestringYesMust be "gemini-2.5"
aspect_ratiostringNoOutput aspect ratio (e.g., "16:9", "1:1", "4:3")
reference_image_urlstringNoURL of reference image for context

Combination Parameters​

ParameterTypeRequiredDescription
promptstringYesText guidance for combination
image_urlsstring[]No*Array of image URLs (2-10 images)
run_idsstring[]No*Array of run IDs (2-10 runs)
filesFile[]No*Array of files (2-10 files)
aspect_ratiostringNoOutput aspect ratio

*At least one image source (URLs, run IDs, or files) must be provided with 2-10 total images.

Edit Parameters​

ParameterTypeRequiredDescription
promptstringYesEdit instruction
original_run_idstringNo*Run ID of image to edit
image_urlstringNo*URL of image to edit
fileFileNo*File to edit (formData only)
mask_urlstringNoURL of mask for inpainting
maskFileNoMask file (formData only)
aspect_ratiostringNoOutput aspect ratio

*At least one image source must be provided.

Response Format​

All Gemini 2.5 operations return a consistent response format:

interface GenerateImageOutput {
  run_id: string;
  user_id: string;
  image_url: string;
  status: 'completed' | 'pending' | 'failed';
  created_at: string;
  updated_at: string;
  inputs: {
    prompt: string;
    model: string;
    aspect_ratio?: string;
    [key: string]: any;
  };
  run_type: string;
}

Advanced Features​

Aspect Ratios​

Gemini 2.5 supports various aspect ratios for different use cases:

const aspectRatios = [
  "1:1",    // Square (Instagram posts)
  "4:3",    // Traditional photo
  "3:4",    // Portrait orientation
  "16:9",   // Widescreen (YouTube)
  "9:16",   // Mobile/Stories
  "21:9",   // Ultra-wide
  "2:3",    // Classic portrait
  "3:2"     // Classic landscape
];

Error Handling​

try {
  const result = await client.images.generate({
    prompt: "Beautiful landscape",
    model_type: "gemini-2.5"
  });
  console.log(result);
} catch (error) {
  if (error.code === 'CONTENT_BLOCKED') {
    console.error('Content was blocked by safety filters');
  } else if (error.code === 'QUOTA_EXCEEDED') {
    console.error('API quota exceeded');
  } else {
    console.error('Generation failed:', error.message);
  }
}

Batch Processing​

// Process multiple images in parallel
const prompts = [
  "Sunset over mountains",
  "City skyline at night",
  "Tropical beach paradise"
];

const results = await Promise.all(
  prompts.map(prompt => 
    client.images.generate({
      prompt,
      model_type: "gemini-2.5",
      aspect_ratio: "16:9"
    })
  )
);

results.forEach(result => {
  console.log(result.image_url);
});

Use Cases​

E-commerce Product Composites​

// Combine multiple product angles into a single showcase
const showcase = await client.images.combine.gemini25.json({
  prompt: "Create an elegant product showcase with multiple angles",
  run_ids: ["front_view_id", "side_view_id", "detail_view_id"],
  aspect_ratio: "16:9"
});

Creative Content Editing​

// Transform image style while preserving structure
const stylized = await client.images.edit.gemini25.json({
  prompt: "Apply watercolor painting style while keeping the composition",
  original_run_id: "photo_run_id",
  aspect_ratio: "1:1"
});

Marketing Material Generation​

// Generate variations for A/B testing
const variations = await Promise.all([
  client.images.generate({
    prompt: "Modern minimalist product advertisement with blue tones",
    model_type: "gemini-2.5",
    aspect_ratio: "4:3"
  }),
  client.images.generate({
    prompt: "Vibrant energetic product advertisement with warm colors",
    model_type: "gemini-2.5",
    aspect_ratio: "4:3"
  })
]);

Best Practices​

  1. Prompt Engineering: Be specific and descriptive in your prompts for best results
  2. Aspect Ratio Selection: Choose aspect ratios that match your intended use case
  3. Image Quality: Use high-quality source images for editing and combination
  4. Mask Creation: For precise edits, provide accurate masks that clearly define edit areas
  5. Error Handling: Always implement proper error handling for production applications
  6. Rate Limiting: Respect API rate limits and implement retry logic with exponential backoff

Limitations​

  • Combination requires 2-10 images (no single image or more than 10)
  • Maximum prompt length is subject to API limits
  • Generated content is subject to safety filters
  • API availability may vary by region

See Also​