Cloud API

Send a detect job

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

/detect the presence of classes in your list of images. You specify an array of classes you'd like to find in your set of images.

In general, we try to process images only via artificial intelligence. However, there are times where edge cases can cause the AI to get it wrong. In these situations, if enabled, we employ human intelligence to additionally verify the AI result.

Verification is automatically enabled by default (verify=AUTO) on every class that's specified in your job. Although human verification incurs an additional cost, we highly recommend it as it greatly increases accuracy. You can disable verification by setting verify=NEVER as part of the request payload.

Similar to all other asynchronous endpoints /detect also responds with an IN_PROGRESS status and a jobId. The results can be acquired by either specifying a webhookUrl, or querying with the jobId on GET /detect/{id}.

Exclusion Zones

/detect also supports the ability to exclude regions in an image during analysis (see exclusionZones). Exclusion zones are regions of an image that you don't want AI to perform analysis on. Here is an example request with multiple exclusion zones on the person class but not on the car class.

{
  "images": [...],
  "classes": [
    {
      "class": "car",
      "verify": "ALWAYS"
    },
    {
      "class": "person",
      "verify": "NEVER",
      "exclusionZones": {
        "type": "GRID",
        "size": 16,
        "zones": [
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1],
          [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1]
        ]
      }
    }
  ]
}

Exclusion zones cells in a grid. Cells with 1 will form an exclusion zone. In example above, we have an exclusion zone on person classification jobs. It represents a 16x16 grid where half of the pixels in each image passed into the API are excluded from analysis.

NOTE: Exclusion zones are only available to /detect. There are no immediate plans to add this feature to other endpoints right now.

Request Parameters

NameInDescription
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

classes
required		body
array[object]

Min Items: 1

class
required		string

A class (object) you want to search for

verify
optional		string

Whether or not you want HITL verification

Default: AUTO

Possible values: NEVER, AUTO, ALWAYS

exclusionZones
optional		object

A list of zones to exclude during analysis

type
required		string

The type of exclusion zone

Default: GRID

Possible values: GRID

size
optional		number

Maximum grid size (e.g. size=32 means 32x32), this is required if type is GRID

Default: 64, Format: int32

Possible values: 32, 64, 128

zones
required		array[array]

A list of lists where each nested list represents a zone of the image to exclude

webhookUrl
optional		bodystring

Publicly accessible POST endpoint for receiving job status updates

Max Length: 512

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",
      "customId": "some_person_filled_image"
    },
    {
      "url": "https://publicly.available.domain.net/image-002.jpg",
      "customId": "some_car_filled_image"
    }
  ],
  "classes": [
    {
      "class": "person"
    },
    {
      "class": "pet",
      "verify": "ALWAYS"
    }
  ],
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et"
}

Response Parameters

Detect job request was successfully submitted

id
required		string
createdAt
required		integer

UNIX timestamp for when the job was created

Format: int64

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

jobResults
required		array[object]
class
required		string

A class you want to search for

image
optional		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)

confidence
required		number

The confidence value for the class

hitl
required		boolean

Whether human-in-the-loop verification was used for this class

imageResults
required		array[object]
id
required		string
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)

status
required		string

The processing status for an image

Possible values: COMPLETED_SUCCESSFULLY, IN_PROGRESS, UNKNOWN_ERROR, JOB_ERROR, IMAGE_DOWNLOAD_ERROR, INVALID_IMAGE_FORMAT_ERROR, SPIDERWEBS_ERROR, DETECTION_ENGINE_ERROR, MODEL_SERVICE_ERROR, MALFORMED_MESSAGE_ERROR

objects
required		array[object]
class
required		string

The class found

confidence
required		number

The confidence for the class

verdict
required		boolean

Whether we're certain if this class exists

Response Sample

{
  "id": "5d689c71-e68f-46c3-ac71-4053806e71de",
  "jobResults": [
    {
      "class": "person",
      "image": {
        "id": "52547074-a622-11e6-8f61-63f37dc33285",
        "url": "https://publicly.available.domain.net/image-001.jpg",
        "proxyUrl": "https://api.quickpix.io/images/c7e9a2ca-c2ee-4290-90b4-04fe3df35be0",
        "customId": "some_person_filled_image",
        "confidence": 0.9971387386
      },
      "hitl": true
    },
    {
      "class": "car",
      "image": {
        "id": "52547074-a622-11e6-8f61-63f37dc33286",
        "url": "https://publicly.available.domain.net/image-002.jpg",
        "proxyUrl": "https://api.quickpix.io/images/c7e9a2ca-c2ee-4290-90b4-04fe3df35be1",
        "customId": "some_car_filled_image",
        "confidence": 0.9987652302
      },
      "hitl": false
    }
  ],
  "imageResults": [
    {
      "id": "52547074-a622-11e6-8f61-63f37dc33285",
      "url": "https://publicly.available.domain.net/image-001.jpg",
      "proxyUrl": "https://api.quickpix.io/images/c7e9a2ca-c2ee-4290-90b4-04fe3df35be0",
      "customId": "some_person_filled_image",
      "objects": [
        {
          "class": "person",
          "confidence": 0.9971387386,
          "verdict": true
        }
      ],
      "status": "COMPLETED_SUCCESSFULLY"
    },
    {
      "id": "52547074-a622-11e6-8f61-63f37dc33286",
      "url": "https://publicly.available.domain.net/image-002.jpg",
      "proxyUrl": "https://api.quickpix.io/images/c7e9a2ca-c2ee-4290-90b4-04fe3df35be1",
      "customId": "some_car_filled_image",
      "objects": [
        {
          "class": "car",
          "confidence": 0.9987652302,
          "verdict": true
        }
      ],
      "status": "COMPLETED_SUCCESSFULLY"
    }
  ],
  "createdAt": 1487648348000,
  "status": "COMPLETED_SUCCESSFULLY",
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et"
}