WARNING: This API has been deprecated and should not be used for new projects. Click here for more information.

Getting Started with Video Cloud Media API

The Media API is a REST-based API for accessing the content and metadata in your Video Cloud account. Because the Media API is a REST-based API, it can be accessed from a client or server-side application. You can use any language, because you just need to be able to make http GET and POST requests, and handle the responses that are generally in the form of JSON.

To prevent unauthorized access to the metadata in your account, Video Cloud protects access to the API with tokens that you pass as parameters when making API calls. Like other web-based APIs, tokens are generated for you by Video Cloud and protected by you.

Note: the Media API is not available to Video Cloud Express Plan I or II customers. Read tokens for the Media API's read methods are available to Video Cloud Express Plan III customers, and the full Media API is available to Video Cloud Pro and Enterprise customers.

Under the hood

REST, or Representational State Transfer, is a standard way of accessing data stored in a remote system over HTTP. It is a cousin of SOAP and is one of the technologies that power web services. Its primary ability is to abstract the workings of the remote system in the transfer of its state (or information). All your code needs to understand is the format of the data that is sent back.

The Media API includes read and write methods.

The Read API consists of a set of methods that perform a variety of queries on our servers (which are cached for performance), and return sets of data in DTOs or Data Transfer Objects. For example, one API method is search_videos, which returns an array of VideoDTOs, where each VideoDTO contains the metadata for a specific video. The return data is formatted as either JSON strings or as MRSS-formatted XML. JSON (JavaScript Object Notation) is a lightweight way of transferring complex objects as strings, and nearly every language today has built-in or publicly available libraries to parse JSON strings into native objects. MRSS (Media Really Simple Syndication) is an RSS module used for syndicating multimedia files (audio, video, image) in RSS feeds.

Note: URLs for videos and images are subject to change without notice, so you need to pull them dynamically using the Media API when you use them in pages, or if that is not possible, re-run your queries to retrieve them regularly - every six hours is recommended - and update links in your pages as needed.

The Write API consists of a set of methods that create, update, or delete videos and playlists. For example, one Write API method is create_video, which you can use to pass in a video file, its associated metadata, and create a video in your Video Cloud account.

The Media Write API requests are POST.

For write requests, the data submitted to the media write API must be in JSON format, encoded as a form parameter named "json". The JSON document should include a "method" field and a "params" field, and the examples you publish should show the whole body of the POST request:

Calling methods

Method calls using REST are basically HTTP GET requests (for read methods) or POST requests (for write methods) to a particular URL on the Video Cloud servers. The request includes the name of the method you're calling, together with its input arguments, which are passed as parameters in the URL. The body of the HTTP response contains the results of the HTTP call as a JSON string or as MRSS-formatted XML. All Media API calls use the base URL http://api.brightcove.com/services. Accessing Video Cloud Services through IP addresses is not supported and should be avoided at all times. Video Cloud IP addresses can change at any time without notice; a change can cause any systems trying to access them via IP address to fail.

Important note for Japanese publishers

If you are a customer of Brightcove KK, our Japanese joint venture, you need to use a different URL to access the Media API. All of your Media API calls need to begin with http://api.brightcove.co.jp, and not http://api.brightcove.com.

Method calls also require a token. Video Cloud issues tokens to accounts; tokens give you access to your account when you use the API. There are separate tokens for read methods and write methods in the API. You append your token to the call as a URL parameter, such as token=[tokenString], where tokenString is your URL-encoded token. Note: Media API tokens generally end with one or more dots (.). Be sure to include the dots when you use the API tokens - it's easy to lose them when you cut and paste. You can view and manage your API tokens on the Account Settings: API Management page in Video Cloud Studio, which also provides a button for emailing a token or copying a token to your clipboard. For more information about tokens, see Managing Media API Tokens.

It is possible to modify your Write token to disable certain methods (like delete_video, for instance). For details, see this documents.

Protecting your API tokens on the wire

To guard against attempts to sniff out your tokens, consider making your API requests via HTTPS, rather than HTTP. All you need to do to use HTTPS is to make your API call with the https:// protocol, instead of http://. The "s" stands for "secure," and instructs the browser to encrypt the transaction, including your token. There are performance drawbacks to using HTTPS, because the server and browser need to encrypt and decrypt the traffic.

For example, to retrieve all videos in your account, you make an HTTP request that looks like:

Note: if you call search_videos without search parameters, all videos are returned. There is also an older find_all_videos method, but search_videos is recommended because it performs better.

This is a working request - you can try it here. You will see the results of the call print out. This is a raw method call. What comes back is unprocessed and is not formatted. In the examples, you'll see ways to take the returned data and shape it in ways that are useful for an application. (Note: This call uses a demo account. To use your own account, substitute your own read token in the &token argument.)

For write requests, the data submitted to the media write API should be in JSON format, encoded as a form parameter named "json". The JSON document should include a "method" field and a "params" field, and the examples you publish should show the whole body of the POST request: json=

Look at the source code for our WRITE samples like this one to see how you submit this data via an HTML form.

Note: When you are uploading a file using the create_video method, the JSON request body must come before the file part in the request, or the request will fail.

Using the API

Because Media API requests are simple HTTP calls, you can include them just about anywhere in your application. Every popular language for the web, server- or client-side, has syntax for making HTTP requests. These are what you use to include API calls in your application. In addition, Video Cloud-savvy developers have created SDKs (Software Development Kits) for most popular web-oriented languages that you can include in your applications as native classes for easy API access. Check out Open Source @ Brightcove, a community supported initiative to host a variety of applications, SDKs and tools for the Video Cloud platform in one central location.

Chances are your request will be made on-demand - for example, when a page loads, when a user clicks a button, or when some other event occurs. To handle this, wrap the HTTP request in a function and call it in response to some programmatic event, like an onClick event. You must also handle the response and, if you're not working in JavaScript, parse the JSON string or MRSS output into native objects so that you can work with the data. Be aware that JSON does not reliably return data in a particular order; we suggest you use a JSON parser to get hold of the fields you want to work with.

With the Write API methods, you can create a client application that integrates your Video Cloud account with your content management system. Or you might write a desktop application that is run locally and doesn't need a server between the client and Video Cloud.

API parameters

The basic Read API calls, like find_all_videos, can be refined with additional parameters. The API reference lists the complete set, but here is an overview of just a few of the things you can do:

Page the search results. You can opt to return pages of data if you expect a large number of results. You can set the page size and select a specific page to be returned. The maximum page size is generally 100; if you don't set the page size, results will be returned in pages of 100.

Select fields for the return set. In most use cases you will only need specific fields of data, like the name and the shortDescription fields. You can force the API to only return these fields to minimize the amount of data returned and improve performance.

Sorting. You can specify a sort order to be applied to the result set, such as alphabetically, creation date, publish date, modified date, last weeks play count, or the total play count.

The basic Write API calls, like create_video, take parameters that add the metadata for the video you're creating. There are also Write API methods to create, update, and delete playlists and to create cue points, images, and logo overlays.

Working with JSON

When you work with JSON strings, make sure you use the appropriate JSON syntax. String values are enclosed in quotes, while numbers and boolean values are not. For example, in the following, create_video, token, and filename are strings, while create_multiple_renditions is a boolean:

Caching

To enhance performance, API calls are cached on Video Cloud servers. When a call is made, Video Cloud checks the cache first. If that call hasn't been cached or the cache has expired, the call goes straight to the database and Video Cloud sends the results back and also caches them. How long the cache persists varies according to several factors including network traffic, the method called, and the current volume of API calls. Generally, you can expect cached values to expire within 5-15 minutes.

Caching doesn't take into account changes you may make to your library using the Video Cloud Studio or batch upload. Changes made to your library that would affect a call won't be reflected in the call's results until the cache expires. Keep this in mind when you are testing your code; the API may be working correctly, even if you're not seeing the correct results.

Disabled videos

A video in your account may be disabled for several reasons:

it has been deleted

it has been set to inactive

it has been scheduled for a future date

Most of the Media API search methods, such a search_videos and find_video_by_id, will not return disabled videos. To return disabled videos, you must use find_modified_videos or one of the _unfiltered methods. Note: the _unfiltered methods are not enabled by default. To enable them, submit a request to Brightcove Support

Error handling

The API will try to catch common errors, such as a video_id that doesn't exist, and handle them in a code-friendly way. Most errors are returned as JSON strings with an error parameter like this:

If your output is MRSS, errors are included in an <error> element that includes an error code and message.

As much as you can, your code should always try and handle errors gracefully rather than letting the end-user deal with a cryptic message or blank page. By handling the "error" parameter of the result object (after JSON-parsing the response), you will know what might have gone wrong so that you act on it appropriately by programming an error message for the end-user.

Error messages returned by the Media API include a numerical error code that classifies errors by type. For more information, see the Error Message Reference.

Strategies for retrying after errors occur

Depending on the specific error your get from the media api, your retry strategy should be different.

First, you should always use 1 thread per token and should keep your requests to just the information you need to complete the action. You should also try to use the same parameters in the same order to ensure you get the most benefit from our caching layers.

If you get a null response, the video either does not exist or has not completed uploading. You should wait at least a few minutes before retrying. If it continues to fail after a reasonable time for the upload to complete, you should consider the video upload failed.

If you get a timeout error, you should modify your request to make sure you are getting only the data that you need. Wait a minute or so, then retry. Going any earlier than that may result in a throttling situation as the timed-out request counts against the throttling limit.

If you get a concurrent read / write exception and have been using only one thread, you should be fine doing normal back off retry until it is solved.

For any transient errors, immediate retry with back off is probably the best solution.

Token management

Keep your token secure - it provides access to your library. This is especially important if you're considering client-side API calls. Any of your web visitors can "view source" and see your API token, which they could then use to retrieve your metadata, including, potentially, direct links to your assets.

Limitations

In general, anything you can do with a video or playlist in the Video Cloud Studio Media module, you can also do using the Media Write APIs. There are a few exceptions. You cannot set or modify the following properties of videos using the Media Write APIs:

The viral syndication flag

bumpers

The "Force Ad Request" flag

Related information

Now that you have an overview of the Media API, check out the other documentation about the Media API: