Name: Google OWL-ViT Base Patch32 Zero-Shot Object Detection API
Brand: magicapi
SKU: api-magicapi-zero-shot-object-detection-adirik-owlvit-base-patch32
Availability: InStock
Author: API Market

Shashank Agarwal

# 🔍 Zero-Shot Object Detection API (Google OWL-ViT Base Patch32)

## Overview
OWL-ViT Base Patch32 is an open-vocabulary object detection model from Google Research, packaged by adirik. It finds objects in an image from plain-text names, so you can detect classes it was never specifically trained on (zero-shot detection).

Send an `image` and a comma-separated `query` such as `dog, bicycle, car`. The model returns a JSON list of detected objects (label, bounding box, confidence) and, by default, the URL of a copy of the image with the boxes drawn on it.

## Features
- **Open vocabulary**: name the objects you want in `query` as comma-separated text; no fixed class list.
- **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.
- **Confidence threshold**: `threshold` (0 to 1, default 0.1) drops detections below that score.
- **Visualisation**: `show_visualisation` (default `true`) also returns an image with the boxes drawn on it.

## Use Cases
1. **Ad hoc detection**: find objects that are not in a standard detector's class list without training a model.
2. **Image tagging**: check whether given items appear in user-uploaded or catalog photos.
3. **Dataset bootstrapping**: draft bounding boxes for new classes before manual review.
4. **Visual QA checks**: confirm that a scene contains (or lacks) named objects.

## Visual Examples
### Example Input
![OWL-ViT example input: a photo with a dog and a bicycle](https://blog.api.market/wp-content/uploads/2026/10/yolox-input-api-market.jpg)

Query: "dog, bicycle, car"

Settings: `threshold` `0.11`, `show_visualisation` `true`.

### Example Output
![OWL-ViT output: the input photo with labelled bounding boxes for the dog, the bicycle and a car](https://blog.api.market/wp-content/uploads/2026/10/owlvit-base-patch32-output-31rqy5e2-api-market.png)

Detections returned in `json_data` (confidence rounded):

| Label | Bounding box `[x_min, y_min, x_max, y_max]` | Confidence |
| --- | --- | --- |
| bicycle | `[65, 73, 121, 131]` | 0.126 |
| car | `[466, 77, 686, 171]` | 0.138 |
| bicycle | `[137, 116, 577, 429]` | 0.365 |
| dog | `[133, 220, 320, 540]` | 0.319 |

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | No | none |  | Input image to query (jpeg, png, gif or webp). Send one with every request |
| `query` | string | No | none |  | Comma-separated names of the objects to detect in the image. Send one with every request |
| `threshold` | number | No | `0.1` | 0 to 1 | Confidence level for object detection; lower scores are dropped |
| `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.001 per API unit.
- **1 API unit = 1 successful request with up to 4 seconds of processing.** A longer job bills one more unit for each started block of 4 seconds (for example, 10 seconds of processing is 3 units, $0.003).
- Processing time grows with image size.
- **Example cost**: the example request took 2.6 seconds of processing, which is 1 unit, so $0.001.
- **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/zero-shot-object-detection-adirik-owlvit-base-patch32`

### 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/zero-shot-object-detection-adirik-owlvit-base-patch32/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "5e899f155a1913c4b7304d09082d842ca7fe6cb1f22e066c83eb1d7849dc37c2",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/10/yolox-input-api-market.jpg",
      "query": "dog, bicycle, car",
      "threshold": 0.11,
      "show_visualisation": true
    }
  }'
```

Response (201 Created):
```json
{
  "id": "31rqy5e2g1rgc0d1f19t4nfber",
  "version": "5e899f155a1913c4b7304d09082d842ca7fe6cb1f22e066c83eb1d7849dc37c2",
  "status": "starting",
  "created_at": "2026-10-26T13:08:37.798Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/zero-shot-object-detection-adirik-owlvit-base-patch32/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "31rqy5e2g1rgc0d1f19t4nfber",
  "status": "succeeded",
  "output": {
    "json_data": {
      "objects": [
        { "bbox": [65, 73, 121, 131], "confidence": 0.12599006295204163, "label": "bicycle" },
        { "bbox": [466, 77, 686, 171], "confidence": 0.1380358189344406, "label": "car" },
        { "bbox": [137, 116, 577, 429], "confidence": 0.3645002245903015, "label": "bicycle" },
        { "bbox": [133, 220, 320, 540], "confidence": 0.3189026415348053, "label": "dog" }
      ]
    },
    "result_image": "https://blog.api.market/wp-content/uploads/2026/10/owlvit-base-patch32-output-31rqy5e2-api-market.png"
  },
  "error": null,
  "created_at": "2026-10-26T13:08:37.798Z",
  "started_at": "2026-10-26T13:11:35.106Z",
  "completed_at": "2026-10-26T13:11:37.709Z"
}
```

`output` is an object. `json_data.objects` is the list of detections, each with `label`, `bbox` (`[x_min, y_min, x_max, y_max]` in pixels of the input image) and `confidence`. `result_image` is the URL of the image with the boxes drawn on it, returned when `show_visualisation` is `true`.

### 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 `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/zero-shot-object-detection-adirik-owlvit-base-patch32";

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: "5e899f155a1913c4b7304d09082d842ca7fe6cb1f22e066c83eb1d7849dc37c2", 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/yolox-input-api-market.jpg",
  "query": "dog, bicycle, car",
  "threshold": 0.11,
  "show_visualisation": true
}).then((output) => {
  for (const obj of output.json_data.objects) {
    console.log(obj.label, obj.bbox, obj.confidence.toFixed(3));
  }
  console.log(output.result_image);
});
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/zero-shot-object-detection-adirik-owlvit-base-patch32"


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": "5e899f155a1913c4b7304d09082d842ca7fe6cb1f22e066c83eb1d7849dc37c2", "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/yolox-input-api-market.jpg",
    "query": "dog, bicycle, car",
    "threshold": 0.11,
    "show_visualisation": True
})
for obj in output["json_data"]["objects"]:
    print(obj["label"], obj["bbox"], round(obj["confidence"], 3))
print(output.get("result_image"))
```

## FAQ
- **How do I choose which objects to detect?**
  - List them in `query`, separated by commas, for example `dog, bicycle, car`. Each detection's `label` is one of the names you sent.
- **Why are the confidence scores low?**
  - Open-vocabulary scores from this model are often well below 0.5 even for correct boxes; in the example the dog scored 0.32. Start with a low `threshold` (the default is 0.1) and raise it if you get too many false boxes.
- **What format are the bounding boxes in?**
  - `[x_min, y_min, x_max, y_max]` in pixels of the input image.
- **Can I get only the JSON without the drawn image?**
  - Yes. Set `show_visualisation` to `false`; `json_data` is always returned.
- **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.


Find any named object in an image with Google OWL-ViT: open-vocabulary detection with labels, pixel boxes and scores. $0.001 per request.