The Media Services Live Stream Provisioning API

The Media Services Live (MSL) Stream Provisioning API allows you to publish live content and retrieve it for delivery either through Akamai or any content delivery network (CDN). You use MSL primarily for over-the-top (OTT) applications, but you can also use it for other live specific events. To publish content, you push media content directly from encoders into a live origin through the Akamai Ingest server. To deliver it, you pull that content into origin through a CDN.

The API mirrors the functionality of MSL 4.x available in the Luna Control Center. This version of the API (v2) contains information on how to create a stream, list available streams, update a stream, remove a stream, list live origins, get live origin details, get activation status, create an origin version, get contracts, get CDNs, generate a key, and get CP codes.

This API supports the beta Multiple CDN feature, which allows you to use any CDN to deliver your media content, while still using Akamai for ingest and origination. It also supports Multi-Account Access, which allows you to use origin keys to deliver streams defined in one Akamai account in other accounts’ configurations, to better syndicate your content for all your customers. In the MSL 4.1 release, Media Services Live is split from Adaptive Media Delivery, so that you can use MSL 4 with all AMD features. The multi-account feature further allows you to deploy many AMD configurations for many customer accounts, all from a single MSL live origin.

Who should use this API

The MSL Stream Provisioning API enables developers and architects to access and provision media streaming using customized interfaces.

Getting started

Before using the MSL Stream Provisioning API for the first time:

  • Contact your Akamai representative to enable it for your account.

  • Ensure that your contract includes MediaServicesLive4::MediaServicesLive4.

  • Review Get Started on tools that Akamai provides.

  • Review Authorize your Client in Luna to create your Akamai API access credentials and authorizations. As detailed in API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • Select the following when you configure the API client:

    • API Group: Luna
    • API Name: Media Streaming

Rate limiting

The MSL Stream Provisioning API imposes a rate limiting constraint. Exceeding that limit results in a 429 error response. Consider this especially when calling successive operations as part of a loop.

Responses have the following headers to specify rate limit information:

  • X-RateLimit-Limit: The maximum number of tokens allowed.

  • X-RateLimit-Remaining: The number of tokens remaining.

Once X-RateLimit-Remaining becomes 0, you get a 429 error the next time you make an API call. The response header also displays the time when you can make one more request. For example: X-RateLimit-Next: 2018-05-11T07:04:40.004Z.

If you do not make any more API calls after you receive a 429 error, the X-RateLimit-Remaining gradually increases and becomes equal to X-RateLimit-Limit.

API workflow

Follow these steps to use the MSL Stream Provisioning API:

  1. Create a new MSL origin and optionally use MSL features such as multi-account and multi-CDN.

  2. Create a stream using the origin that you created. Get all of the origins from List live origins and provide the CP code associated with the origin in the stream creation request. The encoder zone should also match the origin location. or Create a stream with a new MSL origin along with the stream settings. Get an unused CP code from List CP codes and provide it in the stream creation request.

  3. Create the Adaptive Media Delivery (AMD) property with the Origin Type as Media Services Live in the Origin Server Behavior section.

You can retrieve the following fields to create a stream:

To disable the multi-account and multi-CDN features, make a PUT call with an empty object in the request body.

NOTE: The following endpoints are deprecated. Do not use them:

  • /msl-origin/origins/{id}/versions
  • /msl-origin/origins/{id}/versions/{version}/activate

Last modified: 6/12/2018