Media API

Media (video and audio) can be encoded to a variety of formats and quality levels, then distributed onto our global CDN for streaming to end-users.

Create (register) media

HTTP Operation: POST
URL: POST https://secure.metacdn.com/api/users/{username}/media
Auth: HTTP digest authentication
"Content-Type" header: application/json
Expected HTTP response: HTTP/1.1 201 Created
Expected Format (mandatory, optional):

POST /api/users/{username}/media  HTTP/1.1
Content-Type: application/json {
"originSource": [{
    "originUrl": "",
    "aspectRatio": "",
    "screenshotUrl": "",
    "captionUrl": "",
    "splashScreenUrl": "",
    "title": "",
    "description": ""
},
...,
{
    "originUrl": "",
    "aspectRatio": "",
    "screenshotUrl": "",
    "captionUrl": "",
    "splashScreenUrl": "",
    "title": "",
    "description": ""
}],
    "hostUntil": "DD Mon YYYY HH:MM:SS GMT",
    "outputFormats": ["FORMAT1", ..., "FORMATN"],
    "quality": ["Q1", "Q2", ..., "QN"],
    "mediaType": "Video", "Audio",
    "autoQualitySelection": true/false,
    "useEncryption": true/false,
    "aesKey": "AEAEAEAEAEAEAEAEBEBEBEBEBEBEBEBE",
    "aesKeyServer: "https://mykeyserver.com/keys/media",
    "mediaBrandingTemplateName": "",
    "tags": ["TAG1", "TAG2", ..., "TAGN"]
}

Notes:

• "originSources" is a list of media contents hosted on your origin server
• "originUrl" is the source URL of the media content.
• "aspectRatio" is the aspect ratio of the media source, either STANDARD (i.e. 4:3), WIDESCREEN (i.e. 16:9) or AUTO. If it is to AUTO, the aspect ratio will automatically be determined by inspecting the media source.
• "screenshotUrl" is the URL of a screenshot which gets displayed in the media player while the audio is being played back. For the screenshot to show up in the player, the media type must be set to Audio. If media type is Video, this URL is ignored.
  Note that the following image formats are supported: JPG, JPEG, JPE, JIF, JFIF, JFI, PNG
• captionUrl is the URL of a caption file (e.g. subtitle or closed captions) which gets displayed in the media player while the video is being played back. For the captions to show up in the player, the media type must be set to Video. If media type is Audio, this URL is ignored.
  Note that the following caption formats are supported: SRT (Subrip), XML (TT)
• "splashScreenUrl" is the URL of an image which gets displayed in the media player before the video starts playing back. For the splash image to show up in the player, the media type must be set to Video. If media type is Audio, this URL is ignored.
  Note that the following image formats are supported: JPG, JPEG, JPE, JIF, JFIF, JFI, PNG
• "title" is a value that specify the title of the media, the default value will be the file name of the original source. The maximum length allowed for the title field is 100 characters.
• "description" is a value that describes the media content. The maximum length allowed for the description field is 500 characters.
• "hostUtil" is the date you want the deployment to be terminated, after which any replicas that have been created will be deleted. If you omit this field the media will be hosted until you request its deletion.
• "outputFormats" can be mp4, flv, webm, webm_vp9, webm_vp9_dash, ogg, 3gp, mp3 or ogg if the mediaType is Video. Output formats mp3 and ogg are audio-only which means either of the following:
  
  • the audio stream of the origin video gets extracted if the media type is Video.
  • the provided audio source gets re-encoded to MP3 or OGG if the media type is Audio. Note that the following audio input formats are supported: OGG, MP3, AAC, M4A, AIF, WAV, FLAC, WMA
• "quality" can be a list containing MOBILE, LOW, MEDIUM, HIGH, XHIGH, XHIGH_QHD or XHIGH_4K.
• "mediaType" is the type of media and can be either Video or Audio.
• "duplicates is a boolean value that specifies whether you want multiple replicas deployed in each specified location if available.
• "mediaBrandingTemplateName" is the name of the Media Branding template you wish to use when displaying the video.
• "tags" is a list of tags you want your media content to have.
• When creating media, "originUrl" is sent back to the caller in the response. The originUrl can be used to unambiguously map originSource entries to mediaInfo response entries.

Example Call #1:

POST /api/users/rockettest/media HTTP/1.1
Content-Type: application/json {
    "originSource": [{
        "originUrl": "http://www.metacdn.org/trailer_1080p.ogg",
        "aspectRatio": "WIDESCREEN",
        "title": "trailer_1080p.ogg",
        "description": "Big Buck Bunny Trailer"
    }],
    "hostUntil": "10 Sep 2011 08:00:25 GMT",
    "outputFormats": ["mp4","flv"],
    "quality": ["MOBILE","LOW", "MEDIUM", "HIGH", "XHIGH"],
    "mediaType": "Video",
    "mediaBrandingTemplateName": "Default",
    "tags": ["trailer", "bunny"]
}

Expected Response #1:

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Mon, 12 Sep 2011 07:00:28 GMT
Server: Google Frontend
Cache-Control: private, x-gzip-ok=""
Connection: close {
    "mediaInfo": [{
        "metaCdnHttpsUrl": "https://secure.metacdn.com/sr/m/vexleor/56IX9R",
        "keyName": "56IX9R",
        "mediaName": "trailer_1080p_ogg",
        "originUrl": "http://www.metacdn.org/trailer_1080p.ogg",
        "metaCdnUrl": "http://www.metacdn.com/r/m/5RJhVGiSZO/56IX9R",
        "metaCdnApiUrl": "http://www.metacdn.com/api/users/rockettest/media/56IX9R"
    }]
}

Get media

HTTP Operation:GET
URL: GET https://secure.metacdn.com/api/users/{username}/media/{mediakey}
Auth: HTTP digest authentication
"Accept" header: application/json
Expected HTTP response: HTTP/1.1 200 OK
Expected Format (mandatory, optional):

GET /api/users/{username}/media/{mediakey} HTTP/1.1
Accept: application/json

Example Call #1:

GET /api/users/rockettest/media/56IX9R HTTP/1.1
Accept: application/json

Expected Response #1:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Mon, 12 Sep 2011 07:05:36 GMT
Server: Google Frontend
Cache-Control: private, x-gzip-ok=""
Connection: close {
    "metaCdnHttpsUrl": "https://www.metacdn.com/sr/m/5RJhVGiSZO/56IX9R",
    "aspectRatio": "WIDESCREEN",
    "description": "Big Buck Bunny Trailer",
    "duplicates": false,
    "encodeInfo": [{
        "container": "FLV",
        "contentUrl": "http://cdn-1.metacdn.net/rockettest/56IX9R/20120601011931_trailer1080p_ogg-LOW.flv",
        "quality": "LOW"
    }, {
        "container": "MP4",
        "contentUrl": "http://cdn-1.metacdn.net/rockettest/2BcwJI/20120601011931_trailer1080p_ogg-LOW.mp4",
        "quality": "LOW"
    }, {
        "container": "FLV",
        "contentUrl": "http://cdn-1.metacdn.net/rockettest/21rXyi/20120601011931_trailer1080p_ogg-MEDIUM.flv",
        "quality": "MEDIUM"
    }, {
        "container": "MP4",
        "contentUrl": "http://cdn-1.metacdn.net/rockettest/1WAnGL/20120601011931_trailer1080p_ogg-MEDIUM.mp4",
        "quality": "MEDIUM"
    }, {
        "container": "FLV",
        "contentUrl": "http://cdn-1.metacdn.net/rockettest/1u1XiN/20120601011931_trailer1080p_ogg-HIGH.flv",
        "quality": "HIGH"
    }, {
        "container": "MP4",
        "contentUrl": "http://cdn-1.metacdn.net/rockettest/29gYE9/20120601011931_trailer1080p_ogg-HIGH.mp4",
        "quality": "HIGH"
    }],
    "encodingStatus": "INITIATING",
    "hostUntil": "10 Sep 2011 08:00:25 GMT",
    "locations": ["CDN"],
    "mediaBrandingTemplateName": "Default",
    "mediaKey": "56IX9R",
    "mediaName": "trailer_1080p_ogg",
    "mediaStatus": "INITIATING",
    "mediaUserString": "rockettest",
    "createdTime": "12 Sep 2012 03:13:36 GMT",
    "metaCdnUrl": "http://www.metacdn.com/r/m/5RJhVGiSZO/56IX9R",
    "originUrl": "http://www.metacdn.org/trailer_1080p.ogg",
    "splashScreenUrl": "http://www.metacdn.com/img/splash/splash.png",
    "tags": [
        "trailer",
        "bunny"
    ],
    "title": "You've seen it before...  Trailer_1080p.ogg",
    "fileSize": 12854775
}

HTTP Operation:GET
URL: GET http://api.metacdn.com/api/users/{username}/media/{mediakey}/{style}/{quality}/{player}/{container}
Auth: None
"Accept" header: text/plain, text/html
Expected HTTP response: HTTP/1.1 200 OK
Expected Format (mandatory, optional):

GET /api/users/{username}/media/{mediakey} HTTP /1.1
Accept: text/plain, text/html

Example Call #2:

GET /api/users/jbroberg/media/56IX9R HTTP /1.1
Accept: text/plain, text/html

Notes:

• The "Accept" header is set automatically by the user's browser and can vary depending on the browser type (Firefox, Internet Explorer, Safari, Chrome, etc).
• Style is one of FULL, EMBED, CONFIG
• "FULL" - full, standalone html origin page (default)
• "EMBED" - nested object/embed tags
• "CONFIG" - external javascript config for embedded flash player (e.g. embed or facebook)
• By default, MetaCDN attempts to deliver the Media content by deliving the full page and auto-detecting the optimal quality (MOBILE, LOW, MEDIUM, HIGH or XHIGH), player (FLASH, HTML5 or NATIVE) and media container (OGV, MP4, WEBM, WEBM_VP9, WEBM_VP9_DASH, 3GP, FLV, MP3, OGG)
• Alternatively, "style", "quality", "player" and "container" can be optionally specified to force a particular delivery mechanism. If used, these must be set in an incremental fashion, such as /{style}, /{style}/{quality}, /{style}/{quality}/{player}, or /{style}/{quality}/{player}/{container}
• If the media does not have a "hostUntil" (expiry) date, that field will not be present in the response.

Expected Response #2:

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Mon, 12 Sep 2011 07:08:36 GMT
Server: Google Frontend
Cache-Control: private, x-gzip-ok=""
Transfer-Encoding: chunked
<html>
<head>
<title>You've seen it before...  Trailer_1080p.ogg</title>
.
.
.
</html>

Get medias

HTTP Operation:GET
URL: GET https://secure.metacdn.com/api/users/{username}/media
URL: GET https://secure.metacdn.com/api/users/{username}/media/includeEncodeInfo/{includeEncodeInfo}
URL: GET https://secure.metacdn.com/api/users/{username}/media/size/{pageSize}
URL: GET https://secure.metacdn.com/api/users/{username}/media/size/{pageSize}/includeEncodeInfo/{includeEncodeInfo}
URL: GET https://secure.metacdn.com/api/users/{username}/media/size/{pageSize}/cursor/{cursor}
URL: GET https://secure.metacdn.com/api/users/{username}/media/size/{pageSize}/cursor/{cursor}/includeEncodeInfo/{includeEncodeInfo}
Auth: HTTP digest authentication (User)
"Accept" header: application/json
Expected HTTP response: HTTP/1.1 200 OK
Example Call #1:

GET /api/users/rockettest/media/size/20/cursor/CiMSHWoOR0FURVdBWV9BUFBfSURyCwsSBU1lZGlhGGQMGAAgAA HTTP/1.1
Accept: application/json

Notes:

• When not specified, the default return page size is 50.
• When includeEncodeInfo set to true, the result will include each sub-encoding content. Due to the large size of encode info, the response will take longer to load. When not specified, the default response will not include encode info.
• For initial query, the cursor is empty. Cursor will be returned as part of the response body of your initial query for subsequent requests.

Expected Response:

HTTP/1.1 202 Accepted
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language. Accept
Date: Tue, 16 Dec 2014 07:11:20 GMT
Content-Type: application/json
Content-Length: 6734 {
    "cursor": "CiMSHWoOR0FURVdBWV9BUFBfSURyCwsSBU1lZGlhGG4MGAAgAA",
    "size": 20,
    "medias": [
        {...},
        ...
        {...}
    ]
}

Update media

HTTP Operation: PUT
URL: PUT https://secure.metacdn.com/api/users/{username}/media/{mediakey}
Auth: HTTP digest authentication (User)
"Content-Type" header: application/json
Expected HTTP response: HTTP/1.1 202 Accepted
Expected Format (mandatory, optional):

PUT /api/users/{username}/media/{mediakey} HTTP/1.1
Content-Type: application/json {
    "outputFormats": ["FORMAT1", ..., "FORMATN"],
    "quality": ["Q1", "Q2", ..., "QN"],
    "hostUntil": "DD Mon YYYY HH:MM:SS GMT",
    "tags": ["TAG1", "TAG2", ..., "TAGN"],
    "description": "",
    "title": "",
    "mediaBrandingTemplateName": "",
    "refreshOrigin": true/false,
    "captionUrl": "",
    "splashScreenUrl": ""
}

Notes:

• To remove a media's expiry date, set the "hostUntil" value of an update request to an empty string.
• To refresh (reload) media from its existing "originUrl", set the "refreshOrigin" value to true. Note that this will cause the video to be reprocessed (i.e. re-encoded).

Example Call #1:

PUT /api/users/test/media/56IX9R HTTP/1.1
Accept: application/json {
    "outputFormats": ["WEBM","WEBM_VP9", "WEBM_VP9_DASH", "OGV","MP4"],
    "quality": ["LOW"],
    "hostUntil": "06 Nov 2012 08:49:37 GMT",
    "tags": ["Hello"],
    "title": "New Title",
    "description": "New Description"
}

Expected Response #1:

HTTP/1.1 202 Accepted
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language. Accept
Date: Mon, 12 Sep 2011 07:11:20 GMT
Content-Type: text/html
Server: Google Frontend
Media is updating

Delete media

HTTP Operation: DELETE
URL: DELETE https://secure.metacdn.com/api/users/{username}/media/{mediakey}
Auth: HTTP digest authentication
Expected HTTP response: HTTP/1.1 202 Updated
Expected Format (mandatory, optional):

DELETE /api/users/{username}/media/{mediakey} HTTP/1.1

Example Call #1:

DELETE /api/users/test/media/56IX9R HTTP/1.1

Expected Response #1:

HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=UTF-8
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Mon, 12 Sep 2011 07:11:20 GMT
Server: Google Frontend
Cache-Control: private, x-gzip-ok=""
Transfer-Encoding: chunked
Media scheduled for deletion

Get Media by Tag

HTTP Operation: GET
URL: GET https://secure.metacdn.com/api/users/{username}/media/tags/{tag}/size/{size}/cursor/{cursor}
Auth: HTTP digest authentication
Expected HTTP response: HTTP/1.1 200 OK
Expected Format (mandatory, optional):

GET /api/users/{username}/media/tags/{tag}/size/{size}/cursor/{cursor} HTTP/1.1

Example Call:

GET /api/users/test/media/tags/mytag HTTP/1.1

GET /api/users/test/media/tags/mytag/size/10 HTTP/1.1

GET /api/users/test/media/tags/mytag/size/5/cursor/E-ABAOsB8gELY3JlYXRlZFRpbWX6AQkImP6HyPDbugLsAYICIGoPc355dWRvbmdtZXRhY2Rucg0LEgVNZWRpYRjR4TgMiAIBFA HTTP/1.1

Expected Response:

HTTP/1.1 200 OK
{"size":1,"medias":[{"description":"asf","tags":["aaa","bbb6"],"title":"asd","mediaType":"VIDEO","inCompleteStatus":false,"createdTime":1384143556575,"mediaKey":{"name":null,"parent":null,"id":930001,"namespace":"","kind":"Media","appId":"s~yudongmetacdn","complete":true},"hostUntil":null,"mediaBrandingTemplateName":"Default","containers":["MP4"],"mediaCaptionUrl":"","mediaStatus":"ERROR","mediaUserString":"fcihaf","mediaName":"cdsa_jsp","encodingStatus":"FAILED","mediaCaptionKey":null,"duplicates":true,"encodeInfo":[],"xDim":0,"xPar":0,"yDim":0,"originUrl":"http://www.sdfa.sdaf.sad/cdsa.jsp","aspectRatio":"AUTO","qualities":["MOBILE","LOW","MEDIUM","HIGH"],"mediaScreenShotKey":null,"metaCdnUrl":"http://yudongmetacdn.appspot.com/r/m/fcihaf/15ViIiK","splashScreenUrl":"Use Screenshot","splashScreenKey":null,"locations":["CDN"],"fpEscapedTitle":"asd","mediaScreenShotUrl":"","yPar":0,"xDar":0,"yDar":0,"bitrate":0,"fps":0.0,"audioCodec":null,"audioSampleRate":0,"audioBitRate":0,"failureTimes":0,"contentSizeTotal":null,"totalReads":null,"duration":0,"fileSize":0}],"cursor":"E-ABAOsB8gELY3JlYXRlZFRpbWX6AQkImP6HyPDbugLsAYICIGoPc355dWRvbmdtZXRhY2Rucg0LEgVNZWRpYRjR4TgMiAIBFA"}

Notes:

• "tag" is the tag name that you are searching on. If special characters are present in the tag, you will need to URL encode them.
• "size" is the max size of the result list returned. This along with "cursor" can be used to achieve pagination.
• "cursor" is a key string that you can use to fetch results page by page. It should be included as part of the response to fetch the next page of results.