> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Object recognition

> Uploadcare provides object recognition capabilities that are useful when categorizing content or implementing image tagging.

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](https://uploadcare.com/docs/api/rest/add-ons/aws-rekognition-execute).

## How it works

Object recognition works asynchronously through the REST API, unlike the [image processing operations](/docs/transformations/image/#image-transformations-list) performed on the fly.

1. Start a processing job via REST API. Send an input file UUID with necessary
   processing operations.
2. Wait until the processing job status becomes `done`.
3. 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:

[](https://ucarecdn.com/af9b7f02-6cbe-45bd-9bb6-9c928bf8a72e/-/preview/)

Once it is uploaded to a [project](/docs/start/settings/), you can make an API call
to run object recognition via [Rekognition API](https://uploadcare.com/docs/api/rest/add-ons/aws-rekognition-execute):

```bash
curl -L -X POST 'https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/' \
     -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\"}"
```

Get `$YOUR_PUBLIC_KEY` and `$YOUR_SECRET_KEY` from [API keys](https://app.uploadcare.com/projects/-/api-keys/).

### Webhook event

To get the job result, you need to enable `file.info_updated` in the
[Webhook section](/docs/webhooks/#webhook-notifications) of the dashboard.

After completing the processing job, the webhook will be sent to
the endpoint you specified in the webhook settings.

File information in response:

```json
    "initiator": {
        "type": "addon",
        "detail": {
            "addon_name": "aws_rekognition_detect_labels",
            "request_id": ":request_id",
        }
    },
    "hook": {
        ...
        "event": "file.info_updated",
        "is_active": true,
        "version": "0.7",
    },
        "uuid": ":UUID",
        "is_image": true,
        "is_ready": true,
        "metadata": {},
        "appdata": {
            "aws_rekognition_detect_labels": {
                "data": {
                    "LabelModelVersion": "3.0",
                    "Labels": [{
                        "Confidence": 99.99856567382812,
                        "Instances": [],
                        "Name": "Food",
                        "Parents": []
                    }, {
                        "Confidence": 99.99856567382812,
                        "Instances": [],
                        "Name": "Fruit",
                        "Parents": [{
                            "Name": "Food"
                        }, {
                            "Name": "Plant"
                        }, {
                            "Name": "Produce"
                        }]
                    }, {
                        "Confidence": 99.99856567382812,
                        "Instances": [],
                        "Name": "Plant",
                        "Parents": []
                    }, {
                        "Confidence": 99.99856567382812,
                        "Instances": [],
                        "Name": "Produce",
                        "Parents": [{
                            "Name": "Food"
                        }]
                    }, {
                        "Confidence": 99.99794006347656,
                        "Instances": [{
                            "BoundingBox": {
                                "Height": 0.7499178051948547,
                                "Left": 0.5399686098098755,
                                "Top": 0.11977619677782059,
                                "Width": 0.22739684581756592
                            },
                            "Confidence": 98.84937286376953
                        }],
                        "Name": "Pineapple",
                        "Parents": [{
                            "Name": "Food"
                        }, {
                            "Name": "Fruit"
                        }, {
                            "Name": "Plant"
                        }, {
                            "Name": "Produce"
                        }]
                    }]
                },
                "version": "2016-06-27",
                "datetime_created": "2023-11-08T12:15:22.965Z",
                "datetime_updated": "2023-11-08T12:15:22.965Z"
            },
        }
```

### Check the execution status

If your application does not have a backend or uses a mobile version,
you can submit the request yourself.

You can track execution status using `request_id` from object recognition
request's response:

```bash
curl -L "https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/status/?request_id=$REQUEST_ID" \
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY"
```

The result will be available in [JSON response](#json) in `appdata`.

### Get image info

Acquiring info about detected objects through a [file info](https://uploadcare.com/docs/api/rest/file/info) request to the API endpoint, specifying the
`include` parameter.

The endpoint for requesting Object recognition info:

```html
https://api.uploadcare.com/files/
```

There are two methods for getting info on detected objects via GET requests, for
multi-file and single-file cases:

```html
GET /files/?include=appdata
```

or

```
GET /files/$UUID/?include=appdata
```

Where:

* `include` parameter points our API to include `appdata`, an object holding
  various application data.
* `$UUID` identifies the unique image for which you are requesting info on
  detected objects.

### Single-file request

```bash
curl -L "https://api.uploadcare.com/files/$UUID/?include=appdata" \
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY"
```

### Multi-file request

```bash
curl -L "https://api.uploadcare.com/files/?include=appdata" \
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY"
```

Where:

* Note, `Accept` header points at the REST API v0.7 or higher.
* `Uploadcare.Simple` stands for the [auth-scheme](https://uploadcare.com/docs/api/rest/#authentication) that
  requires your Uploadcare project Public and Secret [keys](/docs/start/settings/#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 \[#json]

The JSON response for requesting a single-file that is properly authenticated
looks like this:

```json
{
  "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"
    }
  }
}
```

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

* [JavaScript](/docs/integrations/javascript/)
* [PHP](/docs/integrations/php/)
* [Python & Django](/docs/integrations/python/)
* [Ruby](/docs/integrations/ruby/)
* [Rails](/docs/integrations/rails/)
* [Golang](/docs/integrations/golang/)
* [Rust](/docs/integrations/rust/)
* [Swift](/docs/integrations/swift/)
* [Android](/docs/integrations/android/)

## Billing

* This feature is available on [paid plans](https://uploadcare.com/pricing/).
* Learn how we [charge](/docs/billing/) for this operation.