Get Started - Video API
- 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.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 |
---|---|---|
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 |
---|---|
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:
{
"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 |
---|---|---|
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 |
---|---|
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
{
"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 |
---|---|---|
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 |
---|---|
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 |
---|---|---|
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.
More Information
The contents of these documents and any attachments contain GumGum, Inc. confidential information and are legally protected from disclosure.