Blog

Automate your Media Workflow with Media Services Live API

October 13, 2020 · by Mike Elissen ·

Many companies today rely on Akamai’s Media Services Live and Adaptive Media Delivery for a full end-to-end livestreaming workflow - from ingesting multiple bitrates with high stability to delivering these streams to a global audience with as little latency as possible.

For companies managing multiple livestreams often ranging from 24/7 streams to multiple event streams occurring at the same time, having an automated media workflow to help reduce errors and ease the integration efforts can be a fantastic way to be more productive.

With the Media Services Live API and the Property Manager API, you can automate the ingest half of the workflow and the creation of Adaptive Media Delivery configurations.

In this blog post, I’ll walk through how I used Postman to run the Media Services Live API requests.

Steps

Here are the basic steps that I followed to create my workflow. 

  1. Create a valid Akamai API client with valid credentials and read-write permission to the Media Services Live API

  2. Create a Media Services Live origin

  3. Create a stream

  4. Create an Adaptive Media Delivery configuration

  5. Start your encoder and send your stream data to the Media Services Live origin

  6. Play the stream in your favorite media player

1. Create a valid Akamai API client 

In order to utilize these APIs, you’ll need to create an Akamai API client with valid credentials and read-write permissions to the Media Services Live API and the Property Manager API.

To create your API client, simply: 

  • Go to Control Center

  • Make sure you have the correct permissions, and if not, contact your Akamai account team

  • Navigate to Identity & Access > New API Client for Me 

  • Select which roles, which contracts, and which groups you are adding for this API client

 This short 5-minute tutorial will showcase how to create this in Akamai Control Center.

2. Create a Media Services Live origin

The second step to automating your media workflow is to create a Media Services Live origin. You’ll need to make sure you have your Akamai Contract ID and a new CP Code available to complete this step. 

You can retrieve your contract ID with the following API request:

To create a Media Services Live CP Code, you can run the following API request:

Ensure you are sending the Content-Type: application/json header and the send the following in the body:

{

  "name": "{{your-origin-name}}",

  "contractId": "{{your-contractId}}"

}

*Note: the {{text}} refer to variables that I have stored in a Postman environment for security purposes. 

If successful, you’ll receive a response like this:

Postman UI

The id 1081600, is the CP Code and you can store this as a variable in Postman by right-clicking on the result or manually entering it into your Postman enviroment.

Postman UI

With this in hand, you can launch the POST request to create your Media Services Live origin:

POST https://{{host}}/config-media-live/v2/msl-origin/origins 

[prism:generic]

Ensure you are sending the content-type: application/json header and the send the following body:

[prism:generic]

{

   "contractId": "{{your-contractId}}",

   "hostName": "{{your-hostname}}",

   "cpcode": {{your-cpCode}},

   "encoderZone": "EUROPE",

   "backupEncoderZone": "US_EAST"

}

The encoderZone and backupEncoderZone are region names that you can add based on your geographical needs. We recommend choosing a location closest to your encoder location.

If successful, you will receive a 202 Accepted.

3. Create a stream

Next, you will want to create a stream as part of your origin entrypoint. If you want to select between different origins (in case you have created multiple), you can run the following request to retrieve your Origins:

Once you are ready to create your stream, you can run the following request:

Ensure you are sending the Content-Type: application/json header and the send the following body:

{

   "name": "{{your-streamname",

   "contractId": "{{your-contractId}}",

   "format": "{{HLS - DASH OR CMAF}}",

   "cpcode": {{your-cpCode}},

   "ingestAccelerated": false,

   "allowedIps": [ {{add-IPs-if-you-require-additional-security}} ],

   "encoderZone": "EUROPE",

   "backupEncoderZone": "US_EAST",

   "origin": {

       "hostName": "{{your-hostname}}"

   },

   "additionalEmailIds": [

       "{{your-emailaddress}}"

   ],

   "isDedicatedOrigin": false

}

If successful, you will receive a 202 Accepted.

You can also update an existing stream with a PUT request instead with a similar body as mentioned above.

Now that we have both a Media Services Live origin and an Ingest Entrypoint as well as a stream set-up, everything is now ready for ingesting content from your encoder. However, outside of ingest, you will also need a mechanism for delivering the content.

4. Create an Adaptive Media Delivery configuration

In order to deliver our livestream, we need to create an Adaptive Media Delivery configuration. Ensure that you have read-write access to the Property Manager API (PAPI) for your Akamai API client.

The first step is to create a new CP code for Adaptive Media Delivery.

Enter the following URL into Postman: 

Ensure you are sending the content-type: application/json header and the send the following body:

{

   "productId": "prd_Adaptive_Media_Delivery",

   "cpcodeName": "{{cpCodeName_AMD}}"

}

You can hardcode the cpcodeName or set the cpcodeName as a Postman variable in your environment as shown above.

If successful, you will receive a 201 Accepted.

{

   "cpcodeLink": "/papi/v0/cpcodes/cpc_1088542?contractId=ctr_G-2Q80X7Z&groupId=grp_148539"

}

The CP Code ID is found after the cpc_. In this case, the CP Code is 1088542. We recommend storing this in a Postman variable as well called cpCode_AMD.

Next we will create the AMD configuration.

Enter the following into Postman:

Ensure you are sending the content-type: application/json header and the send the following body:

{

   "contractId": "{{groupId}}",

   "groupId": "{{groupId}}",

   "productId": "prd_Adaptive_Media_Delivery",

   "propertyName": "{{propertyName}}",

   "propertyVersion": 1,

   "ruleFormat": "latest",

   "rules": {

       "name": "default",

       "children": [

           {

               "name": "Default CORS Policy",

               "children": [],

               "behaviors": [

                   {

                       "name": "modifyOutgoingResponseHeader",

                       "options": {

                           "action": "MODIFY",

                           "avoidDuplicateHeaders": false,

                           "newHeaderValue": "*",

                           "standardModifyHeaderName": "ACCESS_CONTROL_ALLOW_ORIGIN"

                       }

                   },

                   {

                       "name": "modifyOutgoingResponseHeader",

                       "options": {

                           "action": "MODIFY",

                           "avoidDuplicateHeaders": false,

                           "newHeaderValue": "GET,POST,OPTIONS",

                           "standardModifyHeaderName": "ACCESS_CONTROL_ALLOW_METHODS"

                       }

                   },

                   {

                       "name": "modifyOutgoingResponseHeader",

                       "options": {

                           "action": "MODIFY",

                           "avoidDuplicateHeaders": false,

                           "newHeaderValue": "origin,range,hdntl,hdnts",

                           "standardModifyHeaderName": "ACCESS_CONTROL_ALLOW_HEADERS"

                       }

                   },

                   {

                       "name": "modifyOutgoingResponseHeader",

                       "options": {

                           "action": "MODIFY",

                           "avoidDuplicateHeaders": false,

                           "newHeaderValue": "Server,range,hdntl,hdnts,Akamai-Mon-Iucid-Ing,Akamai-Mon-Iucid-Del,Akamai-Request-BC",

                           "standardModifyHeaderName": "ACCESS_CONTROL_EXPOSE_HEADERS"

                       }

                   },

                   {

                       "name": "modifyOutgoingResponseHeader",

                       "options": {

                           "action": "MODIFY",

                           "avoidDuplicateHeaders": false,

                           "newHeaderValue": "true",

                           "standardModifyHeaderName": "ACCESS_CONTROL_ALLOW_CREDENTIALS"

                       }

                   },

                   {

                       "name": "modifyOutgoingResponseHeader",

                       "options": {

                           "action": "MODIFY",

                           "avoidDuplicateHeaders": false,

                           "newHeaderValue": "86400",

                           "standardModifyHeaderName": "ACCESS_CONTROL_MAX_AGE"

                       }

                   }

               ],

               "criteria": [],

               "criteriaMustSatisfy": "all",

               "comments": ""

           }

       ],

       "behaviors": [

           {

               "name": "origin",

               "options": {

                   "originType": "MEDIA_SERVICE_LIVE",

                   "mslorigin": "{{hostname}}"

               }

           },

           {

               "name": "cpCode",

               "options": {

                   "value": {

                       "id": {{cpCode_AMD}}

                   }

               }

           },

           {

               "name": "segmentedMediaOptimization",

               "options": {

                   "behavior": "LIVE",

                   "enableUllStreaming": false,

                   "showAdvanced": false

               }

           },

           {

               "name": "originCharacteristics",

               "options": {

                   "authenticationMethod": "AUTOMATIC",

                   "country": "UNKNOWN",

                   "authenticationMethodTitle": ""

               }

           },

           {

               "name": "contentCharacteristicsAMD",

               "options": {

                   "catalogSize": "UNKNOWN",

                   "contentType": "HD",

                   "dash": true,

                   "hds": false,

                   "hls": true,

                   "popularityDistribution": "UNKNOWN",

                   "segmentDurationDASH": "SEGMENT_DURATION_2S",

                   "segmentDurationHLS": "SEGMENT_DURATION_2S",

                   "segmentSizeDASH": "UNKNOWN",

                   "segmentSizeHLS": "UNKNOWN",

                   "smooth": false

               }

           },

           {

               "name": "clientCharacteristics",

               "options": {

                   "country": "UNKNOWN"

               }

           },

           {

               "name": "cacheKeyQueryParams",

               "options": {

                   "behavior": "IGNORE_ALL"

               }

           },

           {

               "name": "segmentedContentProtection",

               "options": {

                   "enabled": false,

                   "hlsMediaEncryption": false,

                   "tokenAuthenticationTitle": "",

                   "mediaEncryptionTitle": ""

               }

           },

           {

               "name": "dynamicThroughtputOptimization",

               "options": {

                   "enabled": true

               }

           }

       ],

       "options": {

           "is_secure": false

       },

       "variables": []

   }

}

This will create an AMD configuration with a name you specify in the {{propertyName}} variable. It will use the livestreaming best practices settings and rely on 2 seconds HLS or DASH segments. You can update this if needed. It will also use your Media Services Live origin hostname as specified in the {{hostname}} variable.

If successful, you will receive a 201 Created.

{

   "propertyLink": "/papi/v0/properties/prp_647447?contractId=ctr_G-2Q80X7Z&groupId=grp_148539"

}

Next you can activate your AMD configuration on Akamai Staging or Akamai Production with the command:

POST https://{{host}}/papi/v1/properties/{{propertyId}}/activations

/[prism:generic]

5. Start your encoder and send your stream data to the Media Services Live Origin

Once the Media Services Live origin has been created and your Adaptive Media Delivery configuration has been created and deployed, you can start sending your stream from your encoder. You will have to push your stream over HTTPS to the Media Service Live Origin.

For more information on encoder support, please read: https://learn.akamai.com/en-us/webhelp/media-services-live/media-services-live-4-user-guide/GUID-DDACF319-12D3-4203-BFEA-EDC985C0A739.html

6. Play the stream in your favorite media player

Once everything is up and running, you can playback your stream in your favorite media player. The full URL syntax can be found here: https://learn.akamai.com/en-us/webhelp/media-services-live/media-services-live-4-user-guide/GUID-0A50253F-0B1B-406B-A8C9-3788CB42F950.html 

We hope that this blog has given you additional insight in how you can utilize the Media Services Live API to create your Media Services Live origin and stream endpoints. With the ability to create an Adaptive Media Delivery configuration with the Property Manager API, you can complete the Akamai workflow of livestreaming and delivery. Tying this together with your favorite encoder and media player, you have the ability to fully automate your livestreaming setup.