Cloud API

Send a recognition job request

POST https://api.imageintelligence.com/v2/recognize

/recognize allows you to perform recognition on any arbitrary image. Similar to other endpoints such as /detect, you can also specify an array of image objects.

When you first start using /recognize, there be be no recognition results because you won't have any identities to recognize against. However, you will still receive detection bounding boxes objects found prior to recognition. See /identities on how you can create identities with detected objects.

Unlike other endpoints such as /detect, /recognize introduces a concept we call namespace. Namespaces are ways to segment identities, groups and images. Imagine you have multiple users with each having varied conditions such as lighting and camera placement. You could isolate each user into different namespaces to avoid conflicts and improve accuracy.

Request Parameters

NameInDescription
namespace
required		pathstring
images
required		body
array[object]

A list of images. Each object should contain either the image URL or blob of image bytes

Min Items: 1, Max Items: 64

url
optional		string

URL of the image

Max Length: 512

blob
optional		string

Base64-encoded image bytes

customId
optional		string

An arbitrary client specific resource identifier to reference this image (usually UUID)

Max Length: 64

webhookUrl
optional		bodystring

Publicly accessible POST endpoint for receiving job status updates

Max Length: 2048

customId
optional		bodystring

An arbitrary client specific resource identifier to reference this job (usually UUID)

Max Length: 64

feedId
optional		bodystring

User specified ID to reference the source of the images within this job

Max Length: 64

Request Sample

{
  "images": [
    {
      "url": "https://publicly.available.domain.net/image-001.jpg"
    },
    {
      "url": "https://publicly.available.domain.net/image-002.jpg"
    }
  ],
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et"
}

Response Parameters

Recognition job request was successfully submitted

id
required		string
status
required		string

The status for a job

Possible values: COMPLETED_SUCCESSFULLY, COMPLETED_PARTIAL_ERROR, COMPLETED_ALL_ERROR, IN_PROGRESS

customId
optional		string

An arbitrary client specific resource identifier to reference this job (usually UUID)

feedId
optional		string

User specified ID to reference the source of the images within this job

webhookUrl
optional		string

Publicly accessible POST endpoint for receiving job status updates

createdAt
required		integer

UNIX timestamp for when the job was created

Format: int64

images
required		array[object]
id
required		string

ID of the image

url
required		string

URL of the image

proxyUrl
optional		string

Proxy URL of the image

customId
optional		string

An arbitrary client specific resource identifier to reference this image (usually UUID)

objects
required		array[object]
identityId
optional		string
confidence
required		number

Format: float

boundingBox
required		object
xMin
required		number

Format: int32

yMin
required		number

Format: int32

xMax
required		number

Format: int32

yMax
required		number

Format: int32

createdAt
required		integer

UNIX timestamp for when the face was created

Format: int64

Response Sample

{
  "id": "5d689c71-e68f-46c3-ac71-4053806e71de",
  "createdAt": 1487648348000,
  "status": "COMPLETED_SUCCESSFULLY",
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et",
  "images": [
    {
      "id": "3534852e-9d44-48d1-b42a-9d14f3652032",
      "url": "https://images.example.com/5673605764397232.jpg",
      "proxyUrl": "https://proxy.images.example.com/5673605764397232.jpg",
      "customId": "a7e0bc2d-3226-46da-b242-9bb40666b14a",
      "objects": [
        {
          "confidence": 0.410791,
          "boundingBox": {
            "xMin": 0.23873,
            "yMin": 0.23873,
            "xMax": 0.75087,
            "yMax": 0.96537
          },
          "createdAt": 1534481491910
        },
        {
          "identityId": "81e45841-4996-433d-9138-3383214176d1",
          "confidence": 0.05628731,
          "boundingBox": {
            "xMin": 0.23873,
            "yMin": 0.23873,
            "xMax": 0.75087,
            "yMax": 0.96537
          },
          "createdAt": 1534481491901
        }
      ]
    }
  ]
}