Name: Grounding DINO SwinB Text-Prompted Object Detection API
Brand: magicapi
SKU: api-magicapi-object-detection-api-candysunplus-grounding-dino-swinb
Availability: InStock
Author: API Market

Shashank Agarwal

# 🔍 Text-Prompted Object Detection API (candysunplus Grounding DINO SwinB)

## Overview
Grounding DINO SwinB is a text-prompted object detection model (SwinB variant), published by candysunplus. It finds objects in an image from a text description, so you can detect things by name (for example `pink mug`) instead of picking from a fixed class list.

Send an `image` and a comma-separated `query`. The model returns a list of detections (label, bounding box, confidence) and, by default, an image with the boxes drawn on it.

## Features
- **Detect by description**: `query` takes comma-separated object names or short phrases such as `pink mug`.
- **Bounding boxes with scores**: each detection has a `label`, a `bbox` in pixels (`[x_min, y_min, x_max, y_max]`) and a `confidence` between 0 and 1.
- **Two thresholds**: `box_threshold` and `text_threshold` (both 0 to 1, default 0.25) filter weak boxes and weak text matches.
- **Visualisation**: `show_visualisation` (default `true`) also returns the image with the boxes drawn on it.

## Use Cases
1. **Find specific items**: locate an object described by colour or type, such as "pink mug" or "red car".
2. **Image tagging and search**: check whether named items appear in product or user photos.
3. **Annotation drafts**: generate first-pass bounding boxes for a labelling team to review.
4. **Cropping pipelines**: use the boxes to crop the named object out of a larger photo.

## Visual Examples
### Example Input
![Grounding DINO example input: a photo of several mugs](https://blog.api.market/wp-content/uploads/2026/10/grounding-dino-input-api-market.webp)

Query: "pink mug"

Settings: `box_threshold` `0.25`, `text_threshold` `0.25`, `show_visualisation` `true`.

### Example Output
![Grounding DINO output: the mugs photo with a labelled bounding box around the pink mug](https://blog.api.market/wp-content/uploads/2026/10/grounding-dino-swinb-output-0dn02jee-api-market.jpg)

Detections returned:

| Label | Bounding box `[x_min, y_min, x_max, y_max]` | Confidence |
| --- | --- | --- |
| pink mug | `[19, 205, 408, 563]` | 0.702 |

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Input image to query (jpeg, png, gif or webp) |
| `query` | string | Yes |  |  | Comma-separated names of the objects to detect in the image |
| `box_threshold` | number | No | `0.25` | 0 to 1 | Confidence level for object detection (minimum box score) |
| `text_threshold` | number | No | `0.25` | 0 to 1 | Confidence level for object detection (minimum text match score) |
| `show_visualisation` | boolean | No | `true` |  | Draw the bounding boxes on the image and return it as `result_image` |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0033 per API unit.
- **1 API unit = 1 successful request with up to 3 seconds of processing.** A longer job bills one more unit for each started block of 3 seconds (for example, 7 seconds of processing is 3 units, $0.0099).
- Processing time grows with image size.
- **Example cost**: the example request took 1.9 seconds of processing, which is 1 unit, so $0.0033.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/object-detection-api-candysunplus-grounding-dino-swinb`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/object-detection-api-candysunplus-grounding-dino-swinb/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ab97c39a0f738126d40d8487bf3969cea1269596743f3659f7ae38715995feaa",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/10/grounding-dino-input-api-market.webp",
      "query": "pink mug",
      "box_threshold": 0.25,
      "text_threshold": 0.25,
      "show_visualisation": true
    }
  }'
```

Response (201 Created):
```json
{
  "id": "0dn02jee51rmw0d1f19ryvezr4",
  "version": "ab97c39a0f738126d40d8487bf3969cea1269596743f3659f7ae38715995feaa",
  "status": "starting",
  "created_at": "2026-10-26T13:08:40.862Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/object-detection-api-candysunplus-grounding-dino-swinb/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "0dn02jee51rmw0d1f19ryvezr4",
  "status": "succeeded",
  "output": {
    "detections": [
      { "bbox": [19, 205, 408, 563], "confidence": 0.7023822665214539, "label": "pink mug" }
    ],
    "result_image": "https://blog.api.market/wp-content/uploads/2026/10/grounding-dino-swinb-output-0dn02jee-api-market.jpg"
  },
  "error": null,
  "created_at": "2026-10-26T13:08:40.862Z",
  "started_at": "2026-10-26T13:09:31.360Z",
  "completed_at": "2026-10-26T13:09:33.272Z"
}
```

`output` is an object. `detections` is a list of objects, each with `label`, `bbox` (`[x_min, y_min, x_max, y_max]` in pixels of the input image) and `confidence`. `result_image` holds the image with the boxes drawn when `show_visualisation` is `true`, otherwise `null`. In our test run the live API returned `result_image` as an inline PNG data URI (`data:image/png;base64,...`) rather than a link; the example above shows our hosted copy of that image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image` or `query`, or a threshold outside 0 to 1.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/object-detection-api-candysunplus-grounding-dino-swinb";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "ab97c39a0f738126d40d8487bf3969cea1269596743f3659f7ae38715995feaa", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

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

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

    const prediction = await response.json();

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

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

    await delay(pollInterval);
  }

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

createAndWaitForPrediction({
  "image": "https://blog.api.market/wp-content/uploads/2026/10/grounding-dino-input-api-market.webp",
  "query": "pink mug",
  "box_threshold": 0.25,
  "text_threshold": 0.25,
  "show_visualisation": true
}).then((output) => {
  for (const det of output.detections) {
    console.log(det.label, det.bbox, det.confidence.toFixed(3));
  }
});
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/object-detection-api-candysunplus-grounding-dino-swinb"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "ab97c39a0f738126d40d8487bf3969cea1269596743f3659f7ae38715995feaa", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-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()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


output = create_and_wait_for_prediction({
    "image": "https://blog.api.market/wp-content/uploads/2026/10/grounding-dino-input-api-market.webp",
    "query": "pink mug",
    "box_threshold": 0.25,
    "text_threshold": 0.25,
    "show_visualisation": True
})
for det in output["detections"]:
    print(det["label"], det["bbox"], round(det["confidence"], 3))
```

## FAQ
- **Can I search for several objects at once?**
  - Yes. Separate them with commas in `query`, for example `pink mug, spoon`. Each detection's `label` tells you which name it matched.
- **What do `box_threshold` and `text_threshold` change?**
  - Both default to 0.25. Raise them to keep only strong matches; lower them if the object you want is missed.
- **What format are the bounding boxes in?**
  - `[x_min, y_min, x_max, y_max]` in pixels of the input image.
- **How do I read `result_image`?**
  - It can arrive as a base64 PNG data URI (`data:image/png;base64,...`). Decode the part after the comma to save it as a PNG file. Set `show_visualisation` to `false` if you only need the boxes.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## 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@magicapi.com.


Detect objects by name or short phrase with Grounding DINO SwinB: labelled boxes, scores and an annotated image. $0.0033 per request, pay as you go.