| Table of Contents |
|---|
Video Endpoints
The
...
GumGum Contextual video analysis endpoints are:
HTTP Request | POST |
|---|---|
Authorization Header |
|
GumGum Contextual Endpoint |
|
...
Verity API processes HTTP POST requests to initiate a new video analysis.
...
Body |
|
HTTP Request | GET |
|---|---|
Authorization Header |
|
GumGum Contextual Endpoint |
|
...
HTTP |
|---|
...
Request | GET |
|---|---|
Authorization Header |
|
GumGum Contextual Endpoint |
|
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
...
| Code Block | ||
|---|---|---|
| ||
{
"url": "https://www.youtube.com/watch?v=lGOofzZOyl8",
"description": "lawyer gets stuck on Zoom kitten filter during court case",
"title": "I'm not a cat'",
"languageCode": "en",
"partnerVideoId": "UUID",
"publisherId": "UUID",
"callbackUrl": "URL value"
} |
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, |
...
GumGum Contextual 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, |
...
GumGum Contextual will push Video Classification results to this endpoint after the video has processed successfully. |
Example:
...
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":"'I'm not a cat': lawyer gets stuck on Zoom kitten filter during court case "languageCode": "en"}' https://verity-api.gumgum.com/video/classification |
Response:
Field | Description |
|---|---|
uuid | Unique identifier generated by |
...
GumGum Contextual | |
url | Video url provided by client |
acceptedAt | ISO-8601 formatted timestamp represented when the video was first accepted by |
...
GumGum Contextual for processing |
Valid HTTP status codes:
Status Code | Description |
|---|---|
202 | Video was accepted by |
...
GumGum Contextual for classification | |
500 | Internal Server Error. Please contact customer support. |
Example:
| Code Block | ||
|---|---|---|
| ||
{
"uuid": "3abddc97-5186-511b-b343-a9aee316b698",
"url": "https://www.youtube.com/watch?v=lGOofzZOyl8",
"acceptedAt": "2023-03-07T17:26:05.694Z"
} |
Once the video classification request is sent, if a callback url was provided, results will be sent to the webhook endpoint.
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 |
...
GumGum Contextual. |
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
...
...
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 |
|---|
{
"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 to get the results, this endpoint will not returned status and will only return results once the status changes to PROCESSED otherwise will return 404 not found, 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 |
...
GumGum Contextual |
Example:
| Code Block | ||
|---|---|---|
| ||
curl --location |
...
'https://verity-api.gumgum.com/video/classification/ |
...
{uuid}' \ --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
...
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 |
|---|
{
"uuid": "5c7da6ee-45aa-5e33-a38f-7b830bae21bb",
"url": "https://kpi-datasets.s3.amazonaws.com/AB_testing_video_threat/nov_AB_test/short_form_samples/merged_dcab3e12-9a0f-572d-9c81-7a1df58b58c0.mp4",
"data": {
"processedAt": "2022-11-11T01:59:01.539Z",
"expiresAt": "2023-11-06T01:59:01.539Z",
"languageCode": "en",
"iab": {
"v2": [
{
"id": "333",
"category": "Drama Movies",
"score": 0.95,
"parent": {
"id": "324",
"category": "Movies"
}
},
{
"id": "441",
"category": "Real Estate",
"score": 0.82714844
},
{
"id": "324",
"category": "Movies",
"score": 0.74609375
}
]
},
"keywords": [
"bang",
"me",
"best actor academy award",
"apology academy",
"getty images bang",
"they",
"nations",
"marlon brando",
"death",
"apology",
"post",
"behalf",
"deserve this apology tonight",
"announced",
"bang showbiz"
],
"safe": true,
"threats": [
{
"id": "GGT6",
"category": "Hate speech, harassment, and cyberbullying",
"confidence": "HIGH",
"risk": "MEDIUM"
},
{
"id": "GGT9", |