Image Detection API Documentation
Overview
The Image detection API identifies objects in images and returns bounding boxes with confidence scores and labels.
Guide Prerequisites
- Marqo Cloud Account: Sign up at cloud.marqo.ai. (if you don't have an account, please reach out!)
- Python 3.7+ installed on your machine
- Image Detection API Key given to you by your Marqo representative. Please reach out to the team if you don't have one.
Base URL
https://image-detection.marqo-ep.ai
Authentication
All API requests require authentication using an API key passed in the request header:
x-api-key: <your-api-key>
Endpoints
Detect Objects
Detects objects in an image and returns bounding boxes with confidence scores and labels.
Endpoint: POST /detect
Headers:
- Content-Type: application/json
- x-api-key: <your-api-key>
Request Body:
{
"image": "<image_url_or_base64>"
}
Parameters:
- image
(string, required): Either a URL to an image or a base64-encoded image string
Supported Image Formats: - JPEG - WebP - PNG
Example Request:
curl -X POST 'https://image-detection.marqo-ep.ai/detect' \
--header 'Content-Type: application/json' \
--header 'x-api-key: your-api-key-here' \
--data '{
"image": "https://example.com/image.jpg"
}'
Example Response:
{
"items": [
{
"bounding_box": [
[0.1, 0.15], // Top-left corner (x, y)
[0.3, 0.4] // Bottom-right corner (x, y)
],
"score": 0.95,
"labels": ["bag", "handbag"]
},
{
"bounding_box": [
[0.2, 0.1],
[0.4, 0.3]
],
"score": 0.87,
"labels": ["top", "shirt"]
}
],
"original_image": {
"width": 800,
"height": 600
}
}
Response Fields:
items
(array): Array of detected objectsbounding_box
(array): Coordinates of the bounding box using top-left corner as origin (0,0)- First array:
[x1, y1]
- Top-left corner coordinates - Second array:
[x2, y2]
- Bottom-right corner coordinates
- First array:
score
(float): Confidence score between 0 and 1labels
(array): Array of category labels for the detected objectoriginal_image
(object): Original image dimensionswidth
(integer): Image width in pixelsheight
(integer): Image height in pixels
Error Responses
400 Bad Request
{
"error": "Missing 'image' field in request"
}
401 Unauthorized
{
"error": "Invalid or missing API key"
}
405 Method Not Allowed
{
"error": "Invalid request method"
}
Integration with Marqo Search
After detecting objects in an image, you can:
- Extract the bounding box coordinates from the response
- Crop the original image using the bounding box coordinates
- Convert the cropped image to base64
- Submit the cropped image to Marqo's image-to-image search endpoint for finding similar products