Clicky

Getting Started with the Developer API

SVP API for Video Publishers

Version: 1.21
Last update: 06/10/2014

Download API_Examples

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. 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.
  2. 2. Listing of publishers videos with filtering
  3. 3. Deleting a video
  4. 4. Receiving(changing) properties of a video (title,aspect ratio,enable/disable,video options)
  5. 5. Receiving video statistics – same as video statistics in site in structured XML form (detailed & daily builds)
  6. 6. Listing upload sources
  7. 7. Listing users (Only for resellers)
  8. 8. Listing TV or PPV channels
  9. 9. Listing player templates
  10. 10. Generating embed codes for video player publishing (option for using pre-configured templates)
  11. 11. Receiving publisher's streams amount
  12. 12. Listing(receiving) video images
  13. 13. Start/stop live broadcast
  14. 14. Live broadcast feeds

SVP provides a client PHP library to facilitate integration. The library implements proper call convention and can be used as a solid starting point for application integration.

Download API_Examples

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.

Entry point

API can be accessed from http://www.streamingvideoprovider.com/?l=api Any other parameters can be passed through HTTP GET/POST requests. Service name is expected as "a" parameter:

Example of GET Request:

http://www.streamingvideoprovider.com/?l=api&a=SERVICE_NAME_HERE

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 2.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:

  1. <response>
  2. <result>OK</result>
  3. <ref_no>xxxx</ref_no>
  4. <video_key>xxxx</video_key>
  5. </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.


NOTE: Video list is not present in response.

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".
order_by Order video list based on the following fields:
ref_no: Video reference code;
title: Video title;
date_created: Video creation date;
date_modified: Video modifying date;
channel_ref: Video playlist reference code;
tag_number: Video integer tag data;
tag_string: Video string tag data.
By default ref_no order by field is applied.
order 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.
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:

  1. <response>
  2. <result>OK</result>
  3. <count>xx</count>
  4. <timestamp>xx</timestamp>
  5. <filters>
  6. <tag_number>xx</tag_number>
  7. <tag_string>xx</tag_string>
  8. <title_search>xx</title_search>
  9. <start_ref_no>xx</start_ref_no>
  10. <end_ref_no>xx</end_ref_no>
  11. <from_date_created>xx</from_date_created>
  12. <to_date_created>xx</to_date_created>
  13. <from_date_modified>xx</from_date_modified>
  14. <to_date_modified>xx</to_date_modified>
  15. <start>xx</start>
  16. <limit>xx</limit>
  17. <channel_ref>xx</channel_ref>
  18. <video_source>xx</video_source>
  19. </filters>
  20. <video_list>
  21. <video>
  22. <ref_no>1</ref_no>
  23. <video_key>xxx</video_key>
  24. <title>My video #1</title>
  25. <tag_number>1000</tag_number>
  26. <tag_string></tag_string>
  27. <video_source>ondemand/live</video_source>
  28. <stream_name>xxx</stream_name>
  29. <channel_ref>xxx</channel_ref>
  30. <duration>xxx</duration>
  31. <date_created>xxx</date_created>
  32. <date_modified>xxx</date_modified>
  33. </video>
  34. ...
  35. </video_list>
  36. </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:

  1. <response>
  2. <result>OK</result>
  3. <video_properties>
  4. <property>
  5. <id>X</id>
  6. <name>XXX</name>
  7. <value>XXX</value>
  8. </property>
  9. ...
  10. </video_properties>
  11. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xxxxx</count>
  4. <stats>
  5. <stat>
  6. <time>xxxxxxxxxx</time>
  7. <ip>1.2.3.4</ip>
  8. <country>GB</country>
  9. <streams>1</streams>
  10. </stat>
  11. ...
  12. </stats>
  13. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xxxxx</count>
  4. <stats_daily>
  5. <stat_day>
  6. <date>xxx</date>
  7. <views>xxxxx</views>
  8. <streams>yyyy</streams>
  9. </stat_day>
  10. ...
  11. </stats_daily>
  12. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xx</count>
  4. <filters>
  5. <source_type>ftp/http</source_type>
  6. </filters>
  7. <upload_source_list>
  8. <upload_source>
  9. <ref_no>1</ref_no>
  10. <name>My upload source #1</name>
  11. <source_type>ftp/http</source_type>
  12. </upload_source>
  13. ...
  14. </upload_source_list>
  15. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xx</count>
  4. <user_list>
  5. <user>
  6. <ref_no>1</ref_no>
  7. <user_name>Test User Name</user_name>
  8. <login_name>Test Login Name</login_name>
  9. </user>
  10. ...
  11. </user_list>
  12. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xx</count>
  4. <filters>
  5. <channel_type>tv/ppv</channel_type>
  6. </filters>
  7. <channel_list>
  8. <channel>
  9. <ref_no>1</ref_no>
  10. <title>My TV/PPV channel #1</title>
  11. <channel_type>tv/ppv</channel_type>
  12. </channel>
  13. ...
  14. </channel_list>
  15. </response>

12 . svp_list_player_templates

Description:

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

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 present embed code templates or error code if error occurs.

Example success response:

  1. <response>
  2. <result>OK</result>
  3. <count>xx</count>
  4. <embed_code_list>
  5. <embed_code>
  6. <ref_no>1</ref_no>
  7. <title>My template #1</title>
  8. <embed_type>Embed type name</embed_type>
  9. </embed_code>
  10. ...
  11. </embed_code_list>
  12. </response>

13 . svp_get_player_code

Description:

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:

  1. <response>
  2. <result>OK</result>
  3. <embed_code_html>
  4. K0F483ABX==
  5. </embed_code_html>
  6. </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:

  1. <response>
  2. <result>OK</result>
  3. <streams_account>
  4. <account_status>Active/Locked</account_status>
  5. <total_streams>xxxx</total_streams>
  6. <monthly_streams>xxxx</monthly_streams>
  7. <renewal_streams>xxxx</renewal_streams>
  8. <renewal_date>dd/mm/yyyy</renewal_date>
  9. <additional_streams>xxxx</additional_streams>
  10. </streams_account>
  11. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xx</count>
  4. <image_list>
  5. <image>
  6. <number>1...4</number>
  7. <name>xxx</name>
  8. <image_url>xxx.jpg</image_url>
  9. <thumb_url>yyy.jpg</thumb_url>
  10. <extension>jpg,gif,png...</extension>
  11. <primary>yes/no</primary>
  12. </image>
  13. ...
  14. </image_list>
  15. </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.
url * URL of image file. URL string must be URL encoded and maximum 255 chars long.
type * 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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xx</count>
  4. <live_encoder_list>
  5. <live_encoder>
  6. <ref_no>1</ref_no>
  7. <name>My Live Encoder #1</name>
  8. <status>started/stopped</status>
  9. </live_encoder>
  10. ...
  11. </live_encoder_list>
  12. </response>

26 . svp_broadcast_feed

Description:

Broadcast live feed to your audience.

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:

  1. <response>
  2. <result>OK</result>
  3. <ref_no>xxxx</ref_no>
  4. <video_key>xxxx</video_key>
  5. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xxx</count>
  4. <video_playlists>
  5. <video_playlist>
  6. <ref_no>1</ref_no>
  7. <title>My Video Playlist #1</title>
  8. </video_playlist>
  9. ...
  10. </video_playlists>
  11. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xxx</count>
  4. <custom_fields>
  5. <custom_field>
  6. <ref_no>1</ref_no>
  7. <name>My Custom Field #1</name>
  8. <description>Field Description</description>
  9. </custom_field>
  10. ...
  11. </custom_fields>
  12. </response>

31 . svp_list_video_custom_fields

Description:

Returns a list of custom fields 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!!!

Returned data:

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

Example success response:

  1. <response>
  2. <result>OK</result>
  3. <count>xxx</count>
  4. <custom_fields>
  5. <custom_field>
  6. <ref_no>1</ref_no>
  7. <name>My Custom Field #1</name>
  8. <value>Field Value</value>
  9. </custom_field>
  10. ...
  11. </custom_fields>
  12. </response>

32 . svp_set_video_custom_field_value

Description:

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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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.
package_ref Advanced package reference ID. See svp_list_advanced_packages service. This parameter is mandatory for advanced layout.
protection_type 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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. <count>xxx</count>
  4. <advanced_packages>
  5. <advanced_package>
  6. <ref_no>1</ref_no>
  7. <name>My Advanced Package #1</name>
  8. </advanced_package>
  9. ...
  10. </advanced_packages>
  11. </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:

  1. <response>
  2. <result>OK</result>
  3. </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:

  1. <response>
  2. <result>OK</result>
  3. </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.
package_ref Advanced package reference ID. See svp_list_advanced_packages service. This parameter is mandatory for advanced layout.
expiry_days 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:

  1. <response>
  2. <result>OK</result>
  3. <count>xxx</count>
  4. <passwords>
  5. <password>xxx</password>
  6. ...
  7. </passwords>
  8. </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:

  1. <response>
  2. <result>OK</result>
  3. </response>

39 . svp_get_rtmp_url

Description:

This service can be used to get RTMP uplink URL with some of publisher's 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.
user_ref SVP User reference ID filter. Only applicable for resellers!!!

Returned data:

RTMP URL or error code if error occurs. rtmp_url tag is base64 encoded.

Example success response:

  1. <response>
  2. <result>OK</result>
  3. <rtmp_url>K0F483ABX==</rtmp_url>
  4. </response>

Appendix 1: API Error Messages

Actual list of error codes and the associated error messages:

1000 Input/output error!
1001 Failed to create API Authorization token!
1002 Failed to delete video!
1003 Failed to set video property!
2000 Invalid input parameters!
2001 Invalid/Missing API key in parameters list!
2002 Invalid/Missing API code in parameters list!
2003 Invalid API key / API code pair!
2004 Invalid API authorization token!
2005 Token validation period has been expired!
2006 Invalid/Missing API authorization token in parameters list!
2007 Invalid/Missing clip reference code in parameters list!
2008 Invalid video reference code!
2009 Invalid start time in video statistics service!
2010 Invalid end time in video statistics service!
2011 Invalid channel reference code!
2012 Invalid upload location reference code!
2013 Invalid/Empty file name!
2014 Invalid property reference ID!
2015 Invalid/Missing new value in parameters list!
2016 Invalid aspect ratio value!
2017 Invalid user reference ID!
2018 Invalid template reference code!
2019 Invalid/Missing embed type!
2020 Invalid video key!
2021 No available video storage!
2022 Invalid video file extension!
(NOTE: Available video file extensions: avi, mpg, mpeg, flv, vob, mpeg2, divx, mp4, mov, wmv, m4v).
2023 Invalid/Missing image file name!
2024 Unable to find video image resource!
2025 Invalid/Missing video image number!
2026 Invalid/Missing video image URL!
2027 Invalid/Missing video image type!
2028 Invalid video type!
2029 Invalid live video file!
2030 Broadcast is started already!
2031 Broadcast is stopped already!
2032 Invalid/Missing live encoder reference code in parameters list!
2033 Not available live streaming access!
2034 Recording is started already!
2035 Recording is stopped already!
2036 Recording service temporary unavailable!
2037 Invalid/Missing video custom field reference ID!
2038 Invalid custom field value!
2039 Invalid/Missing layout parameter.
2040 Invalid/Missing tickets parameter for default layout.
2041 Invalid/Missing advance package reference code.
2042 Invalid/Missing protection type parameter.
2043 Invalid/Missing ticket price parameter.
2044 Invalid/Missing ticket parameter.
2045 Invalid/Missing protection wall parameter.
2046 Invalid/Missing seconds parameter.
2047 Invalid/Missing PPV order key parameter.

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.

NOTE: There is no separate notification for creating video thumbs.

APPENDIX 3: Embed code generator parameter overrides

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.

Was this article helpful?

Yes No

FAQ & Documentation » API Documentation

Last updated on October 6, 2014 with 292842 views