Table of Contents

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:

Code Block

curl

-H

'x-api-key:

<YOUR_API_KEY_HERE>'

-X

POST

-d

'{"url":"

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

'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
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.

Verity API returns a JSON response with

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; charset=UTF-8 showing the request has the following status: ' \
--data '{
"url": "https://www.youtube.com/watch?v=lGOofzZOyl8%22
}'

Response:

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
202	Video was accepted by Verity for classification
500	Internal Server Error. Please contact customer support.

Example:

Code Block

language	json

{
 
"dataAvailable": false,   "statusuuid": "INITIATED3abddc97-5186-511b-b343-a9aee316b698",
    "url": "https://www.youtube.com/watch?v=lGOofzZOyl8",
    "uuidacceptedAt": "244330772023-1733-44f4-930c-4a2ce4f18173"
}

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

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. For example:

Code Block

language	js

curl -H 'x-api-key: <YOUR_API_KEY_HERE>'

Request fields provided as path values:

Field	Requirement	Description
uuid	required	Unique identifier generated by Verity.

Example:

curl --location 'https://verity-api.gumgum.com/video/classification/

24433077-1733-44f4-930c-4a2ce4f18173/status

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

Code Block

language	json

{ "dataAvailable": false, "status": "PROCESSING",

3abddc97-5186-511b-b343-a9aee316b698' \

--header ‘{api_key}’

Response:

Possible status values

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
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

Code Block
{ "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

Code Block
{ "uuiderrorMessage": "244330773abddc97-17335186-44f4511b-930c-4a2ce4f18173b343-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. For example

Request fields provided as path values

Field	Type	Description
uuid	request	Unique identifier generated by Verity

Example:

curl -H 'x-api-key: <YOUR_API_KEY_HERE>-location
'https://verity-api.gumgum.com/video/classification/24433077-1733-44f4-930c-4a2ce4f181733abddc97-5186-511b-b343-a9aee316b698' \
--header 'x-api-key: {api_key}'

Response:

HTTP Status Codes

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

Code Block
{ "errorMessage": " video ‘{uuid}’ does not exist." }

Video is still processing

Code Block
{ "errorMessage": " video ‘{uuid}’ still processing." }

Video has been processed

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
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
v2	array	IAB v2 results produced by Verity
v3	array	IAB v3 results produced by Verity.

v2

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
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
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
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
sentiment	string	Sentiment value produced by Verity. Currently supports: neutral, positive, negative
score	number	GumGum score associated with sentiment.

Segments

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.

Code Block

languagejson


{

"dataAvailable":

true,

status

uuid": "

PROCESSED

5c7da6ee-45aa-5e33-a38f-7b830bae21bb",
    "

pageUrl

url": "https://

www.youtube.com/watch?v=lGOofzZOyl8", "uuid": "5698b006-a8d4-4e3c-a1cd-bd6ec4ad22b6", "verityData": {

kpi-datasets.s3.amazonaws.com/AB_testing_video_threat/nov_AB_test/short_form_samples/merged_dcab3e12-9a0f-572d-9c81-7a1df58b58c0.mp4",
    "data": {
        "processedAt": "

2021

2022-

05

11-

28T00

11T01:

28

59:

14

01.

047Z

539Z",
        "expiresAt": "

2021

2023-

06

11-

27T00

06T01:

28

59:

14

01.

047Z

539Z",
        "languageCode": "en",
        "iab": {
            "v2": [
                {
                    "id": "

424

333",
                    "category": "

Cats

Drama Movies",
                    "score": 0.

28,

95,
                    "parent": {
                        "id": "

422

324",
                        "category": "

Pets"

422

441",
                    "category": "

Pets

Real Estate",
                    "score": 0.

28

383

324",
                    "category": "

Law

Movies",

"score":

0.2,

parent

score": 0.74609375

{

"id":

"379",

"category": "News and Politics"

 ]
        },

}

     "keywords": [

},

{

"bang",

"id":

379

me",
            "

category": "News and Politics",

best actor academy award",
            "

score": 0.2

apology academy",

}

  "getty images bang",

]

},

keywords": [

they",

"zoom

kitten

filter

"nations",

"court case

      "marlon brando",

"lawyer",

cat

death",

"youtube"

]

"apology",

"safe":

true,

threats

post"

:

[

{

    "behalf",

"id":

"GGT2",

       "deserve this

"category": "Criminal

apology tonight",

"confidence":

MODERATE

announced",
            "

risk

bang showbiz"

:

"MEDIUM"

}

],

],

events

safe":

[],

true,
        "

sentiments

threats": [
            {
                "

sentiment

id": "

neutral

GGT6",
                "

score

category":

1

"Hate speech, harassment, and

},

cyberbullying",

{

sentiment

confidence": "

negative

HIGH",

"score":

0

     "risk": "MEDIUM"

},

{

},

"sentiment":

"positive",

"score":

0

}

]

} }

"id": "GGT9",

More Information

Video API Reference

Versions Compared

Old Version 27

New Version Current

Key

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

Page Comparison

Versions Compared

Old Version 27

New Version Current

Key

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