Object Extraction

Extract specific objects or elements from images using Cloudinary's AI-powered extraction technology. This method can isolate objects, create masks, or invert selections for advanced image editing workflows.

Overview

The Extract feature provides powerful object isolation capabilities:

• AI-Powered Selection: Automatically identifies and extracts objects based on text prompts
• Dual Mode Operation: Extract the object itself or create a mask
• Flexible Selection: Support for single or multiple instances
• Inversion Support: Extract everything except the specified object
• Alpha Channel Control: Preserve transparency information

Basic Usage

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

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

// Extract an object from an image
const result = await client.images.extract({
  image_url: "https://example.com/photo.jpg",
  prompt: "car",
  mode: "content",
  preserve_alpha: true
});

console.log("Object extracted:", result);
// { 
//   url: "https://cdn.imagineoai.com/extracted-car.png",
//   runId: "abc-123-def-456",
//   parentRunId: undefined
// }

Parameters

Parameter	Type	Required	Default	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
prompt	string	Yes	-	Text description of what to extract (e.g., "phone", "person", "car")
mode	string	No	"content"	Extraction mode: "content" (extract object) or "mask" (extract mask)
preserve_alpha	boolean	No	true	Whether to preserve the alpha channel
multiple	boolean	No	false	Extract all instances of the prompt
invert	boolean	No	false	Invert the extraction (extract everything except the prompt)

Extraction Modes

Content Mode

Extracts the actual object with transparent background:

// Extract a product from a scene
const result = await client.images.extract({
  image_url: "https://example.com/scene.jpg",
  prompt: "laptop",
  mode: "content"
});
// Returns: Image of just the laptop with transparent background

Mask Mode

Creates a black and white mask of the object:

// Create a mask for compositing
const result = await client.images.extract({
  image_url: "https://example.com/portrait.jpg",
  prompt: "person",
  mode: "mask"
});
// Returns: Black and white mask where white = person, black = background

Examples

Extract Single Object

// Extract a specific object from a complex scene
const result = await client.images.extract({
  image_url: "https://example.com/office-desk.jpg",
  prompt: "coffee mug",
  mode: "content",
  multiple: false  // Only extract one mug
});

Extract Multiple Objects

// Extract all instances of an object type
const result = await client.images.extract({
  image_url: "https://example.com/parking-lot.jpg",
  prompt: "car",
  mode: "content",
  multiple: true  // Extract all cars
});

Inverted Extraction

// Extract everything except the specified object
const result = await client.images.extract({
  image_url: "https://example.com/product-photo.jpg",
  prompt: "background",
  mode: "content",
  invert: true  // Keeps everything except background
});

Create Selection Masks

// Generate a mask for further editing
const result = await client.images.extract({
  image_url: "https://example.com/group-photo.jpg",
  prompt: "person in red shirt",
  mode: "mask",
  preserve_alpha: false
});

Complex Object Descriptions

// Extract objects with detailed descriptions
const result = await client.images.extract({
  image_url: "https://example.com/street-scene.jpg",
  prompt: "yellow taxi cab",
  mode: "content",
  multiple: true,
  preserve_alpha: true
});

Advanced Use Cases

Product Isolation for E-commerce

async function isolateProduct(imageUrl, productType) {
  const extracted = await client.images.extract({
    image_url: imageUrl,
    prompt: productType,
    mode: "content",
    preserve_alpha: true
  });
  
  return extracted.url; // Transparent PNG of the product
}

Creating Composite Images

async function createComposite(foregroundUrl, backgroundUrl) {
  // First, extract the main subject
  const subject = await client.images.extract({
    image_url: foregroundUrl,
    prompt: "person",
    mode: "content"
  });
  
  // Then combine with new background (using another method)
  // ...
  return compositeUrl;
}

Batch Mask Generation

async function generateMasks(images, objectType) {
  const masks = await Promise.all(
    images.map(img => 
      client.images.extract({
        image_url: img,
        prompt: objectType,
        mode: "mask"
      })
    )
  );
  
  return masks;
}

Background Replacement Workflow

async function replaceBackground(imageUrl) {
  // Extract foreground by inverting background selection
  const foreground = await client.images.extract({
    image_url: imageUrl,
    prompt: "background",
    mode: "content",
    invert: true  // Keeps everything except background
  });
  
  return foreground.url;
}

Response

The method returns a promise that resolves to:

{
  url: string;        // URL of the extracted image or mask
  runId: string;      // Unique ID for this operation
  parentRunId?: string; // ID of the source run (if using run_id input)
}

Output Formats

Content Mode Output

• Format: PNG with alpha channel
• Transparency: Transparent where object is not present
• Quality: High-fidelity extraction of object pixels

Mask Mode Output

• Format: PNG (black and white)
• White pixels: Object area
• Black pixels: Non-object area
• Use case: Perfect for compositing and editing workflows

Best Practices

1. Prompt Specificity: Be as specific as possible with your prompts

   • Good: "red sports car", "person wearing blue jacket"
   • Less effective: "thing", "object"

2. Mode Selection:

   • Use content mode for direct object isolation
   • Use mask mode when you need selection data for further processing

3. Multiple Objects: Enable multiple: true when you expect several instances

4. Inversion Use: Use invert: true for removing simple backgrounds or isolating complex foregrounds

5. Alpha Channel: Keep preserve_alpha: true for maximum flexibility in post-processing

Common Extraction Scenarios

Scenario	Prompt	Mode	Multiple	Invert
Product isolation	"product name"	content	false	false
Remove all people	"person"	mask	true	true
Extract all cars	"car"	content	true	false
Isolate foreground	"background"	content	false	true
Create selection mask	"object"	mask	false	false

Error Handling

try {
  const result = await client.images.extract({
    image_url: imageUrl,
    prompt: "specific object"
  });
  console.log("Extraction successful:", result);
} catch (error) {
  if (error.message.includes("credits")) {
    console.error("Insufficient credits");
  } else if (error.message.includes("not found")) {
    console.error("Object not found in image");
  } else {
    console.error("Extraction failed:", error);
  }
}

Limitations

• Works best with clearly defined objects
• May struggle with:
  • Abstract concepts
  • Highly transparent objects
  • Objects that blend with the background
  • Very small or distant objects
• Complex scenes may require multiple extraction passes

Pricing

This operation consumes credits based on your Cloudinary plan. Extraction operations are typically priced per image processed.