Object recognition
On this page
The Object recognition operation allows you to categorize and tag people, objects, and other content classes in your images. This operation uses AWS Rekognition machine learning for the analyses.
The feature is currently available on the REST API v0.7 or higher via add-ons API.
How it works
Object recognition works asynchronously through the REST API, unlike the image processing operations performed on the fly.
- Start a processing job via REST API. Send an input file UUID with necessary processing operations.
- Wait until the processing job status becomes
done
. - The result will be available in the JSON response in the
appdata
section of the processed file.
Example
Let's take this image as an example:
Once it is uploaded to a project, you can make an API call to run object recognition via Rekognition API:
curl -X POST
-H "Accept: application/vnd.uploadcare-v0.7+json" \
-H "Content-Type: application/json" \
-H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
-d "{\"target\": \"$UUID\"}"
"https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/"
bash
Get $YOUR_PUBLIC_KEY
and $YOUR_SECRET_KEY
from API keys.
You can track execution status using request_id
from previous request's
response:
curl -H "Accept: application/vnd.uploadcare-v0.7+json" \
-H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
"https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/status/?request_id=$REQUEST_ID"
bash
The result will be available in JSON response in appdata
.
Get image info
Acquiring info about detected objects through a
file info request to the API endpoint,
specifying the include
parameter.
The endpoint for requesting Object recognition info:
There are two methods for getting info on detected objects via GET requests, for multi-file and single-file cases:
GET /files/?include=appdata
html
or
GET /files/$UUID/?include=appdata
Where:
include
parameter points our API to includeappdata
, an object holding various application data.$UUID
identifies the unique image for which you are requesting info on detected objects.
Single-file request
curl -H "Accept: application/vnd.uploadcare-v0.7+json" \
-H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
"https://api.uploadcare.com/files/$UUID/?include=appdata"
bash
Multi-file request
curl -H "Accept: application/vnd.uploadcare-v0.7+json" \
-H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
"https://api.uploadcare.com/files/?include=appdata"
bash
Where:
- Note,
Accept
header points at the REST API v0.7 or higher. Uploadcare.Simple
stands for the auth-scheme that requires your Uploadcare project Public and Secret keys.- In a single-file example,
$UUID
identifies the image we get info for. - In a multi-file example, no
$UUID
is provided; you will receive detection info for all files in your project.
Single-file response
The JSON response for requesting a single-file that is properly authenticated looks like this:
{
"datetime_removed": null,
"datetime_stored": "2018-08-07T05:31:47.326146Z",
"datetime_uploaded": "2018-08-07T05:31:47.132454Z",
"is_image": true,
"is_ready": true,
"mime_type": "image/jpeg",
"original_file_url": "https://ucarecdn.com/af9b7f02-6cbe-45bd-9bb6-9c928bf8a72e/eberhardgrossgasteiger767950unsplash.jpg",
"original_filename": "eberhard-grossgasteiger-767950-unsplash.jpg",
"size": 2363253,
"url": "https://api.uploadcare.com/files/af9b7f02-6cbe-45bd-9bb6-9c928bf8a72e/",
"uuid": "af9b7f02-6cbe-45bd-9bb6-9c928bf8a72e",
"variations": null,
"content_info": {
"image": {
"dpi": [
72,
72
],
"width": 3648,
"format": "JPEG",
"height": 2432,
"sequence": false,
"color_mode": "RGB",
"orientation": null,
"geo_location": null,
"datetime_original": null
}
},
"metadata": {},
"appdata": {
"aws_rekognition_detect_labels": {
"data": {
"Labels": [
{
"Name": "Nature",
"Parents": [],
"Instances": [],
"Confidence": 99.34097290039062
},
{
"Name": "Outdoors",
"Parents": [],
"Instances": [],
"Confidence": 99.23014068603516
},
{
"Name": "Tree",
"Parents": [
{
"Name": "Plant"
}
],
"Instances": [],
"Confidence": 98.99191284179688
},
{
"Name": "Plant",
"Parents": [],
"Instances": [],
"Confidence": 98.99191284179688
},
{
"Name": "Fir",
"Parents": [
{
"Name": "Tree"
},
{
"Name": "Plant"
}
],
"Instances": [],
"Confidence": 98.6605224609375
},
{
"Name": "Building",
"Parents": [],
"Instances": [],
"Confidence": 97.45043182373047
},
{
"Name": "Housing",
"Parents": [
{
"Name": "Building"
}
],
"Instances": [],
"Confidence": 97.41302490234375
},
{
"Name": "Countryside",
"Parents": [
{
"Name": "Outdoors"
},
{
"Name": "Nature"
}
],
"Instances": [],
"Confidence": 92.5694580078125
},
{
"Name": "Shelter",
"Parents": [
{
"Name": "Building"
},
{
"Name": "Countryside"
},
{
"Name": "Outdoors"
},
{
"Name": "Nature"
}
],
"Instances": [],
"Confidence": 88.491455078125
},
{
"Name": "Water",
"Parents": [],
"Instances": [],
"Confidence": 87.63512420654297
}
],
"LabelModelVersion": "2.0"
},
"datetime_created": "2018-08-07T05:31:47.132454Z",
"datetime_updated": "2022-09-20T05:24:09.871132Z",
"version": "2016-06-27"
}
}
}
json
Limitations
- This operation is not available on the Free plan.
API integrations
You don't have to code most of the low-level API integrations. We have high-level libraries for all popular platforms:
Billing
- This feature is available on paid plans.
- Learn how we charge for this operation.