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

Shashank Agarwal

# 🦾 Real-Time Object Detection API (YOLOv8s Worldv2)

## Overview
Experience lightning-fast, open-vocabulary object detection in real time with this YOLOv8s Worldv2 model. It efficiently detects multiple objects in images, allowing you to specify custom class names or let the model automatically detect relevant objects. With just 12.7M parameters, it’s optimized for robust, near-instant inference—perfect for high-volume production use.

![Example input image showing a bus and people on the street](https://replicate.delivery/pbxt/NTyS3y9a5eUQ0B8d1fCaIW41ENup2OkZOUmDK0siO92cfXf6/bus.jpg)

## Features
- Open-Vocabulary Detection: Specify custom objects or detect automatically.  
- High Accuracy: Achieves 37.7 mAP50-95 on the COCO dataset.  
- Lightning-Fast Inference: Real-time performance with only 12.7M parameters.  
- Flexible Output: Get annotated images or JSON outputs with bounding boxes, class labels, and confidence scores.  
- Simple Integration: Easy to incorporate into existing pipelines for various industries.

## Use Cases

1. **Retail Analytics**  
   Track customer movements, detect products on shelves, and count foot traffic with real-time detection, optimizing store layouts and operations.

2. **Manufacturing Quality Control**  
   Detect defects on conveyor belts or assembly lines. Quickly identify anomalies such as misplaced components or damaged goods.

3. **Security & Surveillance**  
   Monitor sensitive zones for intruders, detect suspicious objects left in a corridor, and raise alerts for quick responses.

4. **Smart Transportation**  
   Automatically identify vehicles, pedestrians, and road signs to enhance self-driving algorithms and real-time traffic analysis.

5. **Warehouse Automation**  
   Track package movements, count stock levels on pallets, and ensure items are in the correct locations.

## Visual Examples
Below is an example of an output image returned by the API, showcasing bounding boxes and detected classes:

![Example output image from the model showing bounding boxes around people and a bus](https://replicate.delivery/xezq/CR6l4fXbYnS3CqExqiFNXA3wKd2b1nn4u1qyCdGFHAzjzCkKA/output.png)

When you make a request to detect objects in an image, you can optionally set “return_json” to true to get a JSON response containing bounding boxes, classes, and confidence scores.

## Pricing
- Pay As You Go (PAYG): Only pay for what you use.  
- 1 API unit = 1 image processed (per POST request).  
- GET requests to check prediction status are free and do not count toward usage.  
- No monthly subscription fees or usage limits—purely per-call pricing.

## API Documentation

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

### Authentication
Include your API key in every request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API processes predictions asynchronously. Follow these steps:
1. Send a POST request with your image and parameters to initiate a prediction.  
2. Receive a unique “prediction ID” in the response.  
3. Use the GET endpoint (free of charge) to poll for the prediction status.  
4. When status is "succeeded", your output data is ready.

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

### Endpoints

#### 1. Create a Prediction

• **Method**: POST  
• **URL**:  
```
POST /api/v1/magicapi/real-time-open-vocabulary-object-detection/predictions
```

##### Request Body
Provide your desired parameters in JSON. For example:
```json
{
  "input": {
    "conf": 0.25,
    "iou": 0.45,
    "image": "https://example.com/image.jpg",
    "imgsz": 640,
    "class_names": "person, bus",
    "return_json": true
  }
}
```

| Field        | Type    | Default | Description                                             |
|--------------|---------|---------|---------------------------------------------------------|
| conf         | float   | 0.25    | Confidence threshold for object detection              |
| iou          | float   | 0.45    | IoU threshold for non-maximum suppression (NMS)        |
| image        | string  | None    | URL of the input image                                 |
| imgsz        | integer | 640     | Image size (width/height)                              |
| class_names  | string  | (empty) | Comma-separated list of classes to filter (optional)   |
| return_json  | boolean | false   | Returns results as JSON if set to true                 |

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

##### Response (201 Created)
A successful response will look like:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "fae5476fa332edc9f40032f5af8176c1689d27134f373883bc03c0aaf2a54b63",
  "status": "starting",
  "created_at": "2025-08-17T17:38:35.109Z"
}
```

| Field        | Description                                    |
|--------------|------------------------------------------------|
| id           | Unique prediction ID                           |
| version      | Model version ID used for this prediction      |
| status       | Current status: “starting” or “processing”     |
| created_at   | Timestamp of the prediction creation           |

#### 2. Get Prediction Status and Results

• **Method**: GET  
• **URL**:  
```
GET /api/v1/magicapi/real-time-open-vocabulary-object-detection/predictions/{id}
```
  
Check the status of an ongoing prediction by providing the unique prediction ID you received from the POST endpoint.

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

##### Response (200 OK)
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": {
    "image": "https://prod.api.market/userfiles/processed_image.png",
    "json_str": "[ ... bounding box data here ... ]"
  },
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

| Field        | Description                                                            |
|--------------|------------------------------------------------------------------------|
| id           | Unique prediction ID                                                   |
| status       | “starting”, “processing”, “succeeded”, “failed”, or “canceled”         |
| output       | Contains output fields (annotated image URL, JSON string, etc.)        |
| error        | Populated if the prediction has failed                                 |
| created_at   | Timestamp of the prediction creation                                   |
| started_at   | Timestamp when processing actually started                             |
| completed_at | Timestamp when processing completed                                   |

### Status Codes
- **200 OK**: The request was processed successfully.  
- **201 Created**: The resource (prediction) was successfully created.  
- **400 Bad Request**: The input parameters were invalid or malformed.  
- **401 Unauthorized**: The API key was missing or invalid.  
- **403 Forbidden**: The API key is valid, but you do not have permission.  
- **404 Not Found**: The requested resource (prediction ID) does not exist.  
- **429 Too Many Requests**: The rate limit was exceeded. Retry after some time.  
- **500 Internal Server Error**: An error occurred on the server side.  
- **503 Service Unavailable**: The service is temporarily unavailable; try again later.

### Rate Limits
Requests may be rate limited if they exceed system capacity. If you receive a 429 error, pause your requests for a short time before retrying.

### Error Handling
If your request is invalid or fails, you’ll receive a JSON error response:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```

- Examine the “code” for a high-level error type.  
- Review the “message” to understand what went wrong.  
- Adjust your request or retry as appropriate.

## Implementation Guide

Below are some example implementations illustrating how to create and poll for predictions.

### JavaScript (Node.js) Example
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-object-detection";

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 a 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 between checks
  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();

    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 Example
```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"

def create_and_wait_for_prediction(input_data):
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }

    # Step 1: Create the prediction
    response = requests.post(f"{BASE_URL}/predictions", json={"input": input_data}, headers=headers)
    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 the result
    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()

        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 Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-object-detection/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg"
    }
  }'

# Example Response:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Poll for results
curl -X GET "https://prod.api.market/api/v1/magicapi/real-time-open-vocabulary-object-detection/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
  
# Keep polling until "status" is "succeeded".
```

### Performance Optimization
- **Batching**: If possible, structure your usage so that you only upload images when needed.  
- **Image Size**: Lower-resolution images (e.g., 640×640) process faster than extremely large images.  
- **Reduce Calls**: Rather than polling too frequently, wait at least 1 second between checks.

## FAQ
1. **How accurate is the model?**  
   – The YOLOv8s Worldv2 variant achieves 37.7 mAP50-95 on the COCO dataset.

2. **Can I specify custom classes?**  
   – Yes. Use the “class_names” parameter to filter or specifically track certain objects.

3. **What if an image has no detectable objects?**  
   – The output image will be unchanged, and any JSON output will be an empty list.

4. **Is there a limit to file size?**  
   – While there’s no specific hard limit, large files increase latency and can risk timeouts. We recommend using images up to 1280×1280 for best performance.

5. **Do I pay for status checks?**  
   – No. GET requests to retrieve status are free.

## 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.

Instantly detect any object in images with open-vocabulary. Fast 12.7M param model. From $0.01/call. Try it free on API.market.

YOLOv8s Worldv2 – Object Detection | $0.01/call | API.market

🦾 Real-Time Object Detection API (YOLOv8s Worldv2)

PAYG

MagicAPI

this is fast, lightweight, and accurate—spots many objects in real time with ease. great pick for retail, security, transport, or any workflow that needs quick detection.
