Versions Compared

Old Version 19

changes.mady.by.user ClaireT (Deactivated)

Saved on

compared with

New Version Current

changes.mady.by.user David Parker

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
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. Include Optionally, include the required language code parameter:

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.

publisherId

optional

Unique identifier for the publisher of the video.

callbackUrl

optional

Verity API returns a JSON response with 

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
languagejson
{
  "dataAvailable": false,
  "statusuuid": "INITIATED3abddc97-5186-511b-b343-a9aee316b698",
    "pageUrlurl": "https://www.youtube.com/watch?v=lGOofzZOyl8",
    "uuidacceptedAt": "244330772023-1733-44f4-930c-4a2ce4f1817303-07T17:26:05.694Z"
}

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

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
languagejs
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
languagejson
{ "dataAvailable": false, "status": "PROCESSING", "pageUrl

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": "uuid"DOWNLOADING"
}

If provided UUID is for a video not seen by Verity

Code Block
{
    "errorMessage": "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 page 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",

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

uuid

processedAt": "

24433077

2022-

1733-44f4-930c-4a2ce4f18173",

11-11T01:59:01.539Z",
        "

verityData

expiresAt":

{

"2023-11-06T01:59:01.539Z",
        "languageCode": "en",
        "iab": {
            "

v1

v2": [
                {
                    "id": "

IAB19

333",
                    "category": "

Technology

Drama

& Computing

Movies",
                    "score": 0.95,

}

],

       "

v2

parent":

[

{

{

           "id": "

424

324",

"category":

"Cats",

           "

score

category":

0.28,

"Movies"

"parent":

{

         }

"id":

"422",

            },

"category":

"Pets"

}

    {

},

{

        

"id": "

422

441",
                    "category": "

Pets

Real Estate",
                    "score": 0.

28

82714844
                },
                {
                    "id": "

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

"kitten",

       "

zoom

nations",

"filter",

       "

court

marlon

case

brando",

"stuck", 

      "

cat

death",

"lawyer",

       "

court

apology",

"case", 

      "

youtube

post",

"funny"

]

"behalf",

"safe":

true,

"threats":

[

 "deserve this apology tonight",

{

"id":

 "

GGT2

announced",
            "

category

bang showbiz"

:

"Criminal",

        ],

"confidence":

"MODERATE"

} 

"safe": true,

],

     "

events

threats": [

],

"sentiments":

[

       {

"sentiment

        "id": "

neutral

GGT6",
                "

score

category":

1

"Hate speech, harassment, and cyberbullying",

},

{

         "

sentiment

confidence": "

negative

HIGH",

"score":

0

}, 

"risk": "MEDIUM"

{

       },

"sentiment":

"positive",

"score":

0

{

}

],

     "

processedAt

id": "

2021-02-10T00:17:55.027Z" } }

GGT9",

More Information