VOD service API SOAP


  1. General information
    1. Presentation
    2. Rules of Use
    3. Variables typing
  2. Basic uses
    1. Authentication
    2. Examples
      1. Test connectivity
      2. Recover videos
      3. Recover imports
      4. Use callback
      5. Import/Send videos
      6. Token use
      7. Chapter manager
  3. Material
    1. Available functions
    2. Feedback from functions
      1. Video type
      2. Folder type
      3. Type of import
      4. Playlist type
      5. Type of player
    3. Error codes
Last update : 28 septembre 2015


1. General information

Presentation of the V.O.D. API

This API has been developped to allow the automation of the different functionalities offered by the VOD service.
It's all based on the SOAP protocol and enables you to call these functions from a distance.
Any SOAP client can be used for exchanges, but for a greater simplicity we give you examples with the one included in PHP5.

For frequent use, a Web inteface is available on the vod administration http://statslive.infomaniak.ch


Rules of Use
Be careful to read closely and respect the following rules before you start using this API
  • Infomaniak reserves the right to stop any account that makes too many calls to this API (several hundreds of calls per hour) without notice.
    We strongly advise you to call it in moderation and store the necessary information on your site.
  • We highly advise you against the use of calls to API on public pages, which may result in too many hits on days of big crowds and thus will simply block your account.
  • Functions are likely to be subjected to modifications, please check regularly the correct working order of your calls. (unit tests)
  • Please use identifiers different to those used for your user account for safety reasons.
  • The use of this API requires solid knowledge about development.
  • All actions processed by this API are logged.

Type of variable
Variables are all prefixed, to know their type :
  • i: integer
  • a: chart
  • s: chain of characters
  • d: integer in timestamp unix format
  • b: boolean
  • e: enum(in the shape of a chain of characters)

2. Utilisations de base

Authentication
In order to authenticate, you must set a Soap header AuthentificationHeader with sLogin and sPassword attributes.
Here is an example in PHP5 : See example

Examples These examples all use the $oSoap object, please go to the Authentication section to find its setting.

1 - Checking API works correctly
This example shows you how to check that the API is operational and that the identifiers submitted are correct.
See example

2 - Video recovery via API
This example will show the names of the last 25 videos of the VOD space.
See example

3 - Recoveries of imports via API
This example will show the names of the last 25 video imports of the VOD space.
See example

4 - Use of callback
The callback isn't linked to the API, however they can easily be used jointly (importing or sending of new videos).
The page you have specified in the admin (Setup > API and Callback page) will automatically be called for each new video. You just need to recover the parameters switched to this page and process them.

Here is an example of parameters received by the callback address: See example

You just need to go through the parameters to process them as you wish.
Here is an example to send an email for each new video : See example

5 - Sending and import of new videos
The sending and upload functions are very often requested. There are 4 different ways of sending new files :
  • Through API via flash module
    Avantage : Simple d'utilisation et visuelement attrayant avec la presence de barres de progressions.
    Inconvenient : Requiert l'utilisation de Javascript et flash.
    Example of use : Voir l'exemple
  • Through API via an HTML form
    Avantage : Simple et compatible avec un grand nombre de solution. Se base uniquement sur HTML et HTTP.
    Inconvenient : Peut attrayant pour l'utilisateur.
    Example of use : See example
  • Per FTP
    Avantage : Simple d'utilisation et evite l'utilisation d'un navigateur internet
    Inconvenient : Necessite un client FTP
    Utilisation : les informations sont disponible dans l'interface d'administration.
  • Through API ask video downloading on another server (FTP or HTTP)
    Avantage : Rapide et ne consomme pas de bande passante pour l'utilisateur
    Inconvenient : Les fichiers doivent deja etre accessible sur internet
    Example of use : See example


6 - Use of token (Restriction by unique key)
This functionality offers the possibility of controlling access to a directory's videos.
Only you will be able to generate the unique key necessary for each user to view the videos located in the folder.
Get further information


7 - Chapter manager
This example shows how to change and retrieve the chapter list for a given video.
See example


3. Material

Available functions
Fonctions d'upload
  • string initUpload(string sFolderPath)
    Function allowing the initialization of a file transfer and the recovery of a token corresponding to the transaction (valid only once for 2 hours), to use for multiple uploads.
  • string initUploadSingle(string sFolderPath, string sFileName)
    Function allowing the initialization of a file transfer and the recovery of a token corresponding to the transaction (valid only once for 2 hours), to use when it's necessary to name the video.
  • boolean importFromUrl(string sFolderPath, string sUrl, anyType aOptions)
    Function allowing the import of a video from a URL, aOptions, under the shape of a chart, enables you to add extra parameters such as "filename": name of the file, "login" and "password": if the url requires an authentication.
  • boolean addInfo(string sTokenUpload, string sInfo)
    Function allowing the addition of details which will then be sent by the callback. Only use after a call at initUpload() ou initUploadSingle()
Information functions
  • array getFolderInformation(integer iFolderCode)
    Function enabling the recovery of a folder's details
  • array getFolderInformationByPath(string sFolderPath)
    Function enabling the recovery of a folder's details (such as the iFolderCode used by other functions)
  • string getDownloadUrl(integer iFolderCode, string sFileServerCode)
    Fonction permettant d'obtenir l'adresse d'une video
  • array getVideoInformation(integer iFolderCode, string sFileServerCode)
    Function enabling the recovery of a video's details
  • integer countVideosFromFolder(integer iFolderCode)
    Fonction permettant de compter le nombre de video d'un dossier
Integration functions
  • string getIFrameImplementation(integer iFolderCode, string sFileServerCode, integer iWidth, integer iHeight, integer iPlayerCode)
    Function enabling the recovery of a video's integration code by iframe
Management functions
  • string setVideoPublish(integer iFolderCode, string sFileServerCode, boolean bValue)
    Function enabling the modification of the publish status of a video (true/false)
  • string setVideoTraiter(integer iFolderCode, string sFileServerCode, boolean bValue)
    Function enabling the modification of the process status of a video (true/false)
  • boolean setVideoTitle(integer iFolderCode, string sFileServerCode, string sName)
    Function enabling the modification of a video title
  • boolean setVideoDescription(integer iFolderCode, string sFileServerCode, string sDescription)
    Function enabling the modification of details for a video
  • boolean deleteVideo(integer iFolderCode, string sFileServerCode)
    Function enabling the deletion of a video for good (doesn't go through the bin).
  • integer duplicateVideo(integer iFolderCode, string sFileServerCode, integer iNewFolderCode)
    Function enabling you to copy a video from one folder to another
  • boolean moveVideo(integer iFolderCode, string sFileServerCode, integer iNewFolderCode)
    Function enabling you to move a video from one folder to another
  • boolean setFolderExceptionIP(integer iFolderCode, string sIp)
    Fonction permettant de modifier les adresses IP non affectees par les restriction d'acces (whitelist)
  • boolean setFolderForbiddenIP(integer iFolderCode, string sIp)
    Fonction permettant de modifier les adresses IP interdites pour un repertoire (blacklist)
  • boolean setFolderGeoip(integer iFolderCode, string sCountryCode)
    Fonction permettant de changer la valeur de geoip d'un repertoire (code pays separer par des virgules, exemple : BE,FR,DE)
  • boolean setFolderToken(integer iFolderCode, string sToken)
    Fonction permettant de modifier la valeur du token d'un repertoire
  • array getChapters(integer iFileCode)
    Fonction permettant de recuperer les chapitres d'une video
  • boolean setChapters(integer iFileCode, anyType aChapters)
    Fonction permettant de modifier les chapitres d'une video
  • boolean cutVideo(integer iFileCode, integer iStart, integer iStop, boolean bCreateNew)
    Decoupage d'une video.
  • boolean cutRestore(integer iFileCode)
    Restauration d'une video decoupee (dans un delais max de 14 jours apres la decoupe).
  • integer createFolder(integer iParentFolderCode, string sFolderName)
    Creation d'un nouveau dossier, retourne l'id du dossier cree.
  • boolean removeFolder(integer iFileCode)
    Suppression d'un dossier a condition qu'il soit vide.
  • boolean importFromVod(integer iFileCode, integer iFolderCode)
    Import d'une video deja presente dans de la VOD vers un nouveau dossier specifique, cette derniere sera reencodee selon la config du nouveau dossier
  • boolean ping()
    Function enabling the test of connectivity and authentication
List functions
  • integer countVideo()
    Function enabling the recovery of the total number of videos imported
  • array getLastVideo(integer iLimit, integer iStart)
    Fonction permettant de recuperer les dernieres videos importees
  • array getVideosFromFolder(integer iFolderCode, integer iLimit, integer iStart, string sOrder, boolean bAsc, string sSearch)
    Fonction permettant de recuperer les videos d'un dossier (attention aux limites)
  • array getUpdatedVideosFromFolder(integer iFolderCode, string dDateFrom, integer iLimit, integer iStart, string sOrder, boolean bAsc, string sSearch)
    Fonction permettant de recuperer uniquement les videos mis a jour depuis une date donnee pour un dossier (attention aux limites), NB : ne fonctionne pas pour les dates anterieur au 19 aout 2014
  • array getVideoByDate(string sDate)
    Function enabling the recovery of videos imported at a given date.
  • array getLastImportation(integer iLimit)
    Function enabling the recovery of the last imported videos
  • array getAllVideoList()
    Fonction permettant de recuperer la liste de toutes les videos d'un espace vod (liste mise a jour une fois par jour entre 5h et 7h), l'URL d'un fichier json compresse qui contient cette liste est retournee.
  • array getFolders()
    Function enabling the recovery of the list of folders from a vod space
  • boolean folderModifiedSince(string date)
    Function enabling to check whether there were some modifications on the folders
  • array getPlayers()
    Function enabling the recovery of the list of players from a vod space
  • boolean playerModifiedSince(string date)
    Function enabling to check whether there were some modifications on the players
  • array getPlaylists()
    Function enabling the recovery of the list of playlists from a vod space
  • array getPlaylistInfo(integer iPlaylistCode)
    Fonction permettant d'obtenir le detail d'une playlist
  • boolean playlistModifiedSince(string date)
    Function enabling to check whether there were some modifications on the playlists

Feedback from functions :

As far as videos and imports are concerned, the functions return a list of items. The latter are formatted in the following way :

Video :
  • string sFileName : Video name
  • string sFileServerCode : Name of video file to identify it on the server
  • string sDescription : Description of file used on social networks
  • string dFileUpload : Date of upload in %Y-%m-%d format
  • integer fFileDuration : Duree de la video en centieme de seconde
  • integer iFolder: Identifier of the folder containing this video
  • integer iFileHit: Number of views on this video
  • integer iFileCode: Identifier of this video
  • array aEncodes : Table showing all the different encoding formats for this video
    • string sEncodeName : Name of coding used
    • integer iVideoSize : Weight of this coding in octet
    • integer iWidth : Video width
    • integer iHeight : Height of video
    • string sVideoURL : Encoding accessing url
    • string sImageURL : Preview image accessing url
    • string eConteneur : Container format used for this encoding (flv, mp4, ...)
    • integer iVideoBitrate : Video stream bitrate (in kbit/s)
    • integer iAudioBitrate : Audio stream bitrate (in kbit/s)
    • string eVideoCodec : Video codec used for this encoding
    • string eAudioCodec : Audio codec used for this encoding
Folder :
  • integer iFolderCode : Folder identifier
  • integer iParentCode : Parent folder identifier
  • string sFolderName : Name of folder
  • string sFolderPath : Folder path (used as FTP path for example)
  • string dCreate : Date of upload in %Y-%m-%d %H:%i:%s format
  • boolean bTraiter : Boolean allowing you to know whether videos from this directory are edited by default
  • boolean bPublish : Boolean allowing you to know whether the videos from this directory are published by default
  • string sAccess : Allows you to know whether the directory is open to all (ALL) or geolocalized (country code: CH, FR, BE)
  • string sToken : chain of characters used during unique key restriction
Importation :
  • string sFileName : Name of video file
  • integer iSize : Weight of file in octet
  • integer iDuration : Duree de la video en centieme de seconde
  • string sProcessState : Allows to get the satuts of the video
  • string eErrorState : In case of error, ensures to find its origin
  • string dDateCreation : Date of upload in %Y-%m-%d format
Playlist :
  • integer iPlaylistCode: Playlist identifier
  • string sPlaylistName: Name of playlist
  • string sPlaylistDescription: Description used on social networks
  • integer iTotal: Number of videos contained in the playlist
  • integer iTotalDuration: Length of playlist
  • string sMode: Playlist reading mode ('normal', 'live', 'sequence')
  • string dCreated: Playlist creation date
  • array aVideos: Contains a list of videos in a playlist (only for getPlaylistInfo(), see below for details)
    • integer iPosition: Position of the video on the playlist
    • integer iFileCode: Video ID
    • string sFileName: Name of video file
    • integer fFileDuration: Duree de la video en centieme de seconde
    • integer iFolder: ID of the folder where the video is located
    • string sUrlVideo: Link to video
    • string sUrlImage: Link to the image associated with this video
    • string sUrlImageMini: Link to the thumbnail image (200x120) associated with this video
Player :
  • integer iPlayerCode: Player identifier
  • string sName: Player name
  • integer iWidth: Player width
  • integer iHeight: Height of player
  • integer bAutoStart: Automatic launch of video at player download
  • integer bLoop: Loop playback
  • integer bSwitchQuality: Option enabling to change the quality of the video when playing
  • string dEdit: Date of player's last modification


Error code
Error are returned with exceptions. The format of error is CCC-Message where CCC is the error code
Here is the list of code :
  • 0 : No Error
  • 2 : General error
  • 100 : General command error
  • 200 : No Video during this interval
  • 201 : This folder doesn't exist
  • 202 : This fileServerCode doesn't exist
  • 203 : This fileServerCode already exist
  • 900 : Authentification is needed
  • 901 : SSL Required
  • 902 : Bad login or password
  • 903 : This Vod doesn't exist
  • 904 : This user don't have the right to use this API
  • 905 : Access to API is disabled or IP is not allowed
  • 906 : Not allowed to do requested action