Cloud API

Send an ask job

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

/ask allows you to submit a question you would like to be answered in context to a set of images. As an option you may also provide example images which give an idea of what should resolve to a 'yes' or a 'no' answer to your question. It responds with an in-progress job.

If the answer is true for the set of images, 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 /ask/{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

question
required		bodystring

The Yes/No question to be answered

Max Length: 256

examples
optional		bodyobject
yes
optional		array[string]

A list of example image URLs for the 'Yes' answer to the question

Min Items: 1, Max Items: 3

The image URL of the target image

Max Length: 512

no
optional		array[string]

A list of example image URLs for the 'No' answer to the question

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_garage_door_open_image"
    },
    {
      "url": "https://publicly.available.domain.net/image-002.jpg",
      "customId": "some_garage_door_closed_image"
    }
  ],
  "question": "Is my garage door open?",
  "examples": {
    "yes": [
      "https://publicly.available.domain.net/yes-image-001.jpg",
      "https://publicly.available.domain.net/yes-image-002.jpg",
      "https://publicly.available.domain.net/yes-image-003.jpg"
    ],
    "no": [
      "https://publicly.available.domain.net/no-image-001.jpg",
      "https://publicly.available.domain.net/no-image-002.jpg",
      "https://publicly.available.domain.net/no-image-003.jpg"
    ]
  },
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et"
}

Response Parameters

Ask 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

question
required		string

The Yes/No question to be answered

Max Length: 256

examples
optional		object
yes
optional		array[string]

A list of example image URLs for the 'Yes' answer to the question

Min Items: 1, Max Items: 3

The image URL of the target image

Max Length: 512

no
optional		array[string]

A list of example image URLs for the 'No' answer to the question

Min Items: 1, Max Items: 3

The image URL of the target image

Max Length: 512

jobResults
required		object
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)

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": {
    "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_garage_door_opened_image"
    }
  },
  "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_garage_door_opened_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_garage_door_closed_image",
      "status": "COMPLETED_SUCCESSFULLY"
    }
  ],
  "question": "Is my garage door open?",
  "examples": {
    "yes": [
      "https://publicly.available.domain.net/yes-image-001.jpg",
      "https://publicly.available.domain.net/yes-image-002.jpg",
      "https://publicly.available.domain.net/yes-image-003.jpg"
    ],
    "no": [
      "https://publicly.available.domain.net/no-image-001.jpg",
      "https://publicly.available.domain.net/no-image-002.jpg",
      "https://publicly.available.domain.net/no-image-003.jpg"
    ]
  },
  "createdAt": 1487648348000,
  "status": "COMPLETED_SUCCESSFULLY",
  "customId": "6c78df0a-67b6-4d5f-93cf-5820cfee501c",
  "feedId": "Camera_123456",
  "webhookUrl": "https://publicly.available.domain.net/90f8754aa4e287bbb2c07ec99ade0de72ddbd4b6Et"
}