SKU Detection Predict API

SKU classification services powered by advanced machine learning models

The SKU Detection API provides secure access to SKU classification services powered by advanced machine learning models. This API acts as a proxy to GPU-accelerated inference endpoints, offering reliable image classification for retail product recognition.

🎯

Product Detection

Detect multiple products in retail shelf images using YOLO

🏷️

SKU Classification

Identify specific SKU/product codes with high accuracy

🧠

AI-Powered

DINOv2 + CLIP embeddings for robust recognition

⚡

GPU Accelerated

Fast inference with RunPod GPU infrastructure

Authentication

All API requests require authentication using an API key passed in the X-API-Key header.

Header

X-API-Key: your-api-key-here

🔑 Getting an API Key

Contact the development team to obtain your API key for production use.

Base URL

https://sku-classification-router.fly.dev

Predict Endpoint

POST /api/v1/predict

Submit an image for SKU detection and classification. The API will detect products in the image and classify each detected product to its corresponding SKU.

Request Body

Parameter	Type	Description
`image` Required	string	Base64-encoded image data (JPEG, PNG, or WebP)
`category` Required	string	Product category (e.g., "DRINKS", "CHIPS", "LIQUID_HAND_SOAP")
`brand` Required	string	Brand name (e.g., "JORDINA", "HIGEEN")
`sku_conf` Optional	float	SKU confidence threshold (0.0-1.0). Default: 0.5
`det_conf` Optional	float	Detection confidence threshold (0.0-1.0). Default: 0.25
`show_unknown` Optional	boolean	Include unknown/unclassified detections. Default: false

Response

Success Response (200)

JSON Response

{
  "predictions": [
    {
      "sku_name": "JORDINA_APPLE_500ML",
      "sku_confidence": 0.94,
      "detection_confidence": 0.89,
      "bounding_box": [120, 45, 280, 320]
    },
    {
      "sku_name": "JORDINA_ORANGE_500ML",
      "sku_confidence": 0.91,
      "detection_confidence": 0.87,
      "bounding_box": [300, 50, 460, 315]
    }
  ],
  "processing_time_seconds": 1.24
}

Response Fields

Field	Type	Description
`predictions`	array	Array of detected and classified products
`predictions[].sku_name`	string	Classified SKU identifier
`predictions[].sku_confidence`	float	Classification confidence score (0.0-1.0)
`predictions[].detection_confidence`	float	YOLO detection confidence score
`predictions[].bounding_box`	array	[x1, y1, x2, y2] coordinates
`processing_time_seconds`	float	Total processing time in seconds

cURL Example

bash

# Base64 encode your image
IMAGE_BASE64=$(base64 -i product_image.jpg | tr -d '\n')

# Make the API request
curl -X POST 'https://sku-classification-router.fly.dev/api/v1/predict' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key-here' \
  -d "{
    \"image\": \"$IMAGE_BASE64\",
    \"category\": \"DRINKS\",
    \"brand\": \"JORDINA\",
    \"sku_conf\": 0.5,
    \"det_conf\": 0.25,
    \"show_unknown\": false
  }"

Python Example

python

import requests
import base64

API_URL = "https://sku-classification-router.fly.dev/api/v1/predict"
API_KEY = "your-api-key-here"

# Read and encode image
with open("product_image.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

# Prepare request
headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
}

payload = {
    "image": image_base64,
    "category": "DRINKS",
    "brand": "JORDINA",
    "sku_conf": 0.5,
    "det_conf": 0.25,
    "show_unknown": False
}

# Make request
response = requests.post(API_URL, json=payload, headers=headers, timeout=60)
result = response.json()

print(f"Found {len(result['predictions'])} products")
for pred in result["predictions"]:
    print(f"  - {pred['sku_name']} ({pred['sku_confidence']:.1%})")

JavaScript Example

javascript

const API_URL = "https://sku-classification-router.fly.dev/api/v1/predict";
const API_KEY = "your-api-key-here";

async function classifySKU(imageFile) {
  // Convert file to base64
  const base64 = await new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result.split(",")[1]);
    reader.onerror = reject;
    reader.readAsDataURL(imageFile);
  });
  
  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify({
      image: base64,
      category: "DRINKS",
      brand: "JORDINA",
      sku_conf: 0.5,
      det_conf: 0.25,
      show_unknown: false
    })
  });
  
  return await response.json();
}

// Usage with file input
document.getElementById("imageInput").addEventListener("change", async (e) => {
  const result = await classifySKU(e.target.files[0]);
  console.log(result);
});

Error Codes

Status	Error	Description
400	Bad Request	Invalid request body or missing required parameters
401	Unauthorized	Missing or invalid API key
503	Service Unavailable	GPU backend unavailable (cold start)
504	Gateway Timeout	Request timed out (60s limit)

⚠️ Cold Start Handling

If you receive a 503 error, the GPU may be warming up. Retry the request after 30-60 seconds.

Rate Limits

Request Timeout

60 seconds

Max Image Size

5 MB

Processing Time

1-5 seconds

Supported Formats

JPEG, PNG, WebP

💡 Performance Tips

Resize images to ~1024px max dimension before encoding
Use JPEG format for smaller payload sizes
Implement retry logic with exponential backoff

Changelog

v1.0.0 February 2026

• Initial release
• POST /api/v1/predict endpoint
• Support for DRINKS, CHIPS, LIQUID_HAND_SOAP categories