Get Started - Video API

 

Video Endpoints

The Verity video analysis endpoints are:

POST /video/classification

Verity API processes HTTP POST requests to initiate a new video analysis.

GET /video/classification/{uuid}

Verity API processes HTTP GET requests to return processed results.

GET /video/classification/{uuid}/status

Verity API processes HTTP GET requests to return the status of the video analysis.

Example Video Request

This example walks through analyzing an english language video at the URL:

https://www.youtube.com/watch?v=lGOofzZOyl8

Step 1 – Submit a POST video classification request  

To start the video analysis, submit a POST request via curl to /video/classification. Optionally, include the language code parameter:

curl -H 'x-api-key: <YOUR_API_KEY_HERE>' -X POST -d '{"url":"'I'm not a cat': lawyer gets stuck on Zoom kitten filter during court case "languageCode": "en"}'  https://verity-api.gumgum.com/video/classification

Note: The url specified in the body 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 provided in body:

Field

Requirement

Description

Field

Requirement

Description

url

required

Video url for the asset to process

description

optional

Video description provided by client

title

optional

Video title provided by client

languageCode

optional

Video language. If the field is not provided, Verity will attempt to infer the language by analyzing the content of the video.

partnerVideoId

optional

Unique Video identifier provided by client.

publisherId

optional

Unique identifier for the publisher of the video.

callbackUrl

optional

If provided, Verity will push Video Classification results to this endpoint after the video has processed successfully.

Example:

curl --location 'https://verity-api.gumgum.com/video/classification' \
--header 'x-api-key: {api_key}' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://www.youtube.com/watch?v=lGOofzZOyl8%22
}'

Response:

Field

Description

Field

Description

uuid

Unique identifier generated by Verity

url

Video url provided by client

acceptedAt

ISO-8601 formatted timestamp represented when the video was first accepted by Verity for processing

 

Valid HTTP status codes:

Status Code

Description

Status Code

Description

202

Video was accepted by Verity for classification

500

Internal Server Error. Please contact customer support.

 

Example:

{ "uuid": "3abddc97-5186-511b-b343-a9aee316b698", "url": "https://www.youtube.com/watch?v=lGOofzZOyl8", "acceptedAt": "2023-03-07T17:26:05.694Z" }

Step 2 – GET status of request

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

 

Request fields provided as path values:

Field

Requirement

Description

Field

Requirement

Description

uuid

required

Unique identifier generated by Verity.

Example:

curl --location 'https://verity-api.gumgum.com/video/classification/3abddc97-5186-511b-b343-a9aee316b698' \

--header ‘{api_key}’

 

Response:

 

Possible status values

Status Value

Description

Status Value

Description

uuid

Unique identifier for video generated by Verity

url

Video url provided by client

status

DOWNLOADING | ANALYZING | PROCESSED

 

Possible http status codes

Status Code

Description

Status Code

Description

200

Video was successfully found.

404

The provided UUID was not associated with a Video seen by Verity

500

Internal Error. Please reach out to customer support.

 

Examples:

If provided UUID is for an existing video

{ "uuid": "3abddc97-5186-511b-b343-a9aee316b698", "url": "https://www.youtube.com/watch?v=lGOofzZOyl8", "status": "DOWNLOADING" }

 

If provided UUID is for a video not seen by Verity

{ "errorMessage": "3abddc97-5186-511b-b343-a9aee31b698 does not exist." }

 

 

Step 3 – Get response

Submit a GET request to /video/classification/{uuid}, specifying the uuid returned in the response in step 1. Once the status changes to PROCESSED, the JSON video classification results are returned in the data payload.

Request fields provided as path values

Field

Type

Description

Field

Type

Description

uuid

request

Unique identifier generated by Verity

Example:

curl --location
'https://verity-api.gumgum.com/video/classification/3abddc97-5186-511b-b343-a9aee316b698' \
--header 'x-api-key: {api_key}'

 

Response:

HTTP Status Codes

Status Code

Description

Status Code

Description

200

Video classification has been processed successfully. 

404

Returned if the provided video uuid is for a video that does not exist or the video is still processing.

500

Internal Server Error. Please contact customer support.

 

Examples:

Video does not exist

 

Video is still processing

 

Video has been processed

Field

Type

Description

Field

Type

Description

uuid

string

Unique identifier generated by Verity

uril

string

Video url provided by client

data

object

Encapsulates Verity’s classification response

 

Data

Field

Type

Returned?

Description

Field

Type

Returned?

Description

processedAt

string

 

When the classification was processed using ISO-8601 format

expiresAt

string

 

When the classification will expire using ISO-8601 format. This is currently configured for one year.

languageCode

string

 

Language provided by client or detected by Verity

iab

object

optional

Encapsulates IAB results produced by Verity. This value can be null.

keywords

array

 

Keywords produced by Verity. Currently configured to return top 15 keywords.

safe

boolean

 

Safety value produced by Verity.

threats

array

 

Threats produced by Verity

sentiments

array

 

Sentiment values produced by Verity.

segments

array

optional

Segments that have been assigned to the video asset processed by Verity.

 

IAB

Field

Type

Description

Field

Type

Description

v2

array

IAB v2 results produced by Verity

v3

array

IAB v3 results produced by Verity.

 

v2

Field

Type

Returned?

Description

Field

Type

Returned?

Description

id

string

 

IAB taxonomy v2 id

category

string

 

Human readable IAB category

score

number

 

Score produced by Verity

parent

object

optional

If an IAB category produced by Verity has a parent category. For example, College Sports has the parent category Sports

 

 

v3

Field

Type

Returned?

Description

Field

Type

Returned?

Description

id

string

 

IAB taxonomy v3 id

category

string

 

Human readable IAB category

score

number

 

Score produced by Verity

parent

object

optional

If an IAB category produced by Verity has a parent category. For example, College Sports has the parent category Sports

 

 

Parent 

Field

Type

Returned?

Description

Field

Type

Returned?

Description

id

string

 

IAB taxonomy v2 id

category

string

 

Human readable IAB category

parent

object

optional

If the IAB category has a root category.

 

Threats

Field

Type

Description

Field

Type

Description

id

string

GumGum threat taxonomy id. Valid values are: GGT1, GGT2, GGT3, GGT4, GGT5, GGT6, GGT7, GGT8, GGT9

category

string

Human readable name

confidence

string

This field has been deprecated and we recommend using RISK. Valid values are: VERY_LOW, LOW, MODERATE, HIGH, VERY_HIGH

risk

string

GumGum risk of threat. Valid values are: LOW, MEDIUM, HIGH

 

Sentiments

Field

Type

Description

Field

Type

Description

sentiment

string

Sentiment value produced by Verity. Currently supports: neutral, positive, negative

score

number

GumGum score associated with sentiment.

 

Segments

Field

Type

Description

Field

Type

Description

id

string

Unique identifier for segment

name

string

Client provided name for segment

 

Example Video JSON Response Body

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

 

More Information

 


The contents of these documents and any attachments contain GumGum, Inc. confidential information and are legally protected from disclosure.