Name: Grounding DINO – Detect Objects by Text | Free · $5/mo | API.market
Brand: magicapi
SKU: api-magicapi-language-guided-object-detection-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🧭 Language-Guided Object Detection API (Grounding DINO) - Detect Anything Fast

## Overview
This API empowers you to detect and localize objects in images based on natural language prompts. With powerful language-guided object detection using Grounding DINO, it identifies objects you specify (e.g., “pink mug”) and returns bounding boxes and confidence scores. You can also obtain a visualized output image with bounding boxes drawn on it for easy inspection.

## Features
- **Language-Guided Detection**: Provide a simple text prompt (e.g., “phone, pen, laptop”) to detect items in images.  
- **Adjustable Thresholds**: Control detection sensitivity with adjustable box and text thresholds.  
- **Bounding Box Visualization**: Optionally receive visually annotated images showing detected objects.  
- **Fast and Scalable**: Optimized for speed, making it ideal for production workloads.  
- **Asynchronous Processing**: Submit detection requests and poll for results, scaling seamlessly with your application.

## Use Cases
1. **E-commerce Product Tagging**: Automatically detect and tag products in user-uploaded images to streamline catalog creation.  
2. **Inventory Management**: Quickly locate and count inventory items in warehouse images or camera feeds.  
3. **Content Moderation**: Detect prohibited objects in images for content safety.  
4. **Social Media Analytics**: Identify brand logos or specific object references within large volumes of user-generated content.  
5. **Robotics & Automation**: Guide robotic systems to locate relevant objects in real-time.

## Examples

### Visual Example
Below is an example of detecting “pink mug” in an image:

**Input Image** (query: "pink mug"):
![An image of multiple coffee mugs, some of which are pink](https://replicate.delivery/pbxt/JlgUQIQCDemKg7bnfn5zKMqLgAPrZdpMMHzkXgHX5HUlbw9z/mugs.webp)

**Output Image** (with bounding boxes drawn):
![The same image with bounding boxes drawn around pink mugs](https://pbxt.replicate.delivery/oJDgostFveUPEiUVnTRM9MnL7rxEMXIuy65E6K2X638PfFyRA/result.png)

The output also includes a JSON structure describing each detected object’s bounding box, label, and confidence score.

## Pricing
• 1 API unit = 1 image processed.  
• Checking prediction status with GET /api/v1/magicapi/language-guided-object-detection-api/predictions/{id} is free (no API unit cost).  
• Various pricing tiers are available based on monthly usage volume. Choose the plan that matches your anticipated load.

## API Documentation

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

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

### Asynchronous Processing
Creating a prediction will return immediately with a prediction ID. The detection process may take some time depending on the complexity of the image. To obtain the final result:

1. Make a POST request to create a prediction.  
2. Receive a prediction ID in the response.  
3. Poll the GET endpoint with the ID.  
4. Continue polling until the status is "succeeded" or "failed".  

Recommended polling interval is 1 second, with a maximum timeout of 600 seconds (10 minutes).

### Endpoints

#### 1. Create a Prediction

• **Endpoint**:  
  POST /api/v1/magicapi/language-guided-object-detection-api/predictions  

• **Description**:  
  Creates an object detection prediction request.  

• **Request Body** (JSON):
```json
{
  "version": "efd10a8ddc57ea28773327e881ce95e20cc1d734c589f7dd01d2036921ed78aa",
  "input": {
    "image": "https://replicate.delivery/pbxt/JlgUQIQCDemKg7bnfn5zKMqLgAPrZdpMMHzkXgHX5HUlbw9z/mugs.webp",
    "query": "pink mug",
    "box_threshold": 0.2,
    "text_threshold": 0.2,
    "show_visualisation": true
  }
}
```

• **Response**  
  - **201 Created**  
    Returns a JSON object containing the `id` (prediction ID), `version`, `status`, and `created_at` timestamp.
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "efd10a8ddc57ea28773327e881ce95e20cc1d734c589f7dd01d2036921ed78aa",
  "status": "starting",
  "created_at": "2025-04-21T10:44:16.959Z"
}
```
  
  - **400 Bad Request**  
    Returned if the request body is invalid or required properties are missing.  

  - **401 Unauthorized**  
    Returned if the API key is invalid or missing.

#### Example (cURL)
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/language-guided-object-detection-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "efd10a8ddc57ea28773327e881ce95e20cc1d734c589f7dd01d2036921ed78aa",
    "input": {
      "image": "https://replicate.delivery/pbxt/JlgUQIQCDemKg7bnfn5zKMqLgAPrZdpMMHzkXgHX5HUlbw9z/mugs.webp",
      "query": "pink mug",
      "box_threshold": 0.2,
      "text_threshold": 0.2,
      "show_visualisation": true
    }
  }'
```

#### 2. Get Prediction Status and Results

• **Endpoint**:  
  GET /api/v1/magicapi/language-guided-object-detection-api/predictions/{id}  

• **Description**:  
  Returns the current status of a prediction and, if completed, the output (detections and annotated image).  

• **Response**  
  - **200 OK**  
    Example (status = succeeded):
    ```json
    {
      "id": "ufawqhfynnddngldkgtslldrkq",
      "status": "succeeded",
      "output": {
        "detections": [
          {
            "bbox": [19, 204, 408, 563],
            "label": "pink mug",
            "confidence": 0.8077122569084167
          }
        ],
        "result_image": "https://pbxt.replicate.delivery/oJDgostFveUPEiUVnTRM9MnL7rxEMXIuy65E6K2X638PfFyRA/result.png"
      },
      "created_at": "2023-01-01T12:00:00.000Z",
      "started_at": "2023-01-01T12:00:05.000Z",
      "completed_at": "2023-01-01T12:01:00.000Z"
    }
    ```

  - **401 Unauthorized**  
    Invalid or missing API key.  

  - **404 Not Found**  
    No prediction found with the specified ID.

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

## Status Codes
Below is a comprehensive list of potential HTTP status codes returned by this API:

- **200 OK**: The request succeeded, and the server returns the requested data.  
- **201 Created**: The request succeeded, and a new resource was created (e.g., new prediction).  
- **400 Bad Request**: The request was malformed or contained invalid parameters.  
- **401 Unauthorized**: The API key is missing or invalid.  
- **403 Forbidden**: The request is understood, but you do not have the required permissions.  
- **404 Not Found**: The specified resource does not exist.  
- **429 Too Many Requests**: You have hit a rate limit. Wait before sending additional requests.  
- **500 Internal Server Error**: A server-side error occurred.  
- **503 Service Unavailable**: The service is temporarily unavailable or undergoing maintenance.

## Rate Limits
Depending on your plan, there may be a maximum number of requests per minute, hour, or day. If you exceed the limit, you will receive a 429 Too Many Requests response. Implement exponential backoff or manual retry strategies if you encounter rate-limiting errors.

## Error Handling
Below is a typical JSON structure for error responses:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```
• Always check for non-200 status codes.  
• Inspect the `error` object to determine the cause.  
• Common errors include invalid parameters (400), lack of authentication (401), or rate limiting (429).  
• If errors are transient (e.g., 503), implement retry logic with exponential backoff.

## Implementation Guide

### Example Code

Below are example workflows in JavaScript, Python, and cURL, demonstrating how to create a new prediction, and then poll until completion.

#### JavaScript

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/language-guided-object-detection-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: "efd10a8ddc57ea28773327e881ce95e20cc1d734c589f7dd01d2036921ed78aa",
        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
# Python example with proper polling and timeout
import requests
import time

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

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    data = {
        "version": "efd10a8ddc57ea28773327e881ce95e20cc1d734c589f7dd01d2036921ed78aa",
        "input": input_data
    }

    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=data)
    if response.status_code != 201 and response.status_code != 200:
        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

    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()
        status = prediction["status"]

        if status == "succeeded":
            return prediction["output"]
        if 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
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/language-guided-object-detection-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
      "version": "efd10a8ddc57ea28773327e881ce95e20cc1d734c589f7dd01d2036921ed78aa",
      "input": {
        "image": "https://replicate.delivery/pbxt/JlgUQIQCDemKg7bnfn5zKMqLgAPrZdpMMHzkXgHX5HUlbw9z/mugs.webp",
        "query": "pink mug"
      }
    }'

# Example response (abbreviated):
# {"id": "abcd1234", "status": "starting", ...}

# Step 2: Check the status of the prediction
curl -X GET "https://prod.api.market/api/v1/magicapi/language-guided-object-detection-api/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

# Poll this endpoint repeatedly until "status" is "succeeded" or "failed".
```

### Performance Optimization
- Use efficient polling intervals (1s recommended).  
- Limit the size of images (e.g., downsampling large images) to reduce processing overhead.  
- Bundle requests where possible to make use of concurrency.  
- Cache results for repeated queries on identical images and queries.

## FAQ
1. **How long does it take to process one image?**  
   Processing usually takes a few seconds, but can vary depending on image size, server load, and the complexity of the request.  
2. **What if no objects are found?**  
   The API returns an empty array for “detections” if no relevant objects match the prompt.  
3. **Is there a limit to the number of objects I can query?**  
   You can specify multiple objects in a comma-separated string. Ensure your thresholds are set appropriately.  
4. **What if the image URL is invalid or inaccessible?**  
   You’ll receive a 400 Bad Request error if the API cannot retrieve the image from the provided URL.

## 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 any object in images using simple text prompts. Returns bounding boxes. Free 20 calls/mo, from $5/mo. Start free on API.market.

Grounding DINO – Detect Objects by Text | Free · $5/mo | API.market

🧭 Language-Guided Object Detection API (Grounding DINO) - Detect Anything Fast

FREE

MagicAPI

PAYG

START

ULTRA

ELITE

MEGA

GIGA

BULK

Detect and localize any object in images from natural language prompts with ultra-fast, accurate AI powered by Grounding DINO.