- 1.1 Video Endpoints
2 Example Video Request
- 2.1 Step 1 – Submit a POST video classification request
- 2.2 Step 2 – GET status of request
  - 2.2.1 If provided UUID is for an existing video
  - 2.2.2 If provided UUID is for a video not seen by Verity
- 2.3 Step 3 – Get response
  - 2.3.1 Video does not exist
  - 2.3.2 Video is still processing
  - 2.3.3 Video has been processed
    - 2.3.3.1 IAB
    - 2.3.3.2 Threats
    - 2.3.3.3 Sentiments
    - 2.3.3.4 Segments
- 2.4 Example Video JSON Response Body
- 2.5 More Information

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

https://gumgum.jira.com/wiki/spaces/VDC/pages/1780187178

Verity Documentation Center

Get Started - Video API

Video Endpoints

Example Video Request

Step 1 – Submit a POST video classification request

Step 2 – GET status of request

If provided UUID is for an existing video

If provided UUID is for a video not seen by Verity

Step 3 – Get response

Video does not exist

Video is still processing

Video has been processed

IAB

Threats

Sentiments

Segments

Example Video JSON Response Body

More Information