Get Started - Image API

1 Supported Image Formats
2 Image Analysis Endpoints
3 Example Image Request
4 Example Image JSON Response Body
5 More Information

Supported Image Formats

BMP	IM	PCX	SPIDER
EPS	JPEG	PNG	TIFF
ICNS	JPEG 2000	PPM	WebP
ICO	MSP	SGI	XBM

Image Analysis Endpoints

The GumGum Contextual image analysis endpoints are:

HTTP Request	POST

HTTP Request	POST
Authorization Header	`X-api-key: value`
GumGum Contextual Endpoint	`https://verity-api.gumgum.com/image/classification`
Body	`{ "url":"https://media3.s-nbcnews.com/j/newscms/2020_18/2724881/190122-handguns-new-york-cs-1005a_ae30ba7e5164f948822ba8d42c3db791.fit-1240w.jpg", "callbackUrl": "URL value" }`

HTTP Request	GET

HTTP Request	GET
Authorization Header	`X-api-key: value`
GumGum Contextual Endpoint	`https://verity-api.gumgum.com/image/classification/{uuid}`

HTTP Request	GET

HTTP Request	GET
Authorization Header	`X-api-key: value`
GumGum Contextual Endpoint	`https://verity-api.gumgum.com/image/classification/{uuid}/status`

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

{
"url":"https://media3.s-nbcnews.com/j/newscms/2020_18/2724881/190122-handguns-new-york-cs-1005a_ae30ba7e5164f948822ba8d42c3db791.fit-1240w.jpg",
"callbackUrl": "URL value"
}

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.

'Request Fields' within Body:

Field	Requirement	Description

Field	Requirement	Description
url	required	Video url for the asset to process.
callbackUrl	optional	If provided, GumGum Contextual will push Video Classification results to this endpoint after the video has processed successfully.

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

Submit an analysis request. Specify an individual image URL.

 curl -X POST "https://verity-api.gumgum.com/image/classification" -H "accept: **" -H "x-api-key: abd" -H "Content-Type: application/json;charset=UTF-8" -d "{"url":"https://media-cldnry.s-nbcnews.com/image/upload/t_fit-1240w,f_auto,q_auto:best/newscms/2020_18/2724881/190122-handguns-new-york-cs-1005a.jpg"}"

Response:

Field	Description

Field	Description
uuid	Unique identifier generated by GumGum Contextual
url	Image url provided by client
acceptedAt	ISO-8601 formatted timestamp represented when the image was first accepted by GumGum Contextual for processing

GumGum Contextual 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",
  "url": "https://media3.s-nbcnews.com/j/newscms/2020_18/2724881/190122-handguns-new-york-cs-1005a_ae30ba7e5164f948822ba8d42c3db791.fit-1240w.jpg",
  "acceptedAt": "2021-06-10T00:05:22.508Z"
}

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

Once the image classification request was sent, if a callback url was provided results will be sent to the webhook endpoint.

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

GumGum Contextual 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 in step 1 to get the results. This endpoint will not return status and will only return results once the status changes to PROCESSED, otherwise it will return '404 - Not Found'. The JSON image classification results are returned in the data payload. For example:

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

Example Image JSON Response Body

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

{
  "uuid": "c7bcbe04-ea77-4808-8e91-28d325d1b1fc",
  "url": "https://media3.s-nbcnews.com/j/newscms/2020_18/2724881/190122-handguns-new-york-cs-1005a_ae30ba7e5164f948822ba8d42c3db791.fit-1240w.jpg",
  "data": {
    "processedAt": "2021-05-28T00:28:36.472Z",
    "expiresAt": "2021-06-11T00:28:36.472Z",
    "keywords": [],
    "safe": false,
    "threats": [
      {
        "id": "GGT1",
        "category": "Violence and gore",
        "confidence": "VERY_HIGH",
        "risk": "HIGH"
      }
    ]
  }
}

Note: Results are not returned for the ‘Keyword’ field.

More Information

Image API Reference