Getting Started with the Developer API

SVP API for Video Publishers

Concept

The purpose of the SVP API for video publishers is to provide web video publishers with a clear and reliable server to server communication interface through which their applications are able to publish video online. This interface provides automated means for nearly all functionality there is in the SVP panel.

From SVP perspective an API publisher is any SVP user that has a valid API KEY/API CODE pair associated with their account. Each publisher may implement any part of this API interface in their own application/website depending on their needs.

The API is implemented as a set of web services and notification callbacks that receive a standard HTTP request(GET/POST) and return structured response in the form of XML response.

The API services allow for the following:

1. Uploading new video files to the platform – video uploads to the platform are realised through an asynchronous FTP/HTTP pull operation through a source predefined by the publisher.

NOTE: This API is intended for a diverse set of requirements. For performance reasons we recommend any heavy load applications/sites to cache all of the needed data with their own service. Then update the local copy of the data when change notifications are received.

Authentication

All service calls through this API require authentication. Authentication is achieved through API Key / API Code pair provided by the SVP panel at Account > Integration > API Access.
The API key/API code pair is used with the svp_auth_get_token service to obtain an authentication token.

Error handling

All errors are returned in the form:

<response>

<result >ERROR</result>

<code >xxxx</code>

<message >Error message here</message>

</response>

Success responses are described per each service bellow.

NOTE: The error messages returned are "error class" messages. For actual detailed error messages look at Appendix 1 in this document.

Notifications

Server to server notifications are available as part of this API. These notifications are calls from the SVP platform to publisher's defined callback address(URL) that allow publishers to react on changes in your associated data. For further information about notification messages please look at Appendix 2 in this document.

Video services list:

1 . svp_auth_get_token

Description:

Retrieves an authentication token for further use with all other API service calls.

Notes:
The authentication token has a meaning similar to session ID. The lifetime of the authentication token is currently 48h. If the service is been accessed with valid token within this time, the validation period will be renewed.

parameter

description

api_key *

Your publisher API Key.

api_code *

Your publisher API Code.

token

Valid API authentication token.

Returned data:

Authentication token code or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<auth_token>xxxxxxxxxxxxxxxxx</auth_token>

</response>

2 . svp_upload_video

Description:

Books an upload of a video file from one of the predefined publisher locations.

Notes:
This is a synchronous service call that books an asynchronous upload and returns immediately! Actual file pull will start asynchronously from a separate server and may take some time. Do not delete the video file immediately, wait for a notification or do so with a clean up scheduled job on your server, in an hour for example!

NOTE: Max 8.00 GB file size allowed.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

upload_location_ref *

The reference ID of the upload location from which the files would be pulled into the streaming CDN. Take a look at svp_list_upload_sources service for information how to get reference IDs dynamically.

file_name *

Video resource file name without path. Example:myvideo.mp4

whitelabel

WhiteLabel SVP video destination. Available values: yes & no (default). If value is yes you can re-brand this kind of player and insert your own logo or text (watermark).
NOTE: If video file is registered under channel playlist and whitelabel parameter is not present, video destination will be established from default branding option in the channel.

video_title

Title to be associated with this video in the video list.

tag_number

Integer user data. May be used at publisher's discretion. For example category or internal user ID.

tag_string

String(100) user data. May be used at publisher's discretion. For example tagging information.

channel_ref

TV or PPV channel under which the video is to be associated with. Useful if you need to publish videos in a TV or PPV channel automatically. Take a look at svp_list_channels service for information how to get reference IDs dynamically.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

Video reference code and key or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<ref_no>xxxx</ref_no>

<video_key>xxxx</video_key>

</response>

3 . svp_list_videos

Description:

Returns a list of videos based on the search/filtering criteria passed with the parameters.

Notes:
Stream name parameter in video list is present only when video source is live video feed.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

tag_number

Integer user data filtering. You can filter the results based on the tag_number associated with the video. The comparison is for exactness. The tag_number can be set by svp_upload_video and svp_set_video_property services.

tag_string

String user data filtering. You can filter the results based on the tag_string associated with the video. The comparison is for inclusion(Like '%val%'). The tag_string can be set by svp_upload_video and svp_set_video_property services.

title_search

Filter based on video titles. Useful for searching. The comparison is for inclusion(Like '%val%'). The title of the video can be set by svp_upload_video and svp_set_video_property services.

start_ref_no/end_ref_no

Filter returned videos by reference IDs start and end range.

from_date_created / to_date_ created

Filter returned videos by date_created from and to range.

from_date_modified / to_date_modified

Filter returned videos by date_modified from and to range.

start/limit

Filter returned videos by result set row numbers start and end range. Same as MySQL "Limit start,limit".

Filter results in ascending or descending order based on order_by field. Available values:asc: Ascending order;desc: Descending order.
By default asc order is applied.

video_source

Each video is linked to a specific video source - on-demand video file or live video feed. You can filter the results based on the video source. Available values: ondemand & live.

count_only

Returns only total count of videos based on search/filtering criteria.

NOTE: Video list is not present in response.

channel_ref

TV or PPV channel under which the video is to be associated with. Useful if you need to publish videos in a TV or PPV channel automatically. Take a look at svp_list_channels service for information how to get reference IDs dynamically.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

A list of videos or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xx</count>

<timestamp>xx</timestamp>

<filters>

<tag_number>xx</tag_number>

<tag_string>xx</tag_string>

<title_search>xx</title_search>

<start_ref_no>xx</start_ref_no>

<end_ref_no>xx</end_ref_no>

<from_date_created>xx</from_date_created>

<to_date_created>xx</to_date_created>

<from_date_modified>xx</from_date_modified>

<to_date_modified>xx</to_date_modified>

<start>xx</start>

<limit>xx</limit>

<channel_ref>xx</channel_ref>

<video_source>xx</video_source>

</filters>

<video_list>

<video>

<ref_no>1</ref_no>

<video_key>xxx</video_key>

<title>My video #1</title>

<tag_number>1000</tag_number>

<tag_string></tag_string>

<video_source>ondemand/live</video_source>

<stream_name>xxx</stream_name>

<channel_ref>xxx</channel_ref>

<duration>xxx</duration>

<date_created>xxx</date_created>

<date_modified>xxx</date_modified>

</video>

...

</video_list>

</response>

4 . svp_delete_video

Description:

Deletes the specified video from the system.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

All editable properties of the given video or error code if error occurs. For further information about editable video properties please look at Appendix 4 in this document.

Example success response:

<response>

<result>OK</result>

<video_properties>

<property>

<id>X</id>

<name>XXX</name>

<value>XXX</value>

</property>

...

</video_properties>

</response>

6 . svp_set_video_property

Description:

Modifies a property value.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID.

property_id *

Property ID received from svp_get_video_properties. For further information about editable video properties please look at Appendix 4 in this document.

new_value *

New Value for the property.

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

7 . svp_get_video_stats_detail

Description:

Returns a list of video viewer statistics. The data includes all individual views.

Notes:

Detail statistics are available for 3 months. For older data only daily statistics are available.
The data amount can be quite large thus number of nodes returned is limited to 100,000! Make a second call with a start_row parameter set in order to retrieve further data.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

start_time *

Start date/time for the requested statistics. Unix time stamp(integer) format.NOTE: Only 3 months ago is supported for the start time.

end_time *

End date/time for the requested statistics. Unix time stamp(integer) format.

start_row

Starting row for the result set. i.e. how many rows are skipped from the start.

limit

Maximum number of rows to return. Can be at most 100,000. If a higher value is set it is assumed 100,000.

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xxxxx</count>

<stats>

<stat>

<time>xxxxxxxxxx</time>

<ip>1.2.3.4</ip>

<country>GB</country>

<streams>1</streams>

</stat>

...

</stats>

</response>

8 . svp_get_video_stats_daily

Description:

Returns a list of video viewer statistics. The data is aggregated per day.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

start_time *

Start date for the requested statistics. Unix time stamp(integer) format.NOTE: If there is no records between given start date and date of first video statistics, start date will be made equal to first date.

end_time *

End date for the requested statistics. Unix time stamp(integer) format.NOTE: If there is no records between given end date and date of last video statistics, start date will be made equal to last date.

start_row

Starting row for the result set. i.e. how many rows are skipped from the start.

limit

Maximum number of rows to return. Can be at most 100,000. If a higher value is set it is assumed 100,000.

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xxxxx</count>

<stats_daily>

<stat_day>

<date>xxx</date>

<views>xxxxx</views>

<streams>yyyy</streams>

</stat_day>

...

</stats_daily>

</response>

9 . svp_list_upload_sources

Description:

Lists publisher's upload sources. The upload locations are servers owned by the publisher where the video files have been uploaded through any means. These locations are configured in the SVP panel. To get to the upload sources screen follow these menus: Account > Integration > Upload Sources

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

source_type

You can filter the results based on the upload source type. Available values: ftp & http.

Returned data:

List of upload sources or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xx</count>

<filters>

<source_type>ftp/http</source_type>

</filters>

<upload_source_list>

<upload_source>

<ref_no>1</ref_no>

<name>My upload source #1</name>

<source_type>ftp/http</source_type>

</upload_source>

...

</upload_source_list>

</response>

10 . svp_list_users

Description:

This service is intended for resellers. It allows to get a list of SVP users that are registered under the reseller. The user reference Ids can then be used to upload or list videos associated with the given user.

Notes:

Users are shown in the SVP panel at Reseller > View Clients

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

login_name

Login name data filtering. You can filter the results based on the login_name associated with the user. The comparison is for inclusion(Like '%val%').

user_name

User name data filtering. You can filter the results based on the user_name associated with the user. The comparison is for inclusion(Like '%val%').

Returned data:

List of reseller's users or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xx</count>

<user_list>

<user>

<ref_no>1</ref_no>

<user_name>Test User Name</user_name>

<login_name>Test Login Name</login_name>

</user>

...

</user_list>

</response>

11 . svp_list_channels

Description:

Returns a list of TV/PPV channels associated with publisher's account.

DEPRECATED: This service is no longer relevant. Please use service “svp_list_playlists”.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

channel_type

Filter channel playlists by type. Available values: tv & ppv.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

List of publisher's channels or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xx</count>

<filters>

<channel_type>tv/ppv</channel_type>

</filters>

<channel_list>

<channel>

<ref_no>1</ref_no>

<title>My TV/PPV channel #1</title>

<channel_type>tv/ppv</channel_type>

</channel>

...

</channel_list>

</response>

12 . svp_list_player_templates

Description:

Returns a list of player embed code templates that the publisher has saved for further use.

13 . svp_get_player_code

Returns a embed code for publishing. This service can be used for automated code generation in publisher's own website/application.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_key

Video key. See svp_list_videos service.

video_ref *

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

param_overrides

Name-Value-Pair list of override template parameters. The NVP data must be URL encoded (each value of NVP string must be URL encoded too). See Appendix 3 for more information.

embed_type *

The type of code to be generated. Available values: js_embed, popup, popin, player_link, object & transparent.

template_ref *

Reference code of embed code template that you have saved from SVP platform. NOTE: If you pass a valid template reference code the embed_type* parameter is not necessary(It will be replaced with embed type associated with given template reference code)

You need to pass either embed_type or a valid template reference ID! You may pass a video_key or video_ref to get embed code ready for.

Returned data:

HTML code for embedding or error code if error occurs. The code is returned as base64 encoded string value in order to preserve formatting.

NOTE!!! If you do not pass a video key or a video reference code the returned code will have the string %clip_key% as a placeholder for a valid video key (also %title% for pupup embed type). In that case you need to replace that placeholder with a valid video key to get a working embed code! This may be used to publish arbitrary videos automatically with the same video code.

Example success response:

<response>

<result>OK</result>

<embed_code_html>

K0F483ABX==

</embed_code_html>

</response>

14 . svp_get_streams_amount

Description:

Returns the current streams (VP) credits amount with the SVP platform. May be used for custom tracking or notifications.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

VP account information or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<streams_account>

<account_status>Active/Locked</account_status>

<total_streams>xxxx</total_streams>

<monthly_streams>xxxx</monthly_streams>

<renewal_streams>xxxx</renewal_streams>

<renewal_date>dd/mm/yyyy</renewal_date>

<additional_streams>xxxx</additional_streams>

</streams_account>

</response>

15 . svp_list_video_images

Description:

Returns a list of images associated with publisher's videos.

Notes:

The lifetime of the image name is currently 48h. You can obtain video image content within this time (See service svp_get_video_image).

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

List of video images or error code if error occurs. Parameter name is autogenerated and it is intended for using with service svp_get_video_image. Parameters image_url and thumb_url could be used for retrieving direct URL to video image and thumbnail. Parameter extension is image file extension (jpg, gif, png, etc.) – you can use it for properly saving of image files on your local environment. Parameter primary shows if image in list is marked as startup video image (available values – yes/no).

Example success response:

<response>

<result>OK</result>

<count>xx</count>

<image_list>

<image>

<number>1...4</number>

<name>xxx</name>

<image_url>xxx.jpg</image_url>

<thumb_url>yyy.jpg</thumb_url>

<extension>jpg,gif,png...</extension>

<primary>yes/no</primary>

</image>

...

</image_list>

</response>

16 . svp_get_video_image

Description:

Displays video image associated with some of publisher's videos.

Notes:

You have to store video image content in your local environment. The lifetime of generated image names is currently 48h (See service svp_list_video_images), so after that time this service won't be able to display the image.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

image_file *

Image file name. See svp_list_video_images service.

type

Type of displayed image. With this parameter you can obtain thumb or large video image. If this parameter is not passed, the service displays large video image. Available values: thumb, large

Returned data:

Video image content or error code if error occurs.

17 . svp_get_primary_video_image

Description:

Displays video image associated with some of publisher's videos.

Notes:

You have to store video image content in your local environment.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

type

Type of displayed image. With this parameter you can obtain thumb or large video image. If this parameter is not passed, the service displays large video image. Available values: thumb, large

Returned data:

Video image content or error code if error occurs.

18 . svp_set_video_image

Description:

Set video image associated with some of publisher's videos.

Notes:

If video image already exists it will be replaced with new image.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

number *

Image number (must be between 1 and 4). See svp_list_video_images service.

Type of setting video image. Image can be established directly by image URL or can be stored on SVP system. Available values: direct, store

NOTE: When type is store, actual file pull will start asynchronously from a separate server and may take some time. Do not delete the image file immediately, wait for a notification or do so with a clean up scheduled job on your server, in an hour for example!

When type is direct, image thumbnails in Panel video list will be created asynchronously and stored on SVP server. If you change content of image URL, you have to call this service again in order to generate new image thumbnails. Notifications are sending as notice event type. See Appendix 2 – Section 6.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

19 . svp_set_primary_video_image

Description:

Marks video image as startup image associated with some of publisher's videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

number *

Image number (must be between 1 and 4). See svp_list_video_images service.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

20 . svp_cancel_user

Description:

It can be used to delete any of reseller's users.

Notes:

This service is only applicable to resellers!

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

user_ref

SVP User reference ID filter.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

21 . svp_start_broadcast

Description:

This service can be used to start broadcasting of live videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

22 . svp_stop_broadcast

Description:

This service can be used to stop broadcasting of live videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

23 . svp_start_live_encoder

Description:

This service can be used to start live encoder box.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

encoder_ref *

Live encoder reference ID. See svp_list_live_encoders service.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

24 . svp_stop_live_encoder

Description:

This service can be used to stop live encoder box

.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

encoder_ref *

Live encoder reference ID. See svp_list_live_encoders service.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

25 . svp_list_live_encoders

Description:

Returns a list of live encoders associated with publisher's account.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

Returned data:

List of publisher's live encoders or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xx</count>

<live_encoder_list>

<live_encoder>

<ref_no>1</ref_no>

<name>My Live Encoder #1</name>

<status>started/stopped</status>

</live_encoder>

...

</live_encoder_list>

</response>

26 . svp_broadcast_feed

Description:

This service will create new Live Broadcast.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

whitelabel

WhiteLabel SVP video destination. Available values: yes & no (default). If value is yes you can re-brand this kind of player and insert your own logo or text (watermark).
NOTE: If live video file is registered under channel playlist and whitelabel parameter is not present, video destination will be established from default branding option in the channel.

video_title

Title to be associated with this video in the video list.

tag_number

Integer user data. May be used at publisher's discretion. For example category or internal user ID.

tag_string

String(100) user data. May be used at publisher's discretion. For example tagging information.

channel_ref

TV or PPV channel under which the video is to be associated with. Useful if you need to publish videos in a TV or PPV channel automatically. Take a look at svp_list_channels service for information how to get reference IDs dynamically.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

Live video reference code and key or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<ref_no>xxxx</ref_no>

<video_key>xxxx</video_key>

</response>

27 . svp_start_recording

Description:

This service can be used to start recording of live videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

28 . svp_stop_recording

Description:

This service can be used to stop recording of live videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

Returned data:

OK or error code if error occurs

Example success response:

<response>

<result>OK</result>

</response>

29 . svp_list_video_playlists

Description:

Returns a list of video playlists associated with publisher's account.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

List of publisher's video playlists or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xxx</count>

<video_playlists>

<video_playlist>

<ref_no>1</ref_no>

<title>My Video Playlist #1</title>

</video_playlist>

...

</video_playlists>

</response>

30 . svp_list_custom_fields

Description:

Returns a list of custom fields associated with publisher's account.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

List of publisher's custom fields or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xxx</count>

<custom_fields>

<custom_field>

<ref_no>1</ref_no>

<name>My Custom Field #1</name>

<description>Field Description</description>

</custom_field>

...

</custom_fields>

</response>

31 . svp_list_video_custom_fields

Description:

Returns a list of custom fields associated with some of publisher's videos.

32 . svp_set_video_custom_field_value

This service can be used to set custom field value with some of publisher's videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

field_ref *

Custom field reference ID. See svp_list_custom_fields service.

value

Video custom field value.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

33 . svp_set_free_video_mode

Description:

This service can be used to set free to watch mode with some of publisher's videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

34 . svp_assign_video_tickets

Description:

This service can be used to assign Pay Per View tickets with some of publisher's videos. Some of parameters are marked for using only when single ticket is assigned. If expiry_days, expiry_months and expiry_years are empty or zero, expiry period of single ticket will be established to UNLIMITED.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

layout *

Layout to be assigned with given video. Available values: default, advanced.

tickets

List of tickets to be assigned with given video. It should be divided by commas. Available values: global, playlist, single. This parameter is mandatory for default layout.

Ticket protection type. Available values: payment, password. This parameter is mandatory for advanced layout and single ticket.

ticket_title

Prepaid single ticket title.NOTE: Available only when single ticket is assigned with given video.

ticket_description

Ticket sales description. It describes what is the single ticket purpose.NOTE: Available only when single ticket is assigned with given video.

ticket_price

Ticket price field. It determines the prepaid single ticket price. This parameter is mandatory and should be greater than zero.NOTE: Available only when single ticket is assigned with given video.

expiry_days

This parameter allows to set up expiry period in days for single ticket.NOTE: Available only when single ticket is assigned with given video.

expiry_months

This parameter allows to set up expiry period in months for single ticket.NOTE: Available only when single ticket is assigned with given video.

expiry_years

This parameter allows to set up expiry period in years for single ticket.NOTE: Available only when single ticket is assigned with given video.

total_allowed_views

This parameter limits the maximum number of times the viewer can use this ticket to play given video. If this parameter is empty or zero, UNLIMITED allowed views will be established. This means that viewer can use single ticket unlimited number of times to play given video unless it is further limited by.NOTE: Available only when single ticket is assigned with given video.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

35 . svp_list_advanced_packages

Description:

Returns a list of advanced packages associated with publisher's account.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xxx</count>

<advanced_packages>

<advanced_package>

<ref_no>1</ref_no>

<name>My Advanced Package #1</name>

</advanced_package>

...

</advanced_packages>

</response>

36 . svp_set_video_protection_mode

Description:

This service can be used to set protection wall to viewer with some of publisher's videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

protection_wall *

Protection wall to be assigned with given video. Available values: immediately, timed.

seconds

In case of timed protection wall, ticket overlay pops up after the set number of seconds.NOTE: Available only when timed protection wall is assigned with given video.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

33 . svp_set_free_video_mode

Description:

This service can be used to set free to watch mode with some of publisher's videos.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref *

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

37 . svp_generate_ticket_passwords

Description:

This service can be used to generate passwords with some of publisher's videos. Some of parameters are marked for using only when single ticket is assigned. If expiry_days, expiry_months and expiry_years are empty or zero, expiry period of single ticket will be established to UNLIMITED.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

ticket *

Available values: global, playlist, single.

layout *

Layout to be assigned with given video. Available values: default, advanced.

video_ref

Video reference ID. See svp_list_videos service.NOTE: Available only when ticket parameter is single.

channel_ref

Video playlist reference ID. Take a look at svp_list_channels service for information how to get reference IDs dynamically.NOTE: Available only when ticket parameter is playlist.

This parameter allows to set up expiry period in days for generated passwords.

expiry_months

This parameter allows to set up expiry period in months for generated passwords.

expiry_years

This parameter allows to set up expiry period in years for generated passwordset.

total_allowed_views

This parameter limits the maximum number of times the viewer can use password to play given video. If this parameter is empty or zero, UNLIMITED allowed views will be established. This means that viewer can use password unlimited number of times to play given video unless it is further limited by.

total_allowed_views_per_video

This parameter limits the maximum number of times the viewer can use password to play any of publisher's videos. If this parameter is empty or zero, UNLIMITED allowed views per video will be established. This means that viewer can use password unlimited number of times to play any of publisher's videos unless they are further limited by.NOTE: Available only when ticket parameter is playlist or global.

count_passwords

Number of passwords to be generated.NOTE: Maximum number of passwords generated per request is 50.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xxx</count>

<passwords>

<password>xxx</password>

...

</passwords>

</response>

38 . svp_confirm_ppv_order

Description:

This service can be used to confirm PPV order in case of using custom payment solution.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

order_key *

PPV order key. It's available through POST parameter after redirection to custom payment processor URL.

email

Viewer's email address.

first_name

Viewer's first name.

last_name

Viewer's last name.

transaction_id

ID of transaction in custom payment processor.

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

39 . svp_get_rtmp_url

Description:

This service can be used to get RTMP uplink URL with some of publisher's live videos.

Valid RTSP URL / SDP content to be associated with the camera.
NOTE: For SDP content see sdp parameter.

new_broadcast

If this parameter is present new broadcast will be created and the camera will be attached to it.

Available values: yes.

whitelabel

WhiteLabel SVP video destination. Available values: yes & no (default). If value is yes you can re-brand this kind of player and insert your own logo or text (watermark).
NOTE: If live video file is registered under channel playlist and whitelabel parameter is not present, video destination will be established from default branding option in the channel.
Only available when new_broadcast is set to: yes!!!

video_title

Title to be associated with this video in the video list.
Only available when new_broadcast is set to: yes!!!

tag_number

Integer user data. May be used at publisher's discretion. For example category or internal user ID.
Only available when new_broadcast is set to: yes!!!

tag_string

String(100) user data. May be used at publisher's discretion. For example tagging information.
Only available when new_broadcast is set to: yes!!!

channel_ref

TV or PPV channel under which the video is to be associated with. Useful if you need to publish videos in a TV or PPV channel automatically. Take a look at svp_list_channels service for information how to get reference IDs dynamically.
Only available when new_broadcast is set to: yes!!!

sdp

If this parameter is present and it's value is 1 then the camera will be treated as RTP and rtsp_url parameter should contain SDP file content.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

Reference ID pointing to the created camera or error code if error occurs. Field ref_no for the RTSP camera is integer.

If new_broadcast is used clip ref_no and video_title fields are also returned.

Example success response:

<response>

<result>OK</result>

<ref_no>xxx</ref_no>

<clip>

<ref_no>xxx</ref_no>

<video_key>xxx</video_key>

</clip>

</response>

42 . svp_edit_rtsp

Description:

This service can be used to edit RTSP camera parameters.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

rtsp_ref *

Rtsp camera reference ID.

rtsp_name

Title to be associated with the camera.

rtsp_url

Valid RTSP URL / SDP content to be associated with the camera.
NOTE: For SDP content see sdp parameter.

sdp

If this parameter is present and it's value is 1 then the camera will be treated as RTP and rtsp_url parameter should contain SDP file content.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

43 . svp_remove_rtsp

Description:

This service can be used to remove RTSP camera.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

rtsp_ref *

RTSP camera reference ID.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

44 . svp_list_rtsp

Description:

This service can be used to list RTSP cameras.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

count_only

Returns only total count of RTSP cameras.

NOTE: RTSP camera list is not present in response.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

List of RTSP camera resources or error code if error occurs. Field name is associated with the camera title.
Field url is associated with the address of the camera. Parameters status and error_msg are related to the response from the camera.

Example success response:

<response>

<result>OK</result>

<count>xxx</count>

<timestamp>1421420895</timestamp>

<rtsp_list>

<rtsp>

<ref_no>xxx</ref_no>

<name>My Custom RTSP camera #1</name>

<url>rtsp://address.com</url>

<status>201</status>

<message>Status Message</message>

</rtsp>

...

</rtsp_list>

</response>

45 . svp_list_recordings

Description:

Returns a list of recorded videos from a specific live video feed

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref

Video reference ID. See svp_list_videos service.

NOTE: Will accept only live feed video references!

count_only

Returns only total count of recorded videos.

NOTE: All recorded video list is not present in the response.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

A list of videos or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<count>xx</count>

<timestamp>xx</timestamp>

<video_list>

<video>

<ref_no>1</ref_no>

<video_key>xxx</video_key>

<title>My video #1</title>

<tag_number>1000</tag_number>

<tag_string></tag_string>

<video_source>ondemand</video_source>

<stream_name>xxx</stream_name>

<channel_ref>xxx</channel_ref>

<duration>xxx</duration>

<date_created>xxx</date_created>

<date_modified>xxx</date_modified>

</video>

...

</video_list>

</response>

46 . svp_set_clip_delivery

Description:

Sets delivery method for a specific video.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref

Video reference ID. See svp_list_videos service.

delivery_method *

Valid delivery method name. Check Appendix 6: Delivery methods!

encryption_method

Sets the video encryption.

Available values: aes , rc4 .

Only available when using Secured HLS!!!

cookie_protection

Hotlinking protection using cookie! Available values: yes , no.

Only available when using HLS or Secured HLS!!!

ip_protection

Hotlinking protection using IP! Available values: yes , no.

Only available when using HLS or Secured HLS!!!

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

</response>

47 . svp_get_hls_url

Description:

Returns the playback hls url of a specific video or live broadcast. You can get and use the playback video url within your own mobile application, Roku or other Top-Set Boxes and TV Apps.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref

Video reference ID. See svp_list_videos service.

viewer_ip

Viewer IP used for IP Hotlinking protection. Should be used if this service is not directly called from the viewer. By default the caller IP is used.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

Video url or error code if error occurs. If cookie protection is set returns a cookie.

This cookie must be used with the video url for non browser applications. Use 'stok' name for the cookie.

NOTE!!! Url will be changed on modifying any of these settings: delivery method; cookie or ip protection; switching between FMLE, WIRECAST, RTSP or WEBTV; going online or offline;
We recommend calling this service after executing one of these actions.

Example success response:

<response>

<result>OK</result>

<video_url>xxx</video_url>

<cookie>xxx</cookie>

</response>

48 . svp_get_video_stats

Description:

Returns a played/shown statistics for specific video.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

video_ref

Video reference ID. See svp_list_videos service.

user_ref

SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

OK or error code if error occurs.

Example success response:

<response>

<result>OK</result>

<stats>

<played>xxx</played>

<shown>xxx</shown>

</stats>

</response>

49 . svp_get_rtp_destination_server

Description:

Returns a RTP publishing data for specific RTP camera.

parameter

description

token *

Valid API authentication token. See svp_auth_get_token service.

rtsp_ref *

RTP camera reference ID.

country_code

Two letter ISO 3166 country code which points the location of camera.
NOTE: Example country codes list could be found here.

Appendix 2: API Callback Notifications

NOTE: In order to receive notifications you must configure your callback URL in the SVP panel at Account > Integration > API Access.
All notifications initiated by the SVP publisher API are implemented as asynchronous calls. They are initiated with a slight delay from the actual operations performed. The delay would usually be under 10seconds.
The API notifications are implemented as HTTP GET calls to an user specified URL address. Parameters are passed with the call depending on the notification event type.

1 . video_transcode

Description:

This notification is sent when there is a status update related to the video transcode system.

Notes:

You will receive this notification if any video associated with your account or API key(for resellers) has had a change in encoding status. This notification can be used for automated publishing of videos whenever they become available in the system.

parameter

description

operation_name *

=video_transcode

result *

OK/ERROR

clip_ref *

The clip reference ID.

clip_key *

The clip key.

err_msg

Error message if result is ERROR.

2 . delete_video

Description:

This notification is sent when a video associated with your account or API key(for resellers) has been deleted through the API or the SVP/Reseller panel.

Notes:

This is an AFTER DELETE type of notification! Any API calls related to the related video reference ID will fail! This notification can be used to update any cached video lists.

parameter

description

operation_name *

=delete_video

result *

OK/ERROR

clip_ref *

The clip reference ID.

clip_key *

The clip key.

err_msg

Error message if result is ERROR.

3 . edit_video

Description:

This notification is sent when some of the properties of the video have been changed.

Notes:

This notification can be used to update any cached video lists.

parameter

description

operation_name *

=edit_video

result *

OK/ERROR

clip_ref *

The clip reference ID.

clip_key *

The clip key.

err_msg

Error message if result is ERROR.

4 . registered_user

Description:

This notification is sent when some new user has been registered.

Notes:

This notification is only applicable to resellers! It can be used to update any cached user lists.

parameter

description

operation_name *

=registered_user

result *

OK/ERROR

ref_no *

The user reference ID.

user_name *

The user name.

login_name *

The user login name.

5. upload_video

Description:

This notification is sent when procedure of uploading files has been successfully finished or failed.

Notes:

This notification can be used to delete the uploaded file from your server or some corrections if uploading is failed.

parameter

description

operation_name *

=upload_video

result *

OK/ERROR

clip_ref *

The clip reference ID.

clip_key *

The clip key.

err_msg

Error message if result is ERROR.

6. notice

Description:

This notification is sent with various operations in system. It can be used like debugging information.

parameter

description

operation_name *

=notice

subject *

Subject of notice. See table below for more information.

type *

SUCCESS/ERROR/WARNING

ref_no *

Reference ID associated with subject of notice.

recorded_from_stream

This parameter is available only with video.publish notice type. It indicates the source stream name of recorded video.

message

Message depending on subject of notice.

Notice subjects:

type

description

user_account.locked

Notifications about locking of user account.
Only applicable for resellers!!!

user_account.restored

Notifications about restoring of user account.
Only applicable for resellers!!!

video.publish

This notification is sent when video is ready for publishing.

video_image.create_thumbs

Notifications about result of creating video thumbs in direct type of setting video images. See svp_set_video_image service for more information.

video_image.upload_image

Notifications about result of uploading video images in store type of setting video images. See svp_set_video_image service for more information.

When you pass parameter overrides to the svp_get_player_code service these override parameters replace the ones saved in the template used thus allowing certain customizations to the code used in the publisher's application.

parameter

description

player_skin

Available values: thin_controls (default), thin_controls_old. Player skin to be used with this
player. Further skins will become available when such are added to the system.

player_color1

First color of player skin coloring. Default color is #c8c8c8.
NOTE: The value should be hexadecimal representation of color. Example: #FF00FF

player_color2

Second color of player skin coloring. Default color is #a6a6a6. NOTE: The value should be hexadecimal representation of color.

width

Player width in pixels. Default width is 640px.

height

Player height in pixels. Default height is 480px.

video_width

Video width in pixels. NOTE: Player width is calculated automatically based on selected player skin.(Calculated player width overrides width parameter if it passed).

video_height

Video height in pixels. NOTE: Player height is calculated automatically based on selected player skin. (Calculated player height overrides height parameter if it passed).

stretch_video

Available values: yes & no (default). If the value is yes the video will be stretched to fit the player area. This option will override the original aspect ratio of the video.

ratio

Available values: 16:9 & 4:3. If this parameter is passed player dimension is calculated proportionally by video_width or video_height parameter (only one of these parameters have to be passed).

brand_link

Available values: new_window(default), same_window. Select the open mode for the branding link (if any) in this player.

player_transparency

Available values: yes & no (default). Some player skins use effects and alpha channels to blend with the background. This option allows to control that behaviour. This mode can be used to create transparent video players.

pause_on_start

Available values: yes (default) & no. If value is yes the visitor must click the play button to start video playback.. NOTE: This is available only if value of parameter hide_controls is not set to yes.

show_image

Available values: yes (default) & no. If value is yes the selected image in clip properties is shown as a startup screen. NOTE: This is available only if value of parameter pause_on_start is not set to no.

start_volume

Available values: Number between 0 and 100 (Default volume is 50%).

video_prebuffer

Available values: yes & no (default). If value is yes the video will start prebuffering immediately. Note that this setting will impose a load on visitor's connection even if the visitor has not decided to watch the video! Also you will be charged for video delivery as the video is delivered even without being watched! NOTE: This is available only if value of parameter pause_on_start is not set to no.

video_loop

Available values: yes & no (default). If value is yes the video will start from the begining when finished.

hide_controls

Available values: yes & no (default). If value is yes only the video is shown without controls. Only auto-play setting applies!

auto_hide_controls

Available values: yes & no (default). If value is yes player controls are automatically hidden if no action(mouse movement/click) is taken for a short amount of time in the player. The controls reappear if mouse is pointed at the player. NOTE: This is available only if value of parameter hide_controls is not set to yes.

player_align

Available values: none (default), top_left, top_center, top_right, middle_left, middle_center, middle_right, bottom_left, bottom_center, bottom_right. Align of the player in the screen.

offset_x

Player offset (in pixels) in x coordinate (Default offset X is 0). NOTE: This parameter is available only if player_align is different than none

offset_y

Player offset (in pixels) in y coordinate (Default offset Y is 0). NOTE: This parameter is available only if player_align is different than none

allow_fullscreen

Available values: yes (default) & no. If value is yes the [full] button on the player will be available and the viewer can switch to a bigger or fullscreeen player. NOTE: This is available only if value of parameter hide_controls is not set to yes.

fullscreen_mode

Available values: big_screen, full_window & flash_native. big_screen fullscreen mode is a larger player shown in the middle of the browser window over your webpage. full_window is when the player fills the entire browser window. flash_native uses native flash plugin capability and fills the entire screen. This mode will only work when Flash9 is installed on the client computer. NOTE: Larger player dimensions may result in poor playback performance on low end computers and will make obvious video quality problems at close sighting range. This is available only if value of parameter allow_fulscreen is not set to no. flash_native is not available for popin embed mode.

background_color

Player background color. Default background color is #FFFFFF NOTE: The value should be hexadecimal representation of color. Example: #FF00FF. This parameter is available only if fullscreen_mode is set to big_screen.

background_transparency

Available values: Number between 0 and 100 (Default 0). This is the transparency of the layer which is put above your page and behind the player in big_screen fullscreen mode. NOTE: This parameter is available only if fullscreen_mode is set to big_screen.

link_type

Available values: text_link (default) & image_link. Choose how the link on your site pointing to the popup player will look like.

link_title

This text will appear as a textual link or set as title for an image link depending on the link_type setting above.

image_address

For an image link fill in the address of the image you would like to use for the link.

close_button

Available values: yes & no (default). Close button of player in the top right corner.

is_responsive

Generate responsive player with HTML5 video fallback. The player will keep
its proportions (etc. 16:9) even after resizing.

Gen3 UberCool (StageVideo Support) parameters:

skinAlpha

Player skin opacity in percents.

colorBase

Player base color.

colorIcon

Player controls icon color.

colorHighlight

Player highlight color.

Appendix 4: Video editable properties list

property ID

name

description

1

Title

Video title which will help you to differentiate this video from the others

2

Enabled

Video status. Available values: 2 - video is being encoded. 1 - video is active and can be watched. 0 - video is disabled - the player still will be visible in your website, but will not play the movie.

3

Tag Number

Video Tag Number is number (Integer) which will help you to differentiate this video from the others

4

Tag String

Video Tag String is string (max 100 characters) which will help you to differentiate this video from the others

5

Aspect Ratio

Use this property to correct the way of how the image is displayed in the video player.
If there are black stripes around the player, simply try each option and save the changes until you find the best result.

6

Channel Name

Channel Playlist name – this property is available only if video is part of TV or PPV playlist

7

Channel Ref

Channel Reference Code - this property is available only if video is part of TV or PPV playlist

8

Whitelabel

Whitelabel branding status of video. Available values:

yes - whitelabel (rebrandable) video - ideal for web designers / developers / resellers. You can rebrand this kind of players and insert your own logo or text (watermark). The embed code is also whitelabeled, so you can use them for reselling purposes. During each playback billing point, the system will deducts 1.5 Streams from your account.

no – standard video - there is a watermark "powered by our company". Branding cannot be removed/modify by the user. Use whitelabel or TV/PPV channel publishing solutions if you wish to insert your brand. During each playback billing point, the system will deducts 1 Stream from your account.

9

Allowed Domains

Our policy is to keep your content private. It is not essential to apply domain name restriction unless you have some concerns that your online viewers can copy the embed code you have used to publish the video in the first place and use that code for other websites. In that case if you set up domain name restrictions, the embed code will not be valid for other websites. Add the allowed domains separated by comma(",").

DO NOT enter www. or http://
Leave empty to allow all domains. Subdomains and directories if used will further limit the access.

EXAMPLE: domain1.com , mydomain2.com , mydomain3.com

NOTE: This property is available only for single videos.

10

Short Description

Updates video short description

11

Full Description

Updates video full description

12

Recording title

Video title of each recording created for specific live stream.
Default format is: Recording %ref_code% (%date_created%)

The following variables could be used:
1. %date_created% Creation date of recording in the following format: M d, Y H:i:s
2. %date_started% Started date of recording in the following format: M d, Y H:i:s
3. %ref_code% The reference code of live stream
4. %parent_title% The title of live stream

NOTE: This property is available only for live videos.

13

Recording duration

Max duration (in seconds) for each recording created for specific live stream.