Skip to main content
POST
/
api
/
yolo
/
detect
YOLO Object Detection
curl --request POST \
  --url https://api.example.com/api/yolo/detect \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "detection": {
    "name": "<string>",
    "confidence": 123,
    "bbox": [
      {}
    ],
    "avg_color_rgb": [
      {}
    ]
  },
  "annotated_image_url": "<string>"
}

​
Endpoint

POST /api/yolo/detect
Detects objects in an uploaded image using a YOLO (You Only Look Once) deep learning model. Returns the highest confidence detection along with an annotated image showing all detected objects with bounding boxes.

​
Authentication

This endpoint requires authentication via Bearer token in the Authorization header. 
Authorization: Bearer <your_access_token>

​
Request

​
file
file
required
The image file to analyze. Supports common image formats (JPG, PNG, etc.)Must be sent as multipart/form-data.
File Format Requirements:
  • Supported formats: JPG, JPEG, PNG, BMP
  • Image must be readable by OpenCV
  • Recommended: Clear, well-lit images for better detection accuracy
  • Model confidence threshold: 0.25

​
Response

​
detection
object
The highest confidence detection from all detected objects
​
name
string
The class name of the detected object
​
confidence
number
Confidence score between 0 and 1
​
bbox
array
Bounding box coordinates as [x1, y1, x2, y2] where (x1, y1) is top-left and (x2, y2) is bottom-right
​
avg_color_rgb
array
Average RGB color of the detected object region as [r, g, b] values (0-255)
​
annotated_image_url
string
Cloudinary URL of the annotated image with bounding boxes and labels drawn on it

​
Success Response (200)

{
  "detection": {
    "name": "apple",
    "confidence": 0.92,
    "bbox": [150, 200, 350, 450],
    "avg_color_rgb": [195, 45, 38]
  },
  "annotated_image_url": "https://res.cloudinary.com/your-cloud/image/upload/v1234567890/annotated_image.jpg"
}

​
No Detections Response (200)

{
  "detections": [],
  "message": "No objects detected",
  "annotated_image_url": null
}

​
Error Response (500)

{
  "detail": "Could not load image at uploads/image.jpg"
}

​
Code Examples

curl -X POST https://api.expireeye.com/api/yolo/detect \
  -H "Authorization: Bearer your_access_token" \
  -F "file=@/path/to/image.jpg"

​
Integration Details

​
YOLO Model

The endpoint uses the YOLO (You Only Look Once) model loaded from best.pt with the following configuration:
  • Confidence Threshold: 0.25 (detections below this confidence are filtered out)
  • Model: Custom-trained YOLO model optimized for product detection
  • Framework: Ultralytics YOLO implementation

​
Cloudinary Integration

Annotated images are automatically uploaded to Cloudinary with the following configuration:
  • Environment Variables Required:
    • CLOUDINARY_CLOUD_NAME: Your Cloudinary cloud name
    • CLOUDINARY_API_KEY: Your Cloudinary API key
    • CLOUDINARY_API_SECRET: Your Cloudinary API secret
  • Upload Settings: Secure URLs enabled by default

​
Detection Process

  1. Image is uploaded and saved temporarily in the uploads/ folder
  2. YOLO model processes the image and detects objects
  3. For each detection:
    • Bounding box coordinates are extracted
    • Confidence score is calculated
    • Average RGB color of the detected region is computed
    • Bounding boxes and labels are drawn on the image
  4. The detection with highest confidence is selected as the primary result
  5. Annotated image is uploaded to Cloudinary
  6. Results are returned with the Cloudinary URL

​
Image Annotations

The annotated image includes:
  • Green bounding boxes around detected objects
  • Labels showing class name and confidence score
  • Format: {class_name} {confidence:.2f}

Build docs developers (and LLMs) love

Get started for freeTalk to us