Video API
The Video secton of the API is the most commonly used and thus the more complex element of the API, providing features to view, add, edit and remove videos from the 247 Platform.
Contents
Get
Returns the information on a video on the 247 Platform
Request URL
http://console.247platform.com/api/video/get/[video id]?sessionId=[Session ID]&userId=[Client Id]
Params: none.
Response { "response":{ "video":{ "videoId":"12345", "title":"My Live Video", "categoryId":"230", "published":"1", "thumbnailKey":"https:\/\/s3-eu-west-1.amazonaws.com\/247platform-test\/247platform-images\/42\/12345\/custom-908.png", "live":{ "formatId":"7", "enabled":true, "videoFormatSettings":{ "videoFormatId":"7", "enabled":"1", "streamName":"2c-61e-live", "requiresAuth":"1" }, "primaryStreamingDetails":{ "protocol":"rtmp", "portNumber":"1935", "publicDNS":"46.137.7.26", "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com", "application":"origin", "stream":"2c-61e-live" }, "backupStreamingDetails":{ "protocol":"rtmp", "portNumber":"1935", "publicDNS":"46.137.7.26", "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com", "application":"origin", "stream":"2c-61e-live" }, "publishString":{ "protocol":"rtmp", "portNumber":"1935", "publicDNS":"46.137.7.26", "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com", "application":"origin", "stream":"2c-61e-live" } }, "vod":{ "formatId":"9", "enabled":true, "settings":{ "protocol":"rtmp", "portNumber":"1935", "publicDNS":"46.137.7.26", "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com", "application":"vods3", "stream":"2c-61e-vod" } }, "download":{ "formatId":"8", "enabled":false } }, "code":"200", "isOk":true }, "code":"200" }
Errors
- 404 ResourceNotFound - We are unable to locate the Video ID you requested
- 400 AuthenticationRequired - Authentication is required but not provided.
Put
Create a new video on the 247 Platform.
Request URL
http://console.247platform.com/api/video/put/?sessionId=[Session ID]&userId=[Client Id]&categoryId=[Category Id]&published=[1 or 0]
Params
- `videoTitle` (required), String, Title you wish to change the video to
- `categoryId` (required), Integer, Category Id you wish to change this Video to
- `published` (required), Integer, 1 for published, 0 for not.
Response
{ "response":{ "videoId":1705, "data":{ "title":"My New Video", "categoryId":"270", "published":1, "ownerId":42 }, "clientId":42, "log":{ "formats":{ "live":"7", "vod":"9", "download":"8" }, "uniqueIdentifer":"2c-78a", "streamNames":{ "live":"2c-78a-live", "vod":"2c-78a-vod" } }, "code":"200", "message":"Video has been added.", "isOk":true }, "code":"200" }
Errors
- 400 AuthenticationRequired - Authentication is required but not provided.
- 404 ResourceNotFound - One or more of the required params where not passed.
Update
Updates the title, category and publish status of a video
Request URL
http://console.247platform.com/api/video/update/[Video Id]/?video=[JSON Object]&sesionId=[Session ID]&userId=[Client ID]
Params
- Video Id (Required), Int, ID of the video you wish to update
- `video` (Required), String, The JSON reporesentation of the details you wish to update for the video, e.g.:
{ "title":"My New Title", "categoryId":4, "published":0 }
Response
{ "response":{ "code":"200", "message":"Video Updated.", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
Authenticate
Creates an authentication record for a users' IP against a video stream, providing them the ability to watch the video. See the Embedding Your Video page on how to the response from this API call to embed secure URLs.
Request URL
http://console.247platform.com/api/video/authenticate/?ip=[Viewer IP]&streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]&returnAll=[1 or 0]&ttl=[TTL]
Params
- `ip` (Required), String, The IP address of the viewer (not of the web server, or any load-balancer), you can pass a * (asterix) which will allow any IP to connect to the video
- `streamName` (required), String, The stream name of the video you're authenticating the user to watch.
- `ttl`, Int, Seconds, how long can the video be played before the viewer needs to refresh the page to get a new authorisation. Defaults to 21600 seconds (5 hours).
- `returnAll`, Integer, 1 for returning the video source url - (allows you to use your own custom player and integration), 0 for not.
Response
{ "response":{ "clientIp":"192.168.100.1", "streamName":"aa-b1234-live", "authHash":"34ce63220112342cdb63204298788f323", "videoSource":"Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmfdsfds2NlIjoiKjJjLWI5YWE0KiIsICJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE0MDI5NDk1OTJ9fX1dfQ__&Signature=WnN3~AXC~t-hIOIJbOu61r4~DHWcKgfdsfsdttwFvryL2KZWraQefZTWsAhw~9BIbFYj-yuSyI~FKUX1f6ZSOA4MCTpsMLKqv96kO6TYs0J5JZPpgxdhvtAcnS2zIRitoUhV7zh18Zn8lmQL4fAzoiX5y-HQgqMohcNISKZpfjuwG7F2LXvtqfqAFlkLn3P74UI2aUSk0P1GP3TsUX3wc3I8PJUGSTRb5X5R6NezISQ7Te1Mf9YZNA4VE5bHDFy3mtDq7x5TXemSf5hHybu~2MOau0YEZp9-M1GoSfCsPxC6~Z4WVsErbu1gTvMVuIOAlvmSQvqXR2BgpsFShzH-3PS9cQ6Oo~A__&Key-Pair-Id=APKAII5FS2T7S2UQ4YHQBARA", "code":"200", "isOk":true } }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
Status
Returns the status of the video, so that it can be used to check the video's status before embedding the player, and handle errors in your own fashion.
Request URL
http://console.247platform.com/api/video/status/?streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]
Params
- `streamName` (Required), String. the stream name of the video you wish the status of.
- `ip` (optional), String, The viewers IP address, required if you wish to include a Geoblocking check against the user in the response.
Response
{ "response":{ "video":{ "live":true, "original":"2c-61e-live", "uniqueIdentifer":"2c-61e", "simpleName":"2c-61e-live" }, "errors":[
], "code":"200", "isOk":true }, "code":"200" }
Possible Responses
The `errors` array can contain a number of possible keys and descriptions:
- COM_PLATFORM247_EMBED_ERROR_NOTEXIST : The video doesn't exist
- COM_PLATFORM247_EMBED_ERROR_VIDEONOTPUBLISHED - The video hasn't been published.
- COM_PLATFORM247_EMBED_ERROR_CATEGORYNOTPUBLISHED - The category (or one of the parent categories) of this video hasn't been published.
- COM_PLATFORM247_EMBED_ERROR_VIDEONOTENABLED - The requested format hasn't been abled for this video.
- COM_PLATFORM247_EMBED_ERROR_GEOBLOCKED - The video has been geoblocked for the given IP address
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
Delete
Deletes any physical objects for a video such as recordings and thumbnails, does not remove the video from the 247 Platform to ensure you continue to have access to log information.
Request URL
http://console.247platform.com/ap/video/delete/[Video Id]/?deleteThumbs=[deleteThumbs]
Params
- Video Id (Required), Integer, The Video ID that you're trying to delete
- `deleteThumbs`, Integer, 1 or 0, if you wish to delete an thumbnail images also.
Response
{ "response":{ "code":"200", "message":"VOD has been deleted.", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
isPublishing
Returns the connection status of the streams required to publish the live stream. For videos using more than one bitrate, it will return each individual required stream with it's own publishing status.
Request URL
http://console.247platform.com/api/video/ispublishing/?streamname=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]
Params
- `streamName` (reqired) String - Stream name to verify
Response
{ "response":{ "isPublishing":{ "isPublishing":{ "1":{ "name":"platform-example-270p-500", "publishing":1, "streamName":"2c-61e-live-1" }, "2":{ "name":"platform-example-360-1000", "publishing":1, "streamName":"2c-61e-live-2" }, "3":{ "name":"platform-example-360-1500", "publishing":0, "streamName":"2c-61e-live-3" }, "4":{ "name":"platform-example-540-2500", "publishing":0, "streamName":"2c-61e-live-4" }, "5":{ "name":"platform-example-576-3500", "publishing":0, "streamName":"2c-61e-live-5" } }, "publishingOk":0 }, "timeoutSeconds":60, "code":"200", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
UploadFormParams
Returns parameters required to host your own upload form for transferring files to an Amazon S3 Folder so that they can be transcoded through the 247 Platform.
Request URL
http://console.247platform.com/api/video/uploadformparams/?sessionId=[Session ID]&userId=[Client ID]
Response
{ "response":{ "policy":"eyJleHBpcmF0aW9uIjogIjIwMTMtMDYtMjBUMDk6MTE6MTlaIiwiY29uZGl0aW9ucyI",
"signature":"KtzHA6RoypairnKrOsiY8UVadRFbsrM=", "AWSAccessKeyId":"dKtzsHA6eRoywpainqKrOieY8UVdRFbrM", "s3BucketName":"247platform-test", "key":"users\/635\/uploads\/${filename}", "scriptUrl":"http:\/\/247platform-test.s3.amazonaws.com\/" "code":"200", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
Usage
Once you have the parameters above you can host your own upload form, we use the jQuery plugin 'uploadify' to implement our upload form. An example of an implementation with uploadify: http://www.flynsarmy.com/2011/03/upload-to-amazon-s3-with-uploadify/
Using the parameters in the example response above you would fill in the gaps as so:
<script type="text/javascript"> $(document).ready(function() { $("#file_upload").uploadify({ 'uploader' : '<?= WEBROOT ?>files/uploadify/uploadify.swf', 'buttonText' : 'Browse', 'cancelImg' : '<?= WEBROOT ?>files/uploadify/cancel.png', 'script' : '<?=$this->apiResponse->scriptUrl ?>', 'scriptAccess' : 'always', 'method' : 'post', 'scriptData' : { "AWSAccessKeyId" : "<?=$this->apiResponse->AWSAccessKeyId ?>", "acl" : "authenticated-read", "policy" : "<?=$this->apiResponse->policy ?>", "signature" : "<?=$this->apiResponse->signature ?>", "success_action_status" : "201", "key" : "<?=$this->apiResponse->key ?>", "fileext" : "", "Filename" : "" }, 'fileExt' : '*.*', 'fileDataName' : 'file', 'simUploadLimit': 2, 'multi' : true, 'auto' : true, 'onError' : function(errorObj, q, f, err) { console.log(err); }, 'onComplete' : function(event, ID, file, response, data) { console.log(file); } }); }); </script>
ListVideosByCategory
List your videos for a specified optional list of categoryids
Request URL
http://console.247platform.com/api/video/listvideosbycategory/?sessionId=[Session ID]&userId=[Client Id]&categoryIds=[Category Ids]
Params
- `categoryIds` (optional), String, List of categories to pull videos for, format required is 1-2-3-4 (each category separated by a dash) if no category is specified we return all your videos
Response
[ { "videoId":"9", "title":"test", "categoryId":"98", "published":"-2", "formats":[ { "title":"Live Flash", "videoFormatId":"7", "isLive":"1", "isVod":"0", "isDownload":"0", "published":"1" } ] }, { "videoId":"10", "title":"test", "categoryId":"98", "published":"1", "formats":[ { "title":"VOD Flash", "videoFormatId":"9", "isLive":"0", "isVod":"1", "isDownload":"0", "published":"1" } ] }, { "videoId":"11", "title":"vide 2", "categoryId":"98", "published":"1", "formats":[ { "title":"Live Flash", "videoFormatId":"7", "isLive":"1", "isVod":"0", "isDownload":"0", "published":"1" }, { "title":"VOD Flash", "videoFormatId":"9", "isLive":"0", "isVod":"1", "isDownload":"0", "published":"1" } ] } ]
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
ListViewers
Returns a list of users who are viewing a particular stream in the last 10 minutes.
Request URL
http://console.247platform.com/api/video/listviewers/?streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]
Params
- `streamName` (reqired) String - Stream name to verify
Response
{ "response":{ "viewers":{
{ "ipaddress":"78.129.148.101", "country_name":"United Kingdom", "city_name":"London" }, { "ipaddress":"94.197.127.197", "country_name":"United Kingdom", "city_name":"London" }, }, "code":"200", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
RemoveAuth
Disconnect a user from viewing a stream.
Request URL
http://console.247platform.com/api/video/removeauth/?streamName=[Stream Name]&ipAddress[IP Address]&sessionId=[Session ID]&userId=[Client ID]
Params
- `streamName` (required) String - Stream name to verify
- `ipAddress` (required) String - IP to disconnect
Response
{ "response":{ "code":"200", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- ResourceNotFound (code 404), One or more of the required params where not passed.
- InternalError (code 500) The stream was not found or the user was found to not be watching the stream anymore
Download
Creates signed URLs so VOD content can be downloaded from the 247 Platform.
Request URL
http://console.247platform.com/api/video/download/?filename=[Video File NAme]&sessionId=[Session ID]&userId=[Client ID]
Params
- `filename` (required), String - The VOD file name, eg. ab-12345-6-720-1280-5000.mp4 ( How to find your Video Download file name )
Response
{ "response":{ "link":"https://247platform-test.s3.amazonaws.com/users/99/588897/3/ab-12345-6-720-1280-5000.mp4?AWSAccessKeyId=AASO4WRSSEIJAWDA&Expires=1395142829&Signature=afEmzVSLsdurssaSlvAYmg%2Bjj3ytM%3D", "TTL":"300" }, "code":"200" }
Create Viewer Login Credential
Creates a login credential for the viewer to watch the video
Request URL
http://console.247platform.com/api/video/createviewercredential/[Video Id]/?password=[Password]&email=[Email]&liveEnabled=[Live Enabled]&vodEnabled=[Vod Enabled]&downloadEnabled=[Download Enabled]&sesionId=[Session ID]&userId=[Client ID]
Params
- Video Id (Required), Int, ID of the video you wish to create a login credential for
- Email (Required), String, The email address of the viewer
- Password (Required), String, A password for the viewer
- Live Enabled , Int, Is the live video to be enabled under this credential
- Vod Enabled , Int, Is the vod video to be enabled under this credential
- Download Enabled , Int, Is the download video to be enabled under this credential
Response
{ "response":{ "code":"200", "message":"Credential Created.", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- MissingRequiredQueryParameter (code 400), One or more of the required params where not passed.
- FailedToPerformAction (code 400), Failed to Perform the Action.
Delete Viewer Login Credential
Delete a login credential
Request URL
http://console.247platform.com/api/video/deleteviewercredential/[Video Id]/?email=[Email]&sesionId=[Session ID]&userId=[Client ID]&videoName=[Video Name]
Params
- Video Id (Required), Int, ID of the video you wish to delete a login credential for
- Email (Required), String, The email address of the viewer
- Video Name (Required), String, The video name to delete credential for - eg: 4d-564-vod or 4d-564-live
Response
{ "response":{ "code":"200", "message":"Credential Deleted.", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- MissingRequiredQueryParameter (code 400), One or more of the required params where not passed.
- FailedToPerformAction (code 400), Failed to Perform the Action.
Viewer Statistics
Retrieve the viewing stats for a video. The duration stats will only show for any views recorded after 11th July 2014
Note: the uid field below can be set using the embed url parameter "uid" as below, if you do not specify the uid then we will set the uid to the value of a cookie which is placed on the viewers device (1 yr expiration cookie) - this cookie value stays the same when the viewer navigates to different videos.
http://console.247platform.com/embed/?v=4d-355-vod&uid=1234
Request URL
http://console.247platform.com/api/video/viewerstats/[Video Id]/?sesionId=[Session ID]&userId=[Client ID]
Params
- Video Id (Required), Int, ID of the video you wish to retrieve stats for
Response
{ "response":{ "statsLive":{ { "ip":"78.129.148.101", "hash":"0137o34ims1huba3d3cqc0huo1.88705831", "uid":"f123f87653e143d0810a9c8dbe2f29c9" "updated":"12-07-14 20:59:33", "created":"12-07-14 20:57:33", "userAgent":"Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36", "duration":"1258", "seeks":"1", "videoName":"2c-b9edb-live", }, { "ip":"80.215.229.114", "hash":"c52f3c6efqeu2t4ou843mjc647.46817052", "uid":"b66f6a183af2e0984478b3a331fb5f1d" "updated":"12-07-14 08:58:13", "created":"12-07-14 08:58:13", "userAgent":"Mozilla/5.0 (iPhone; CPU iPhone OS 5_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A405 Safari/7534.48.3", "duration":"0", "seeks":"0", "videoName":"2c-b9edb-live", }, }, "code":"200", "isOk":true }, "code":"200" }
Errors
- AuthenticationRequired (code 400), Authentication is required but not provided.
- MissingRequiredQueryParameter (code 400), One or more of the required params where not passed.
- FailedToPerformAction (code 400), Failed to Perform the Action.