Video JSON Object Specification

The Video JSON Object is the data you will need to pass in your API requests to either create or update a video in the system.

This article describes the structure of the Video JSON Object including property names and corresponding values.

 

Video JSON Object Template

The following JSON Object is a template that includes value placeholders for all the properties available in the video object. Please refer to the Video JSON Properties & Values table to learn what values and types are supported.

Note: String placeholders are highlighted in red, integers in green and booleans in blue.

{
"id": "VIDEO_ID", //String
"name": "VIDEO_NAME/TITLE", //String
"shortDescription": "SHORT_DESCRIPTION", //String
"description": "LONG_DESCRIPTION", //String
"originalVideoUrl": "VIDEO_ORIGINAL_URL", //String
"storageType": "STORAGE_TYPE", //String
"encodingProfileId": "ENCODING_PROFILE_ID", //String
"sellerRuleId": "SELLER_RULE_ID", //String
"clickUrl": "CLICK_VIDEO_URL", //String
"supportedPlayerTypes": ["SUPPORTED_PLAYER"], //Array of strings
"maxAds": MAX_ADS, //Integer
"contentLifecycle": "CONTENT_LIFECYCLE", //String
"category": ["CATEGORY_TAG"], //Array of strings
"keywords": ["KEYWORD"], //Array of strings
"copyright": "COPYRIGHT", //String
"credit": "CREDIT", //String
"author": ["AUTHOR"], //Array of strings
"media": {
"tag": ["VIDEO_TEXT_TAG"] //Array of strings
},
"audienceGender": "AUDIENCE_GENDER", //String
"ageRatings": ["AGE_RATING"], //Array of strings
"commonRating": {
"value": "CONTENT_RATING_VALUE", //String
"descriptors": ["CONTENT_RATING_DESCRIPTOR"] //Array of strings
},
"countries": ["usa"], //Array of strings
"language": {
"code": "LANGUAGE_CODE", //String
"name": "LANGUAGE_NAME" //String
},
"transcript": "TRANSCRIPT", //String
"transcriptEnabled": AUTO_TRANSCRIPT_OPTION, //Boolean
"systemThumbnails": [{
"url": "THUMBNAIL_URL", //String
"width": THUMBNAIL_WIDTH, //Integer
"height": THUMBNAIL_HEIGHT //Integer
}],
"thumbnailsNew": [{
"id": "THUMBNAIL_ID", //String
"covering": true, //Boolean
"type": "AUTO", //String
"version": 1, //Integer
"sizes": [{
"original": false, //Boolean
"width": THUMBNAIL_WIDTH, //Integer
"height": THUMBNAIL_HEIGHT, //Integer
"url": "THUMBNAIL_URL" //String
}]
}],
"encodedVariants": [{
"width": RENDITION_WIDTH, //Integer
"height": RENDITION_HEIGHT, //Integer
"mono": false, //Boolean
"provider": "ENCODING_PROVIDER", //String
"aspectRatio": 0, //Integer
"videoUrl": "RENDITION_URL", //String
"audioBitRate": AUDIO_BIT_RATE, //Integer
"advancedQuality": false, //Boolean
"audioQuality": AUDIO_QUALITY, //Integer
"videoQuality": VIDEO_QUALITY, //Integer
"videoBitRate": VIDEO_BIT_RATE, //Integer
"crop": false, //Boolean
"frameStep": true //Boolean
}],
}

Note: The Video JSON Object template includes all available properties and values, some of which might contradict one another. For specific minimal examples please refer to the examples at the bottom of this article.

 

Video JSON Proerties & Values

The following tables describes all the available Video JSON Object properties and accepted values. The tables are split into the following topics for easier navigation:

 

 

General

Property Name Description Type Example
id

The Video Identification number designated by the system.
When creating a new video, this property and value are automatically given by the system according to the Company Key you provided.

Syntax: A 24 character alpha-numeric value.

Use: Update (PUT) Mandatory/Create (POST) Not Required.

String
{
"id":"56d475aee4b03ea22d9fde93"
}
name

The name or title of the video.

Use: Create (POST) Mandatory/Update (PUT) Optional.

String
{
"name":"Video title"
}
shortDescription

A short and concise description of the video.

Use: Create (POST) Mandatory/Update (PUT) Optional.

String
{
"shortDescription":"Video short description"
}
description

A detailed description of the video.

Use: Create (POST) Optional/Update (PUT) Optional.

String
{
"description":""
}
originalVideoUrl

The URL address for the original video file. This property can be used to ingest a new video into our system or just specify the location of the original video file.

Note: URLs must include an http:// or https:// prefix.

Note: To upload a video and automatically ingest it into the system, please see Ingestion video minimal object.

Use: Create (POST) Mandatory/Update (PUT) Optional.

String
{
"originalVideoUrl":"http://www.aolonnetwork.com/videos/my_video_001.mp4"
}
storageType

Defines if a passed 'originalVideoUrl' property URL address value will be sent to the rendition encoding process.

This property accepts the following two options:

  • ENCODED - Selecting this option will send the 'originalVideoUrl' video file to be encoded by the system. Renditions will be created according to the defined 'encodingProfileId' defined in the video object.

    Note: For further details, please see How to Ingest a new video using upload API

  • EXTERNAL - Selecting this option will allow you to pass 'encodedVariants' objects for any externally hosted renditions you have out of our platform.

    Note: For further details, please see How to create video linked to an externally hosted rendition.
String
{
"storageType": "ENCODED"
}
encodingProfileId

The identification number of the Encoding Profile object assigned to this video.

Encoding profiles control what renditions will be created for the video.

When creating a new video, this value is automatically updated by the system according to your Company's default Encoding Profile. By passing a specific Encoding Profile ID you can apply different rendition settings when ingesting or updating your video.

Note: You can only use ID numbers of other Encoding Profiles created or shared with your Company.

String
{
"encodingProfileId": "56d475aee4b03ea22d9fde93"
}
sellerRuleId

The identification number of the Seller Rule object assigned to this video.

Seller Rules controls the video's syndication and restriction settings.

When creating a new video, this value is automatically updated by the system according to your Company's default seller rule. By passing a specific Seller Rule ID you can apply different syndication and restriction settings for this video.

Note: You can only use ID numbers of other Seller Rules created under your Company.

Syntax: A 24 character alpha-numeric value.

Recommendation: We recommend using our default Encoding profile with the following ID: 54f3028ce4b0eb68ceca1c1f

Use: Create (POST) Optional/Update (PUT) Optional.

String
{
"sellerRuleId":"54f3028ce4b0eb68ceca1c1f"
}
clickUrl

A URL address that will redirect the viewer upon clicking on the player when playing back the video.

Note: This URL will override any Player click address set on the player level when this video is played back.

Use: Create (POST) Optional/Update (PUT) Optional.

String
{
"clickUrl":"http://www.aolplatforms.com/onebyaol-publishers"
}
supportedPlayerTypes

The supported player types that are compatible with this video, according to the following options:

  • O2 - The video is compatible for playback using our Player.
  • YAHOO - The video is compatible for playback using the Yahoo Player.
  • NONE - The video is not suitable for playback using our any of our Player (mostly used for content delivered by VAST Tag).

Note: You can pass multiple player types in this array.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings
{
"supportedPlayerTypes": [
"YAHOO",
"O2"
]
}

 

{
"supportedPlayerTypes": [
"NONE"
]
}
maxAds

The maximum number of ads that will be served when playing this video. This is a total cap limit for pre/mid-rolls that will be served by the player's ad settings when this specific video is played back.

Use: Create (POST) Optional/Update (PUT) Optional.

Integer
{
"maxAds": 5
}

 

 

 

Video Metadata

Property Name Description Type Example
contentLifecycle

The content life-cycle of the video according to the following options:

  • Evergreen - The video is always topical and not specific to any time period.
  • Fast-Breaking - he video is a trending/news topic.
  • Live - he video is a live feed.

Note: You can only pass one value.

Use: Create (POST) Optional/Update (PUT) Optional.
String
{
"contentLifecycle":"Evergreen"
}
category

Custom category vertical metadata associated with your video.
This field is not linked to any standardized category list and allows you to enter any word.

Note: You can pass multiple strings to this array.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings
{
"category":["Sports","Baseball"]
}
keywords

Custom keyword metadata associated with your video. This field is not linked to any standardized keyword list and allows you to enter any word.

Note: You can pass multiple strings to this array.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings
{
"keywords":["Babe Ruth","Home Run"]
}
copyright

Custom copyright information associated with your video.

Use: Create (POST) Optional/Update (PUT) Optional.

String
{
"copyright":"copyright information"
}
credit Custom credit information associated with your video.

Use: Create (POST) Optional/Update (PUT) Optional.

String
{
"credit":"credits information"
}
author

Custom Author information associated with your video.

Note: You can pass multiple strings to this array.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings
{
"author":[
"J K Rowling","George R. R. Martin"
]
}
media:tag

Custom tag metadata associated with your video.
This field is not linked to any standardized tag list and allows you to enter any word.

Note: You can pass multiple strings to this array.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings in Object
{
"media":{
"tag":["Sports","Action"]
}
}
audienceGender

A target gender for which this video is most appropriate, according to the following options:

  • Female - The video is appropriate for female viewers.
  • Male - The video is appropriate for Male viewers.
  • All - The video is appropriate for all viewers.

Note: You can pass only one value.

Use: Create (POST) Optional/Update (PUT) Optional.

String
{
"audienceGender":"All"
}
ageRatings

A target age rating for which this video is most suited for, according to the following options:

  • KIDS - The content is appropriate for kids approximately up to the age of 9.
  • TWEENS - The content is appropriate for kids nearing puberty, approximately between the ages of 10-11.
  • TEENS - The content is appropriate for teenagers, approximately between the ages of 12-20.
  • ADULTS - The content is appropriate for teenagers, approximately between the ages of 21-54.
  • SENIORS - The content is appropriate for teenagers, approximately between the ages of 55 and above.
  • NONE_SPECIFIED - This content does not have an age rating classification. Selecting this option will override all other.

Note: You may pass multiple string to this array as long as you do not pass 'NONE_SPECIFIED' with any others.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings
{
"ageRatings":["KIDS","TWEENS"]
}
commonRating:value

A standard content rating that defines who is most suitable to view this video, according to the following options:

  • Y - The video is suitable for all children.
  • Y-7 - The video is suitable for ages 7 and above.
  • G - The video is suitable for all ages.
  • PG - The video is suitable for ages 10 and above.
  • PG-14 - The video is suitable for ages 14 and above.
  • MA - The video is suitable for ages 17 and above.
  • NC-17 - The video is suitable for adults only.
  • NR - The video is not rated.

Note: You can pass only one value.

Use: Create (POST) Optional/Update (PUT) Optional.

String in Object
{
"commonRating":{
"value":"NR"
}
}
commonRating:descriptors A standard content descriptor that describes the contents of the video, according to the following options:
  • D - The video contains suggestive dialog.
  • L - The video contains coarse language.
  • S - The video contains sexual content
  • V - The video contains violence.
  • FV - The video contains fantasy violence.
  • AR - The video is age restricted.

Note: You may pass multiple string to this array.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings in Object
{
"commonRating":{
"descriptors":["D","L"]
}
}
countries

Countries in which this video is suitable to be played back in.
Enter any 3 letter country code.

Note: You may pass multiple string to this array.

Note: All countries should be in lowercase.

Note: For further details on country code designations, please click here.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Strings
{
"countries":[
"use",
"gbr"
]}
language:code

The language code spoken in your video.
Enter any 2 letter language code.

Note: You can pass only one.
Note: For further details on language code designations, please click here.

Use: Create (POST) Optional/Update (PUT) Optional.

String in Object
{
"language":{
"code":"en"
}
}

 

 

 

 

Transcripts

Property Name Description Type Example
transcript

A textual record of spoken language, which may include naming the subject spoken at any given time.

Use: Create (POST) Optional/Update (PUT) Optional.

String
{
"transcript":"Adam: Hey Marcel,
do you know how to upload a
transcript? Marcel: Sure,
just add it into the video
object transcript property
field."
}
transcriptEnabled

Apply our automated voice to text recognition service that will creatae a transcript for your video based on the videos audio soundtrack.

Note: This is option is set to true by default to all uploaded videos. If your video contains background music or other sounds that might interrupt the voice recognition process we recommend setting this field to false.

Use: Create (POST) Optional/Update (PUT) Optional.

Boolean
{
"transcriptEnabled":"false"
}

 

 

 

 

 

Thumbnails

Property Name Description Type Example
systemThumbnails

An array used to hold image thumbnail objects that are displayed on your video before playback has started.

Note: You may pass multiple thumbnail objects to this array.

Note: This object is intended to be replaced by the 'thumbnailNew' object in the near future. The object name might stay the same.
A formal update will be provided when this change is implemented.

Note: URLs must include an http:// or https:// prefix.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Objects
{
"systemThumbnails":[
{
"url": "http://www.aolplatforms.com/sites/aolplatforms.com/files/uploads/ONE%20Logo_0.png",
"width": 450,
"height": 300
}
]
}
thumbnailsNew

An array used to hold image thumbnail objects that are displayed on your video before playback has started.

Note: You may pass multiple thumbnail objects to this array. The first image object in the array is the one that will be assigned to the video.

Note: When a new thumbnail is created it is given an identification number by the system. This can be used to identify a specific thumbnail for updating using the PUT request.

Note: URLs must include an http:// or https:// prefix.

Note: This object is intended to replace the 'systemThumbnail' object in the near future. The object name might change to 'systemThumbnail' .
A formal update will be provided when this change is implemented.

Use: Create (POST) Optional/Update (PUT) Optional.

Array of Objects

Create (without ID property)

{
"thumbnailsNew": [
{
"id":"56d475aee4b03ea22d9fde93",
"covering": true,
"type": "AUTO",
"version": 1,
"sizes": [{
"original": false,
"width": 853,
"height": 480,
"url": "http://cdn.vidible.tv/prod/2016-04/26/571f2c6de4b0953a97d8df41_853x480_A_v1.jpg"
}]
}
]
}


Update (with ID property)

{
"thumbnailsNew": [
{
"id":"56d475aee4b03ea22d9fde93",
"covering": true,
"type": "AUTO",
"version": 1,
"sizes": [{
"original": false,
"width": 853,
"height": 480,
"url": "http://cdn.vidible.tv/prod/2016-04/26/571f2c6de4b0953a97d8df41_853x480_A_v1.jpg"
}]
}
]
}

 

 

 

Encoding

Property Name Description Type Example
encodedVariants

An array used to point to video rendition objects that are externally hosted.

Note: encodedVariants only need to be defined when you want to display an externally hosted video using our system. This does not need to be applied to your video object if you intend to ingest a video into the system using the originalVideoUrl property.

Note: Currently the 'provider' property supports the following values: ZENCODER, ENCODING and UPLYNK.

Array of Objects
{
"encodedVariants":[
{
"advancedQuality": false,
"aspectRatio": 0,
"audioBitRate": 96,
"audioQuality": 5,
"crop": false,
"fileSizeBytes": 13927700,
"frameStep": true,
"height": 480,
"mono": false,
"provider": "ZENCODER",
"tokenEnabled": false,
"videoBitRate": 1500,
"videoQuality": 3,
"videoUrl": "http://cdn.vidible.tv/prod/2016-04/26/571f2c6de4b0953a97d8df41_853x480_v1.mp4",
"width": 853
}
]

 

Examples

 

Upload and Ingest Video

The following Video JSON Object is the minimal requirement to create a new video in the system including ingestion. This video will be ingested into our system and multiple renditions will be created for it.

POST Request

http://api.vidible.tv/5d3f3b3ac9374m3463be2557e04697ad/video


Passed Video JSON Object

{
"name": "Ingest New Video",
"encodingProfileId": "54f3028ce4b0eb68ceca1c1f",
"storageType": "ENCODED",
"originalVideoUrl": "http://mockup.on.aol.com/Adam/Videos/aolSampleVideo.mp4"
}

Response

{
"id": "5720bcdae4b0e7aba8369c09",
"companyId": "56d5921ce4b0f5991ad44713",
"creationDate": 1461763290190,
"name": "Ingest New Video",
"originalVideoUrl": "http://mockup.on.aol.com/Adam/Videos/aolSampleVideo.mp4",
"metadata": {},
"encodedVariants": [],
"thumbnailsNew": [],
"commonRating": {
"value": "G",
"descriptors": [],
"minAge": 0
},
"audienceGender": "All",
"countries": [],
"media": {},
"contentLifecycle": "Evergreen",
"associatedCompanies": [],
"logo": {
"region": {
"x": 0,
"y": 0,
"w": 0,
"h": 0
}
},
"sellerRuleId": "56d8474ee4b037ad9eade4da",
"deleted": false,
"supportedPlayerTypes": [
"O2"
],
"playbackAvailable": false,
"ageRatings": [
"NONE_SPECIFIED"
],
"storageType": "ENCODED",
"version": 1,
"hidden": false,
"subtitles": [],
"encodingProfileId": "54f3028ce4b0eb68ceca1c1f",
"uploadState": "Encoding"
}

 

Upload Externally Hosted Video

The following Video JSON Object is the minimal requirement to create a new video in the system excluding ingestion. This video will not be ingested into our system but will point to an externally hosted video rendition.

POST Request

http://api.vidible.tv/5d3f3b3ac9374m3463be2557e04697ad/video


Passed Video JSON Object

{
"name": "Externally Hosted New Video",
"storageType": "EXTERNAL",
"originalVideoUrl": "http://mockup.on.aol.com/Adam/Videos/aolSampleVideo.mp4",
"encodedVariants": [
{
"advancedQuality": false,
"aspectRatio": 0,
"audioBitRate": 96,
"audioQuality": 5,
"crop": false,
"fileSizeBytes": 13927700,
"frameStep": true,
"height": 480,
"mono": false,
"provider": "ZENCODER",
"tokenEnabled": false,
"videoBitRate": 1500,
"videoQuality": 3,
"videoUrl": "http://cdn.vidible.tv/prod/2016-04/26/571f2c6de4b0953a97d8df41_853x480_v1.mp4",
"width": 853
}
]
}

Response

{
"id": "5720c5b0e4b0e7aba836ac37",
"companyId": "56d84746e4b0558a22bf8f75",
"creationDate": 1461765552241,
"name": "Externally Hosted New Video",
"originalVideoUrl": "http://mockup.on.aol.com/Adam/Videos/aolSampleVideo.mp4",
"metadata": {},
"encodedVariants": [
{
"audioBitRate": 96,
"width": 853,
"height": 480,
"advancedQuality": false,
"audioQuality": 5,
"videoQuality": 3,
"videoBitRate": 1500,
"crop": false,
"frameStep": true,
"mono": false,
"provider": "ZENCODER",
"aspectRatio": 0,
"tokenEnabled": false,
"videoUrl": "http://cdn.vidible.tv/prod/2016-04/26/571f2c6de4b0953a97d8df41_853x480_v1.mp4",
"fileSizeBytes": 13927700,
"file": ""
}
],
"thumbnailsNew": [],
"commonRating": {
"value": "G",
"descriptors": [],
"minAge": 0
},
"audienceGender": "All",
"countries": [],
"media": {},
"contentLifecycle": "Evergreen",
"associatedCompanies": [],
"logo": {
"region": {
"x": 0,
"y": 0,
"w": 0,
"h": 0
}
},
"sellerRuleId": "56d8474ee4b037ad9eade4da",
"deleted": false,
"supportedPlayerTypes": [
"O2"
],
"playbackAvailable": false,
"ageRatings": [
"NONE_SPECIFIED"
],
"storageType": "EXTERNAL",
"version": 1,
"hidden": false,
"subtitles": []
}

 

 

Have more questions? Submit a request