Name: Ultralytics YOLOv8s – Detect Any Object | $0.01/call | API.market
Brand: magicapi
SKU: api-magicapi-real-time-open-vocabulary-object-detection-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🔎 Real-Time Object Detection API (Ultralytics YOLOv8s Worldv2)

## Overview
This API provides real-time object detection capabilities using an open-vocabulary model based on the Ultralytics YOLOv8s Worldv2 architecture. With only 12.7M parameters, it delivers 37.7 mAP for high accuracy while remaining optimized for fast inference. Whether you need to detect people, vehicles, signs, or any other objects, this API quickly processes images to identify and locate relevant objects.

Below is an example of how the model can detect multiple objects in an image:

![Input image with a bus and people](https://replicate.delivery/pbxt/NTyS3y9a5eUQ0B8d1fCaIW41ENup2OkZOUmDK0siO92cfXf6/bus.jpg)

![Output image with bounding boxes for detected persons and bus](https://replicate.delivery/xezq/CR6l4fXbYnS3CqExqiFNXA3wKd2b1nn4u1qyCdGFHAzjzCkKA/output.png)

As shown above, the API can handle multiple objects within the same image and return bounding boxes, class labels, and confidence scores.

## Features
- Real-time object detection with 12.7M parameters.  
- Achieves 37.7 mAP50-95 on the COCO dataset.  
- Open-vocabulary support for detecting a variety of class names.  
- Configurable confidence threshold and IoU threshold for fine-tuning detection results.  
- Lightweight model size for smooth integration into high-traffic, real-time applications.  
- Returns results as a processed image (with bounding boxes) or as JSON with complete detection data.

## Use Cases
Below are some practical, industry-targeted use cases:

1. Smart Traffic Management Systems  
   Automate traffic flow monitoring to detect vehicles, pedestrians, and road signs in real time. Enhance traffic safety, optimize light cycles, and reduce congestion.

2. Retail Store Analytics  
   Track foot traffic and measure the effectiveness of in-store displays. Monitor customers, identify popular product sections, and gather valuable analytics for merchandising decisions.

3. Warehouse Automation and Logistics  
   Continuously monitor conveyor belts and storage areas to detect products, pallets, or equipment. Enhance inventory management and real-time tracking of goods.

4. Robotics and Autonomous Navigation  
   Equip robots or drones with on-board vision to identify obstacles, pedestrians, and signs in real time, improving collision avoidance and path planning.

5. Security and Surveillance  
   Automate threat detection or suspicious behavior in areas such as airports, stadiums, or public venues. Enable alerts for unauthorized objects or intrusions.

## Visual Examples
Here are additional images demonstrating input and output in context:

• Input image example (car, bus, and pedestrians):  
![Input image with a bus and people](https://replicate.delivery/pbxt/NTyS3y9a5eUQ0B8d1fCaIW41ENup2OkZOUmDK0siO92cfXf6/bus.jpg)

• Output image example after detection (bounding boxes, classes, and confidences):  
![Output image with bounding boxes for detected persons and bus](https://replicate.delivery/xezq/CR6l4fXbYnS3CqExqiFNXA3wKd2b1nn4u1qyCdGFHAzjzCkKA/output.png)

In the example above, the API identified multiple “person” objects and a “bus,” returning bounding boxes and confidence scores for each detected object.

## Pricing
• Pay As You Go (PAYG) model: only pay for what you use.  
• Each API call that processes an image counts as 1 API unit.  
• Checking prediction status via GET /api/v1/magicapi/real-time-open-vocabulary-object-detection-api/predictions/{id} is free and does not consume API units.  
• No monthly subscription fees or usage limits — simple per-call pricing.

## API Documentation

### Base URL
All API requests should be made to:
```
https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-object-detection-api
```

### Authentication
Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```
If the key is missing or invalid, you will receive a 401 Unauthorized error.

### Asynchronous Processing
This API uses asynchronous processing to handle predictions. The recommended approach:

1. Send a POST request to create a prediction.  
2. Receive a “prediction ID” in the response.  
3. Poll the GET endpoint with the prediction ID to check the status.  
4. The final result is available once the status is "succeeded."

Implementation tips:
- Poll every 1 second (POLL_INTERVAL = 1000 ms) to avoid overloading the service.  
- Set a maximum timeout of 10 minutes (600 seconds) per prediction.  
- Stop polling if the status is "failed" or "succeeded," or if the timeout is reached.

### Endpoints

#### 1. Create a Prediction
• Method: POST  
• URL: /api/v1/magicapi/real-time-open-vocabulary-object-detection-api/predictions  
• Purpose: Create a new prediction request for object detection.  

Request Body (JSON):
```json
{
  "input": {
    "image": "https://example.com/image.jpg",
    "conf": 0.25,
    "iou": 0.45,
    "imgsz": 640,
    "class_names": "person, bus",
    "return_json": true
  }
}
```

- image (required): URL of the image to analyze.  
- conf (optional): Confidence threshold (0 < conf <= 1).  
- iou (optional): IoU threshold for non-max suppression (0 < iou <= 1).  
- imgsz (optional): Image size for resizing (e.g., 640).  
- class_names (optional): Comma-separated class labels to detect specifically.  
- return_json (optional): Return the bounding boxes and detection data in JSON.

Example cURL:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-object-detection-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg",
      "conf": 0.25,
      "iou": 0.45,
      "imgsz": 640,
      "class_names": "person, bus",
      "return_json": true
    }
  }'
```

Success Response (HTTP 201):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "fae5476fa332edc9f40032f5af8176c1689d27134f373883bc03c0aaf2a54b63",
  "status": "starting",
  "created_at": "2025-08-17T17:19:38.856Z"
}
```

#### 2. Get Prediction Status
• Method: GET  
• URL: /api/v1/magicapi/real-time-open-vocabulary-object-detection-api/predictions/{id}  
• Purpose: Retrieve the status and results of an existing prediction.

Example cURL:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-object-detection-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Example Success Response (HTTP 200):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": {
    "image": "https://replicate.delivery/xezq/CR6l4fXbYnS3CqExqiFNXA3wKd2b1nn4u1qyCdGFHAzjzCkKA/output.png",
    "json_str": "[...]"
  },
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```
- status: “starting,” “processing,” “succeeded,” “failed,” or “canceled.”
- output: Contains either image URL with bounding boxes and/or JSON string with detection data.

## Status Codes
- 200 OK: Request was successful.  
- 201 Created: A new prediction was successfully created.  
- 400 Bad Request: Invalid parameters or a malformed request body.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: You do not have the required permissions.  
- 404 Not Found: The requested resource or prediction ID does not exist.  
- 429 Too Many Requests: Rate limit exceeded; wait or slow down requests.  
- 500 Internal Server Error: A server-side error occurred; try again later.  
- 503 Service Unavailable: Service is temporarily unavailable; try again later.

## Rate Limits
When rate limits are in effect, exceeding them will result in a 429 Too Many Requests error. For large-scale or high-frequency usage, ensure your application implements exponential backoff or retries with appropriate intervals.

## Error Handling
If an error occurs, you will receive a JSON response with an error object:

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

Common errors include missing required parameters, invalid image URLs, or invalid authentication headers. Implement robust error handling to catch and interpret these messages correctly.

## Implementation Guide

### Example Code

Below are some sample code snippets illustrating the asynchronous prediction flow.

#### JavaScript (Node.js)
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-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-api-market-key": apiKey
      },
      body: JSON.stringify({ 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-api-market-key": apiKey
      }
    });

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

    const prediction = await response.json();

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

    // Wait before next poll
    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/real-time-open-vocabulary-object-detection-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json={"input": input_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  # 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-api-market-key": API_KEY})

        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"]
        elif 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/real-time-open-vocabulary-object-detection-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg"
    }
  }'

# The response includes a prediction ID. For example:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Poll for prediction status using the ID
curl -X GET "https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-object-detection-api/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Send concise requests with minimal overhead (avoid extremely large images if possible).  
- Use appropriate confidence and IoU thresholds to limit the detection of lower-confidence or overlapping objects.  
- Reuse connections (keep-alive) to reduce latency on repetitive calls.  
- Implement an exponential backoff for polling if you approach rate limits.

## FAQ
1. Can I use this API for video streams?  
   – Currently, you can process video frames by sending individual frames as images. Direct video file detection is not provided.

2. Does the API limit specific classes for detection?  
   – You can specify class names to filter detections. If you leave class_names empty, the model detects all objects it recognizes.

3. How many objects can it detect in a single image?  
   – The model can detect multiple objects depending on your confidence threshold. In principle, it can detect dozens of instances per image.

4. Is there a limit on image size?  
   – The API resizes images to the specified imgsz setting for detection. Very large images will be resized automatically.

5. How do I handle failed predictions?  
   – Check the “status” field. If it’s “failed,” look at the “error” message in the response for more info and retry if appropriate.

## 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 with open-vocabulary AI. High accuracy with 37.7 mAP. From $0.01/call. Try it free on API.market.

Ultralytics YOLOv8s – Detect Any Object | $0.01/call | API.market

🔎 Real-Time Object Detection API (Ultralytics YOLOv8s Worldv2)

PAYG

MagicAPI

the real-time object detection api (yolov8s worldv2)is light, fast, and accurate—great for spotting people, vehicles, or signs in images. super useful for traffic, retail, or security tasks.
