Cloud API

Send a match job

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

/match allows you to specify a set of targets you want to search for in a given list of images. It responds with an in-progress job.

If the target is found, the completed job results will include the chosen image.

The results can be acquired by either specifying a publicly accessible webhook URL, or querying with the job ID on the /match/{id} endpoint.

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

target
required		bodyobject
class
required		string

The target class you want to find in your images

customId
optional		string

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

Max Length: 64

images
required		array[string]

A list of target image URLs

Min Items: 1, Max Items: 3

The image URL of the target image

Max Length: 512

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"
    }
  ],
  "target": {
    "class": "person",
    "customId": "example_target_id",
    "images": [
      "https://publicly.available.domain.net/person-001.jpg",
      "https://publicly.available.domain.net/person-002.jpg",
      "https://publicly.available.domain.net/person-003.jpg"
    ]
  },
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et"
}

Response Parameters

Match 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		object
target
required		object
class
required		string

The class (target) found in the image

customId
optional		string

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

images
required		array[string]

A list of target image URLs that were passed in during the request)

Min Items: 1, Max Items: 3

URL of target image

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)

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

Response Sample

{
  "id": "5d689c71-e68f-46c3-ac71-4053806e71de",
  "jobResults": {
    "target": {
      "class": "person",
      "customId": "custom_target_id",
      "images": [
        "https://publicly.available.domain.net/person-001.jpg",
        "https://publicly.available.domain.net/person-002.jpg",
        "https://publicly.available.domain.net/person-003.jpg"
      ]
    },
    "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"
    },
    "hitl": true
  },
  "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",
      "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",
      "status": "COMPLETED_SUCCESSFULLY"
    }
  ],
  "createdAt": 1487648348000,
  "status": "COMPLETED_SUCCESSFULLY",
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et"
}