Background Removal (Cloudinary)

Remove backgrounds from images using Cloudinary's AI-powered background removal technology. This method provides high-quality, automatic background removal suitable for e-commerce, portraits, and product photography.

Overview

The Cloudinary Background Remove feature offers:

• Automatic Detection: AI identifies and removes backgrounds without manual masking
• Edge Preservation: Maintains fine details like hair, fur, and transparent objects
• Alpha Channel Support: Outputs images with transparent backgrounds (PNG format)
• Fast Processing: Optimized for quick turnaround times

Basic Usage

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

const client = new ImagineoAIClient(apiUrl, { 
  apiKey: process.env.IMAGINEOAI_API_KEY 
});

// Remove background from an image
const result = await client.images.backgroundRemove({
  image_url: "https://example.com/photo-with-background.jpg"
});

console.log("Background removed:", result);
// { 
//   url: "https://cdn.imagineoai.com/transparent-image.png",
//   runId: "abc-123-def-456",
//   parentRunId: undefined
// }

Parameters

Parameter	Type	Required	Description
image_url	string	One of image_url or run_id	URL of the source image
run_id	string	One of image_url or run_id	ID of a previous run to use as source

Examples

Basic Background Removal

// Remove background from a portrait
const result = await client.images.backgroundRemove({
  image_url: "https://example.com/portrait.jpg"
});

// The result will have a transparent background
console.log("Transparent image URL:", result.url);

Using Previous Run as Source

// Remove background from a previously generated image
const result = await client.images.backgroundRemove({
  run_id: "previous-run-id-123"
});

console.log("Background removed from run:", result.parentRunId);

Batch Processing

// Process multiple images
const imageUrls = [
  "https://example.com/product1.jpg",
  "https://example.com/product2.jpg",
  "https://example.com/product3.jpg"
];

const results = await Promise.all(
  imageUrls.map(url => 
    client.images.backgroundRemove({ image_url: url })
  )
);

console.log("Processed images:", results.map(r => r.url));

Common Use Cases

E-commerce Product Images

// Create clean product images for online stores
const result = await client.images.backgroundRemove({
  image_url: productImageUrl
});

// Use the transparent image for:
// - Product catalogs
// - Composite images
// - Marketing materials

Profile Pictures

// Create professional headshots with transparent backgrounds
const result = await client.images.backgroundRemove({
  image_url: portraitUrl
});

// Perfect for:
// - Professional profiles
// - ID cards
// - Team pages

Logo Extraction

// Extract logos from images with backgrounds
const result = await client.images.backgroundRemove({
  image_url: logoImageUrl
});

// Useful for:
// - Brand assets
// - Marketing materials
// - Website integration

Creative Compositing

// Prepare images for creative compositions
async function prepareForComposite(imageUrl) {
  // First, remove the background
  const bgRemoved = await client.images.backgroundRemove({
    image_url: imageUrl
  });
  
  // Then use the result for further processing
  return bgRemoved.url;
}

Response

The method returns a promise that resolves to:

{
  url: string;        // URL of the processed image (PNG with transparency)
  runId: string;      // Unique ID for this operation
  parentRunId?: string; // ID of the source run (if using run_id input)
}

Output Format

• Format: PNG with alpha channel
• Transparency: Full transparency where background was removed
• Quality: High-quality edge detection and preservation
• Resolution: Maintains original image dimensions

Best Practices

1. Image Quality: Use high-resolution images with good contrast between subject and background

2. Subject Types: Works best with:

   • People and portraits
   • Products and objects
   • Animals
   • Logos and graphics

3. Challenging Scenarios: May require manual editing for:

   • Glass or transparent objects
   • Very fine details (hair wisps, fur)
   • Complex patterns that blend with background

4. File Size: PNG files with transparency are larger than JPEGs, consider compression for web use

Comparison with Standard Remove Background

While the SDK also offers a standard removeBackground method under client.images.removeBackground, this Cloudinary-powered version provides:

• Enhanced AI processing
• Better edge detection
• More consistent results across various image types
• Integration with Cloudinary's image optimization pipeline

Error Handling

try {
  const result = await client.images.backgroundRemove({
    image_url: imageUrl
  });
  console.log("Success:", result);
} catch (error) {
  if (error.message.includes("credits")) {
    console.error("Insufficient credits");
  } else if (error.message.includes("not found")) {
    console.error("Run ID not found");
  } else {
    console.error("Background removal failed:", error);
  }
}

Limitations

• Best results with clear subject-background separation
• May struggle with:
  • Very low contrast images
  • Transparent or semi-transparent objects
  • Highly reflective surfaces
  • Images with multiple focal points

Pricing

This operation consumes credits based on your Cloudinary plan. Background removal is typically priced per image processed.