Name: Grounded SAM – Detect & Segment Objects | Free · $5/mo | API.market
Brand: magicapi
SKU: api-magicapi-object-detection-segmentation-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🗂️ Advanced Object Detection & Mask Segmentation API (Grounded SAM)

## Overview
This API provides advanced object detection and mask segmentation capabilities for images using prompt-driven AI, leveraging Grounding DINO and the Segment Anything Model (SAM). By sending an image alongside positive and negative prompts, you can quickly and accurately identify and segment the objects that match (or don’t match) your specified criteria.

Use this API to:
- Extract specific objects from photos based on textual prompts
- Dynamically separate objects from backgrounds
- Generate segmented masks for advanced image editing or analysis

## Features
- Prompt-based Object Detection: Provide positive and negative prompts to isolate the items you care about.
- High-Quality Mask Segmentation: Produces refined segmentation masks with optional dilation or erosion adjustments.
- Fast Processing: Quickly detects and segments objects with minimal latency.
- Asynchronous Architecture: Ensures reliable performance for larger or more complex requests.
- Flexible Integration: Ideal for e-commerce, fashion, research, or other applications requiring object-level analysis.

## Use Cases
1. E-commerce Product Segmentation: Isolate products (clothes, shoes, bags) from background images for cleaner catalogs.  
2. Fashion Outfitting: Combine or separate outfit components for styling or recommendations (“clothes,” “shoes,” exclude “pants,” etc.).  
3. Background Removal: Quickly remove unwanted objects from images by specifying them as negative prompts.  
4. Manufacturing & Quality Control: Detect specific defects or components in plant images.  
5. Research & Analysis: Identify and segment various objects for computer vision tasks in scientific or academic contexts.

## Examples

### Input Example (Positive & Negative Prompts)
![Input fashion image used for segmentation](https://st.mngbcn.com/rcs/pics/static/T5/fotos/outfit/S20/57034757_56-99999999_01.jpg)

Above is an example input image. The prompt might look like:  
Positive mask prompt: "clothes,shoes"  
Negative mask prompt: "pants"  

### Output Example
When the request succeeds, the response might include one or more segmentation images:

![Annotated image showing clothes and shoes in the mask](https://replicate.delivery/pbxt/BQZ68Tf4k0U6Xiw6gbBNiB6PHeYNWCL9Y5YJihcPOOhZncyRA/annotated_picture_mask.jpg)  
*Annotated mask highlighting targeted objects (e.g., clothes, shoes).*

![Annotated image showing excluded objects](https://replicate.delivery/pbxt/fHrUkd4rydxCGK7fQTw6gdOnf68IUNyvpM4uCKEPOIeqdyJHB/neg_annotated_picture_mask.jpg)  
*Annotated mask indicating excluded objects (e.g., pants).*

![Generated mask of just the clothing items (positive prompt)](https://replicate.delivery/pbxt/OK9e1dEPmI35JKh2eT58XFmntzdBDIpqRlOzvzXJlmHbncyRA/mask.jpg)  
*A simpler mask output for positive prompts.*

![Inverted mask to separate background vs. object focus](https://replicate.delivery/pbxt/jQAawD111B4KF5nMUXVsP6xhANUoNpecRUmP5xTsylvtTO5IA/inverted_mask.jpg)  
*An inverted mask showcasing segmented areas in reverse.*

## Pricing
- 1 API unit = 1 image processed.  
- Checking prediction status with GET /api/v1/magicapi/object-detection-segmentation-api/predictions/{id} is free and does not consume any API units.  
- Various pricing tiers are available based on usage volume. Contact us to determine the best tier for your needs.

## API Documentation

### Base URL
All requests should be made to:  
```
https://prod.api.market/api/v1/magicapi/object-detection-segmentation-api
```

### Authentication
Include your API key in the request header:  
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API processes predictions asynchronously. The typical workflow is:

1. Submit a prediction request (POST /api/v1/magicapi/object-detection-segmentation-api/predictions).  
2. Receive a prediction ID in the response.  
3. Poll the GET /api/v1/magicapi/object-detection-segmentation-api/predictions/{id} endpoint to check status.  
4. Continue polling until the status is "succeeded" or "failed."

Processing time depends on request complexity. Recommended polling approach:
- Poll in 1-second intervals.
- Timeout if no result after 600 seconds (10 minutes).
- Handle success or failure accordingly.

### Endpoints

#### 1. Create a Prediction
• Method: POST  
• URL: /api/v1/magicapi/object-detection-segmentation-api/predictions

Use this endpoint to request a new object detection & segmentation task.

Request Body (JSON):
```json
{
  "version": "ee871c19efb1941f55f66a3d7d960428c8a5afcb77449547fe8e5a3ab9ebc21c",
  "input": {
    "image": "https://st.mngbcn.com/rcs/pics/static/T5/fotos/outfit/S20/57034757_56-99999999_01.jpg",
    "mask_prompt": "clothes,shoes",
    "negative_mask_prompt": "pants",
    "adjustment_factor": -15
  }
}
```

Example (cURL):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/object-detection-segmentation-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ee871c19efb1941f55f66a3d7d960428c8a5afcb77449547fe8e5a3ab9ebc21c",
    "input": {
      "image": "https://st.mngbcn.com/rcs/pics/static/T5/fotos/outfit/S20/57034757_56-99999999_01.jpg",
      "mask_prompt": "clothes,shoes",
      "negative_mask_prompt": "pants",
      "adjustment_factor": -15
    }
  }'
```

Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "ee871c19efb1941f55f66a3d7d960428c8a5afcb77449547fe8e5a3ab9ebc21c",
  "status": "starting",
  "created_at": "2025-04-21T10:44:17.776Z"
}
```

#### 2. Get Prediction Status & Results
• Method: GET  
• URL: /api/v1/magicapi/object-detection-segmentation-api/predictions/{id}

Check the status and retrieve the results of a previously requested prediction.

Response (JSON) when successful:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://replicate.delivery/pbxt/BQZ68Tf4k0U6Xiw6gbBNiB6PHeYNWCL9Y5YJihcPOOhZncyRA/annotated_picture_mask.jpg",
    "https://replicate.delivery/pbxt/fHrUkd4rydxCGK7fQTw6gdOnf68IUNyvpM4uCKEPOIeqdyJHB/neg_annotated_picture_mask.jpg",
    "https://replicate.delivery/pbxt/OK9e1dEPmI35JKh2eT58XFmntzdBDIpqRlOzvzXJlmHbncyRA/mask.jpg",
    "https://replicate.delivery/pbxt/jQAawD111B4KF5nMUXVsP6xhANUoNpecRUmP5xTsylvtTO5IA/inverted_mask.jpg"
  ],
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

Example (cURL):
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/object-detection-segmentation-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

## Status Codes
- 200 OK: Request was successful.  
- 201 Created: Resource successfully created (e.g., after POST).  
- 400 Bad Request: Invalid input or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: API key is valid but lacks permissions.  
- 404 Not Found: Resource does not exist.  
- 429 Too Many Requests: Rate limit exceeded; retry after a delay.  
- 500 Internal Server Error: An error occurred server-side.  
- 503 Service Unavailable: The service is temporarily unavailable or under maintenance.

## Rate Limits
Requests are rate-limited based on your plan. If you exceed your request quota, you’ll receive a 429 Too Many Requests response. Implement retry logic with exponential backoff to handle rate limits gracefully.

## Error Handling
When an error occurs, the API returns a JSON object containing details:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```

Best practices:
- Check the error code and message to determine the cause.  
- Resolve the issue (e.g., include required parameters, fix invalid prompts) and retry.  
- Implement retry loops for transient errors (e.g., 503 Service Unavailable).  
- Implement backoff for 429 Too Many Requests.

## Implementation Guide

### Example Code

#### JavaScript (Node.js)
```javascript
// JavaScript example with polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/object-detection-segmentation-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "ee871c19efb1941f55f66a3d7d960428c8a5afcb77449547fe8e5a3ab9ebc21c",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second

  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

#### Python
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/object-detection-segmentation-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    payload = {
        "version": "ee871c19efb1941f55f66a3d7d960428c8a5afcb77449547fe8e5a3ab9ebc21c",
        "input": input_data
    }
    
    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=payload)
    if response.status_code != 200 and response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds = 10 minutes
    POLL_INTERVAL = 1  # 1 second

    start_time = time.time()
    
    while (time.time() - start_time) < MAX_TIMEOUT:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers={"x-magicapi-key": API_KEY})
        
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")
        
        prediction = response.json()
        
        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")
        
        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")
```

#### cURL
```bash
# 1. Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/object-detection-segmentation-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ee871c19efb1941f55f66a3d7d960428c8a5afcb77449547fe8e5a3ab9ebc21c",
    "input": {
      "image": "https://st.mngbcn.com/rcs/pics/static/T5/fotos/outfit/S20/57034757_56-99999999_01.jpg",
      "mask_prompt": "clothes,shoes",
      "negative_mask_prompt": "pants"
    }
  }'

# Example Response:
# {"id": "ufawqhfynnddngldkgtslldrkq","status":"starting",...}

# 2. Poll for status
curl -X GET "https://prod.api.market/api/v1/magicapi/object-detection-segmentation-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Group similar requests together to reduce overhead.  
- Use smaller images or compressed formats to speed up processing.  
- Limit the frequency of requests to avoid rate-limiting.  

## FAQ
1. **How do I customize segmentation?**  
   Use the “adjustment_factor” parameter to dilate (positive) or erode (negative) the mask.

2. **Does the API support video inputs?**  
   This documentation focuses on image-based segmentation. Video processing may require frame-by-frame handling or a separate service.

3. **How quickly are results returned?**  
   Most predictions complete within seconds, but complex images/prompts may take longer.

4. **Is the API multilingual?**  
   Yes, prompt text can be in various languages, but results may vary in accuracy depending on the language used.

5. **How do I handle errors or failures?**  
   Inspect the error in the JSON response, fix the problem (e.g., invalid parameters), and retry.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Detect and segment objects in images using text prompts. Leverages Grounding DINO & SAM. Free 20 calls/mo, from $5/mo. Start free on API.market.

Grounded SAM – Detect & Segment Objects | Free · $5/mo | API.market

🗂️ Advanced Object Detection & Mask Segmentation API (Grounded SAM)

FREE

MagicAPI

PAYG

START

ULTRA

ELITE

MEGA

GIGA

BULK

Accurately detect and segment objects from images with lightning-fast, prompt-driven AI using Grounding DINO & SAM.