Get Started with the Image API

Image Analysis Endpoints

The Verity image analysis endpoints are:

Image URL Requirements

In the POST image/classification endpoint, you’ll specify the URL of an individual image for analysis. The URL specified in <IMAGE_URL> must meet the following requirements:

• Start with http:// or https://.

• Have a properly URL-encoded address.

• Any request parameter values must be properly URL-encoded.

Example Image Request

This example shows a request to analyze the following image URL:

https://media3.s-nbcnews.com/j/newscms/2020_18/2724881/190122-handguns-new-york-cs-1005a_ae30ba7e5164f948822ba8d42c3db791.fit-1240w.jpg

Step 1 – Submit a POST request via curl to /image/classification

Submit an analysis request specifying an individual image URL. 

curl -H 'x-api-key: <YOUR_API_KEY_HERE>' -H 'Content-Type: application/json' -X POST https://verity-api.gumgum.com/image/classification

Verity API returns a JSON response with  Content-Type: application/json; charset=UTF-8  showing showing a uuid for the request and current request status, for example: 

{
   "uuid": "c7bcbe04-ea77-4808-8e91-28d325d1b1fc",
   "acceptedAt": "2020-06-25T23:09:41.729Z"
}

For a list of supported status messages, refer to Application Status Codes.

Step 2 – Submit a GET request to /image/classification/{uuid}/status

Submit a GET request to /image/classification/{uuid}/status specifying the uuid returned in the previous step. Within a short period, once analysis of the image is complete, a status change occurs. For example:

curl -H 'x-api-key: <YOUR_API_KEY_HERE>' https://verity-api.gumgum.com/image/classification/c7bcbe04-ea77-4808-8e91-28d325d1b1fc/status

Verity API returns a JSON response with  Content-Type: application/json; charset=UTF-8  showing the request has the following status: 

{
   "uuid" : "c7bcbe04-ea77-4808-8e91-28d325d1b1fc",
   "status": "ANALYZING"
}

Step 3 – Submit a GET request to /image/classification/{uuid} 

Submit a GET request to /image/classification/{uuid} , specifying the uuid returned in the response during Step 1. Within a short period, once analysis of the image is complete, a status change occurs. For example:

curl -H 'x-api-key: <YOUR_API_KEY_HERE>' https://verity-api.gumgum.com/image/classification/123e4567-e89b-12d3-a456-426655440000

The JSON response details the complete brand safety, keyword, and categorization analysis data for the image.  See JSON Response for details about the fields included in the response.

{
  "uuid": "6998e629-ed07-4f0e-94a4-7a684238a313",
  "url": "https://media3.s-nbcnews.com/j/newscms/2020_18/2724881/190122-handguns-new-york-cs-1005a_ae30ba7e5164f948822ba8d42c3db791.fit-1240w.jpg",
  "data": {
    "keywords": [
      "fitness_and_exercise"
    ],
    "safe": false,
    "threats": [
      {
        "id": "GGT1",
        "category": "Violence and gore",
        "confidence": "VERY_HIGH"
      }
    ],
    "processedAt": "2020-09-29T22:34:10.143Z"
  }