Segment Image

Segments an image based on a textual prompt. This method is available under client.images.segmentImage and has two variants: .json and .formData.

The endpoint for this operation is /api/v1/edits/segment.

JSON Method

client.images.segmentImage.json(payload: SegmentImageJsonPayload): Promise<Blob | Buffer>

Accepts a JSON payload to specify the image via URL or a previous run_id, and a segmentation prompt.

Parameters

• payload (SegmentImageJsonPayload): An object containing:
  • prompt (string): A textual prompt describing the object or area to segment.
  • imageUrl (string, optional): URL of the image to process.
  • run_id (string, optional): ID of a previous run whose output image should be used.

One of imageUrl or run_id must be provided.

Returns

• Browser: Promise<Blob> - A promise that resolves to a Blob containing the segmented image (often a mask, or the original image with the segmented part highlighted/isolated, depending on API behavior).
• Server: Promise<Buffer> - A promise that resolves to a Buffer containing the segmented image.

Example (Browser)

import { ImagineoAIClient } from "@imagineoai/javascript-sdk/browser";

const client = new ImagineoAIClient("YOUR_API_URL", { apiKey: "YOUR_API_KEY" });

async function segmentFromUrl() {
  try {
    const imageBlob = await client.images.segmentImage.json({
      imageUrl: "https://example.com/image_with_person.jpg",
      prompt: "person"
    });
    // Handle the resulting imageBlob
    console.log("Image segmented, image blob:", imageBlob);
  } catch (error) {
    console.error("Error segmenting image:", error);
  }
}

Example (Server)

import { ImagineoAIClient } from "@imagineoai/javascript-sdk/server";
import fs from 'fs/promises';

const client = new ImagineoAIClient("YOUR_API_URL", { apiKey: "YOUR_API_KEY" });

async function segmentFromServerUrl() {
  try {
    const imageBuffer = await client.images.segmentImage.json({
      imageUrl: "https://example.com/image_with_car.jpg",
      prompt: "car"
    });
    await fs.writeFile("output_segmented.png", imageBuffer);
    console.log("Image segmented, image saved as output_segmented.png");
  } catch (error) {
    console.error("Error segmenting image:", error);
  }
}

FormData Method

client.images.segmentImage.formData(payload: { image: File | Buffer; prompt: string; run_id?: string; filename?: string }): Promise<Blob | Buffer>

Accepts FormData, typically used for uploading an image file directly, along with a segmentation prompt.

Parameters

• payload (object):
  • image (File (Browser) | Buffer (Server)): The image file or buffer.
  • prompt (string): A textual prompt describing the object or area to segment.
  • run_id (string, optional): ID of a previous run to associate with this operation.
  • filename (string, optional): Optional filename for the image when sending form-data (primarily for server-side usage with Buffers).

Returns

• Browser: Promise<Blob> - A promise that resolves to a Blob containing the segmented image.
• Server: Promise<Buffer> - A promise that resolves to a Buffer containing the segmented image.

Example (Browser - File Upload)

import { ImagineoAIClient } from "@imagineoai/javascript-sdk/browser";

const client = new ImagineoAIClient("YOUR_API_URL", { apiKey: "YOUR_API_KEY" });

const fileInput = document.getElementById('imageUploadForSegment'); // <input type="file" id="imageUploadForSegment">
const promptInput = document.getElementById('segmentPrompt'); // <input type="text" id="segmentPrompt">


async function handleSegmentationUpload() {
  const file = fileInput.files[0];
  const promptText = promptInput.value;

  if (file && promptText) {
    try {
      const imageBlob = await client.images.segmentImage.formData({ 
        image: file, 
        prompt: promptText 
      });
      console.log("Image segmented from uploaded file:", imageBlob);
      // Display logic for imageBlob
    } catch (error) {
      console.error("Error segmenting uploaded file:", error);
    }
  }
}

// Attach event listener to a button or form submission
// document.getElementById('segmentButton').addEventListener('click', handleSegmentationUpload);

Example (Server - Buffer)

import { ImagineoAIClient } from "@imagineoai/javascript-sdk/server";
import fs from 'fs/promises';

const client = new ImagineoAIClient("YOUR_API_URL", { apiKey: "YOUR_API_KEY" });

async function segmentFromLocalFile() {
  try {
    const imageBuffer = await fs.readFile("path/to/your/image_to_segment.png");
    const resultBuffer = await client.images.segmentImage.formData({
      image: imageBuffer,
      prompt: "cat on a mat",
      filename: "image_to_segment.png"
    });
    await fs.writeFile("local_image_segmented.png", resultBuffer);
    console.log("Image segmented from local file, image saved.");
  } catch (error) {
    console.error("Error segmenting local file:", error);
  }
}