Multimedia Classification API
This document provides a technical overview of the Multimedia Classification API.
Overview & Base Endpoint
Overview
Integral Ad Science (IAS) provides the Multimedia Classification API for you to submit content (audio and video) which IAS scores for brand safety and suitability. Additionally, the Multimedia Classification API returns the Global Alliance of Responsible Media (GARM) brand safety risk level and category of the submitted content.
GARM establishes "common definitions to ensure that the advertising industry is categorizing harmful content in the same way across the board reducing the availability and monetization of harmful content online."
Base Endpoint
https://bss.adsafeprotected.com/v1/Authorization
This API uses OAuth 2.0 with a grand_type=client_credentials. Get a client ID and client secret from yoru IAS representative. You only need one set of credentials, and you do not need access to IAS Signal.
Authentication Request
Get a token through the following command:
curl -H "Accept:application/json" -u {client ID}:{client Secret} https://auth.adsafeprotected.com/uaa/oauth/token -d grant_type=client_credentialsAuthentication Response
Value | Description |
{client ID}:{client Secret} | client ID and secret, separated by a colon |
grant_type | client_credentials |
username | the IAS Signal username |
password | the password for the IAS Signal username |
Authentication Token URL | https://auth.adsafeprotected.com/uaa/oauth/token |
The event POST requests can pass the access_token in HTTP header:
Authorization: bearer nnNnnNnnOnNNN...Once generated, you can re-use the token with multiple requests to the Multimedia Classification API until the token expires (which is indicated with the error 'invalid_token' and an error description 'Access token expired').
Example:
{ "jti": "x0x0x000-0x0x-0000-x0x0-x00x0xx000x0", "scope": "00:{client ID}:write", "expires_in": 12345, "token_type": "bearer", "access_token": "nnNnnNnnOnNNN..."}Score
Description
Use this API to give IAS a multimedia (audio, text, image, or video) resource to score for brand safety. This API returns a unique content ID for each resource which you use when calling results to obtain the GARM score.
Body Request
Key | Description | Required/Optional |
url | The location of the resources. | Required. |
title | Adding a title provides more data to determine the GARM score. | Optional. |
description | Adding a description provides more data to determine the GARM score. | Optional. |
language | ISO 639-1 standard language codes as an array with en-US as the default language. For example, language: ["en-US", "es-MX"] | Optional. |
See the Body Request to the below.
{ url: ["The location of the resource"], title: "Optional to use - title of the resource", description: "Optional to use - description of the resource", language: ["en-GB", "es-MX"]}Return Values
Code | Description |
200 | success. |
503 | failure / processing timeout on IAS's end. |
Returned JSON
Key | Description |
contentId | Upon success, the UUID of the resource IAS scores. Use this UUID in the
result
call. |
error | When a problem occurs, this value describes the error. |
Sample
Curl
curl -X POST http://bss.adsafeprocted.com/v1/score -H 'Content-Type: application/json' -d '{"url": ["https://cdn.widget.com/podcasts/content/1E3iAJQ4S00pUaHI71vDBz"], "title":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", language: ["en-GB"] }'Responses
200 Success
503 Error
200 Success Example:
{ "contentId": "b544e84a-76ac-76ac-76ac-1d0621cdcbba"}503 Error Example:
{ "error": "Error description"}Results
Description
This API retrieves the GARM scores for the multimedia submitted via the score API. For successful returns, the API provides a status to show whether IAS is scoring the resource or completed the score. Once the status is completed, then the returned object contains a scoring for the resource.
Body Request
Request | Type | Description |
contentId | UUID | Universal Unique Identifier of the content to get the GARM score. |
Return Values
Code | Description |
200 | Completed |
404 | "error": "Not found" |
503 | "error": "Error description" |
503 | { "contentId": "...", "status": "failed", "error" : "Error description" } |
Returned JSON
Key | Description |
contentId | UUID of the content scored via
score
request. |
status | If success, either: processing completed |
garmScores | When the status is complete, then garmScores gives a scoring on various GARM classifications, where: S: Safe L: Low M: Medium H: High F: Floor For example: { "adult": "S", "arms": "M", "crime": "S", "death": "S", "debated": "S", "drugs": "H", "hate": "F", "obscene": "L", "piracy": "S", "spam": "S", "terror": "S" } |
Sample
Curl
curl -X POST http://bss.adsafeprocted.com/v1/results -H 'Content-Type: application/json' -d '{"contentId": "b544e84a-76ac-76ac-76ac-1d0621cdcbba"}'Responses
Success - Processing Status
Success - Complete Status
404 Error
503 Error
503 Failed Error
Success - Processing Status Example:
{ "contentId": "b544e84a-76ac-76ac-76ac-1d0621cdcbba", "status": "processing"}Success - Complete Status Example:
{ "contentId": "b544e84a-76ac-76ac-76ac-1d0621cdcbba", "status": "completed", "garmScores": { "adult": "S", "arms": "M", "crime": "S", "death": "S", "debated": "S", "drugs": "H", "hate": "F", "obscene": "L", "piracy": "S", "spam": "S", "terror": "S" }}404 Error Example:
{ "error": "Not found"}503 Error Example:
{ "error": "Error description"}503 Failed Error Example:
{ "contentId": "b544e84a-76ac-76ac-76ac-1d0621cdcbba", "status": "failed", "error" : "Error description"}