...
| 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 shows a request to analyze walks through analyzing an english language video at the URL:
httphttps://www.youtube.com/watch?v=lGOofzZOyl8
| 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. |
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:
| 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 |
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.
Verity API returns a JSON response with Content-Type: application/json; charset=UTF-8 showing the request has the following status: 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": "8f72c44b3abddc97-05c85186-4946511b-8c69b343-bcc98c655367a9aee316b698",
"url": "httphttps://contentwww.jwplatformyoutube.com/videos/00D9qbqJ-320.mp4watch?v=lGOofzZOyl8",
"acceptedAt": "20202023-0403-18T0007T17:4326:4405.015+0000694Z"
} |
For a list of supported status messages, refer to Application Status CodesOnce 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. For example:
...
| language | js |
|---|
...
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-
...
Verity API returns a JSON response with Content-Type: application/json; charset=UTF-8 showing the request has the following status:
...
| language | json |
|---|
...
b343-a9aee316b698' \
--header ‘{api_key}’
Response:
Step 3 – Get response
Submit a GET request to /video/classification/{uuid}, specifying the uuid returned in the response in step 1. Once 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 page video classification results are returned in the data payload. For example:curl -H 'x-api-key: <YOUR_API_KEY_HERE>
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}' |
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 |
|---|
...
| language | json |
|---|
...
{ "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", |