MSL Stream Provisioning API Resources

This section provides details on each API operation.

The following list provides a road map of all the conceptual objects you deal with when interacting with the MSL Stream Provisioning API, and provides pointers to where you can learn more.

  • Stream: This object contains configuration details for ingest streams. The Stream resources enables you to create an ingest stream, get a list of streams, get stream details, edit a stream, and delete a stream. See the Stream object type.

    To create an ingest stream using Media Services Live v4.1, you must set up the following:

    • Set up basic stream parameters.
    • Optionally, set up Media Services Live transcoding.
    • Set up DVR for the stream.
    • Set up Media Services Live origin for the stream.

    The process of creating or updating any stream changes its status to Pending. When all of the above steps complete, the stream status changes to Provisioned. If any of the above steps fail, the stream status changes to Failed.

    The typical time for any stream to get Provisioned is around two to three hours.

  • Origin: This object contains configuration for the origin of a stream. The Media Services Live origin feature enables you to publish live content, and retrieves it for delivery through the Akamai content delivery network (CDN). The feature is targeted primarily for OTT applications, but can also be used for other live specific events. Live origin has a publishing workflow and a delivery workflow. See the Origin object type.

    In the publishing workflow, you can directly push content from encoders into Live origin through the Akamai Ingest server.

    In the delivery workflow, you can pull the content that was earlier published into origin through a CDN.

API Summary

Operation Method Endpoint
MSL Ingest API   (download RAML)
List Streams GET /config-media-live/v1/msl-origin/streams{?page,pageSize,sortKey,sortOrder}
Create a Stream POST /config-media-live/v1/msl-origin/streams
Get Stream Details GET /config-media-live/v1/msl-origin/streams/{streamId}
Update a Stream PUT /config-media-live/v1/msl-origin/streams/{streamId}
Remove a Stream DELETE /config-media-live/v1/msl-origin/streams/{streamId}
List All Live Origins GET /config-media-live/v1/msl-origin/origins{?region,cpcode}
Get Live Origin Details GET /config-media-live/v1/msl-origin/origins/{id}
Get Activation Status GET /config-media-live/v1/msl-origin/origins/{id}/status
Create an Origin Version PUT /config-media-live/v1/msl-origin/origins/{id}/versions{?activate}
Activate an Origin Version PUT /config-media-live/v1/msl-origin/origins/{id}/versions/{version}/activate
Get Transcoding Presets GET /config-media-live/v1/msl-origin/presets

List Streams

Retrieves a list of all streams available to a user. Supports an optional request object for pagination and sorting of the results.

GET /config-media-live/v1/msl-origin/streams{?page,pageSize,sortKey,sortOrder}

Sample: /config-media-live/v1/msl-origin/streams?page=2&pageSize=10&sortKey=createdDate&sortOrder=ASC

Content-Type: application/json

Request Body:

{
    "pageSize": 25,
    "page": 1,
    "sortKey": "name",
    "sortOrder": "ASC"
}
Parameter Type Sample Description
Optional Query Parameters
page Integer 2 Specifies the number of pages.
pageSize Integer 10 Indicates the number of data points that are displayed per page. The default is to display all data if you do not specify the page size.
sortKey Enumeration createdDate Sorts the fields displayed based on the key that you specify. Possible enum values: cpcode, createdDate, dvrWindowInMin, format, modifiedDate, name, originHostName, status, zone.
sortOrder Enumeration ASC Sorts the streams list in ascending or decending order. Possible enum values: ASC, DESC, VERBOSE.

Status 200 application/json

Response Body:

{
    "totalSize": 5,
    "streams": [
        {
            "cpcode": 563423,
            "originHostName": "demo-host1.akamaiorigin.net",
            "provisionDetail": {
                "status": "PROVISIONED",
                "message": "Provisioned"
            },
            "format": "HLS",
            "dvrWindowInMin": -1,
            "encoderZone": "EUROPE",
            "modifiedDate": "2017-05-25T07:38:18.003Z",
            "isTranscodingEnabled": true,
            "id": 123456,
            "name": "DemoStream1"
        },
        {
            "cpcode": 652345,
            "originHostName": "demo-host2.akamaiorigin.net",
            "provisionDetail": {
                "status": "FAILED",
                "message": "Stream provisioning failed"
            },
            "format": "HLS",
            "dvrWindowInMin": 5,
            "encoderZone": "EUROPE",
            "modifiedDate": "2017-05-25T06:30:48.215Z",
            "isTranscodingEnabled": true,
            "id": 654768,
            "name": "DemoStream2"
        },
        {
            "cpcode": 123455,
            "originHostName": "demo-host3.akamaiorigin.net",
            "provisionDetail": {
                "status": "PENDING"
            },
            "format": "HLS",
            "dvrWindowInMin": 9,
            "encoderZone": "EUROPE",
            "modifiedDate": "2017-05-25T06:13:13.436Z",
            "isTranscodingEnabled": true,
            "id": 3276426,
            "name": "DemoStream3"
        }
    ],
    "page": 1,
    "pageSize": 10
}
  1. Form an optional PagingAndSorting object for sorting pagnation of the request.

  2. Make a GET request to /config-media-live/v1/msl-origin/streams.

Create a Stream

Provisions a new stream.

POST /config-media-live/v1/msl-origin/streams

Content-Type: application/json

Request Body:

{
    "cpcode": 345762,
    "origin": {
        "hostName": "sample.akamaiorigin.net"
    },
    "name": "DemoStream",
    "format": "HLS",
    "allowedIps": [
        "1.2.3.4"
    ],
    "ingestAccelerated": false,
    "encoderZone": "global",
    "additionalEmailIds": [
        "abc@akamai.com"
    ],
    "transcoding": {
        "masterPathNode": "masterpath",
        "format": "HLS",
        "source": [
            {
                "tracks": [
                    {
                        "type": "VIDEO"
                    },
                    {
                        "type": "METADATA"
                    }
                ],
                "segment": {
                    "suffix": ".ts",
                    "pathNode": "audiovideo"
                },
                "playlist": "program.m3u8",
                "pathNode": "audiovideo"
            }
        ],
        "masterPlaylist": "master.m3u8",
        "output": {
            "playlists": [
                {
                    "renditions": [
                        {
                            "width": 320,
                            "bitRate": 200000
                        },
                        {
                            "width": 320,
                            "bitRate": 400000,
                            "height": 200
                        }
                    ],
                    "name": "playlist1.m3u8"
                }
            ],
            "location": "output_folder"
        }
    }
}

Status 202

Headers:

Location: /streams/123
  1. Form a Stream object for the request.

  2. Make a POST request to /config-media-live/v1/msl-origin/streams.

Get Stream Details

Retrieves detailed information about the requested stream ID.

GET /config-media-live/v1/msl-origin/streams/{streamId}

Sample: /config-media-live/v1/msl-origin/streams/50005

Parameter Type Sample Description
URL Parameters
streamId Integer 50005 Unique identifier for each stream.

Status 200 application/json

Response Body:

{
    "cpcode": 123321,
    "origin": {
        "hostName": "demo-host1.akamaiorigin.net",
        "id": 541,
        "versions": []
    },
    "name": "DemoStream",
    "format": "HLS",
    "allowedIps": [],
    "id": 654345,
    "dvrWindow": 5,
    "backupPublishingUrl": "test2.akamaientrypoint.net",
    "ingestAccelerated": false,
    "encoderZone": "EUROPE",
    "additionalEmailIds": [
        "abc@akamai.com"
    ],
    "storageGroup": {
        "cpcode": 987678
    },
    "modifiedDate": "2017-05-25T07:38:18.003Z",
    "createdDate": "2017-05-25T07:38:18.003Z",
    "primaryPublishingUrl": "test1.akamaientrypoint.net",
    "transcoding": {
        "masterPathNode": "",
        "output": {
            "playlists": [
                {
                    "renditions": [
                        {
                            "width": 320,
                            "bitRate": 400000
                        },
                        {
                            "width": 320,
                            "bitRate": 200000
                        }
                    ],
                    "name": "master.m3u8"
                }
            ],
            "location": "postltc"
        },
        "masterPlaylist": "master.m3u8",
        "source": [
            {
                "tracks": [
                    {
                        "type": "VIDEO"
                    },
                    {
                        "type": "METADATA"
                    }
                ],
                "segment": {
                    "prefix": "",
                    "suffix": ".ts",
                    "pathNode": "qwerty"
                },
                "playlist": "mastervideo.m3u8",
                "pathNode": "qwerty"
            },
            {
                "tracks": [
                    {
                        "type": "AUDIO"
                    }
                ],
                "segment": {
                    "prefix": "",
                    "suffix": ".aac",
                    "pathNode": "qwert"
                },
                "playlist": "masteraudio.m3u8",
                "pathNode": "qwert"
            }
        ]
    },
    "events": [],
    "provisionDetail": {
        "status": "PENDING",
        "streamId": 345789
    }
}
  1. Run List Streams to get the value of the streamId URL parameter.

  2. Make a GET request to /config-media-live/v1/msl-origin/streams/{streamId}.

Update a Stream

Modifies an existing stream. The request body object must be identical in structure to the Get Stream Details response object.

You can edit the name, ingestAccelerated, password, dvrWindow, allowedIps, and additionalEmailIds fields. If you try to edit any other field, the API returns a 400 - Bad Request.

PUT /config-media-live/v1/msl-origin/streams/{streamId}

Sample: /config-media-live/v1/msl-origin/streams/50005

Content-Type: application/json

Request Body:

{
    "cpcode": 123432,
    "origin": {
        "hostName": "demoHost1.akamaiorigin.net",
        "id": 541,
        "versions": []
    },
    "name": "DemoStream1",
    "format": "HLS",
    "dvrWindow": 5,
    "ingestAccelerated": false,
    "encoderZone": "EUROPE",
    "additionalEmailIds": [],
    "transcoding": {
        "masterPathNode": "",
        "output": {
            "playlists": [
                {
                    "renditions": [
                        {
                            "width": 300,
                            "bitRate": 500000,
                            "height": 400
                        },
                        {
                            "width": 200,
                            "bitRate": 600000,
                            "height": 200
                        }
                    ],
                    "name": "master1.m3u8"
                },
                {
                    "renditions": [
                        {
                            "width": 230,
                            "bitRate": 1000000,
                            "height": 120
                        },
                        {
                            "width": 246,
                            "bitRate": 2000000,
                            "height": 124
                        }
                    ],
                    "name": "master2.m3u8"
                }
            ],
            "location": "testBasePath"
        },
        "masterPlaylist": "master.m3u8",
        "source": [
            {
                "tracks": [
                    {
                        "type": "VIDEO"
                    },
                    {
                        "type": "METADATA"
                    },
                    {
                        "type": "AUDIO"
                    }
                ],
                "isAudioEnabled": true,
                "segment": {
                    "suffix": ".ts",
                    "pathNode": "urlVideo01"
                },
                "playlist": "video01",
                "pathNode": "urlVideo01"
            },
            {
                "tracks": [
                    {
                        "type": "AUDIO"
                    }
                ],
                "segment": {
                    "suffix": ".aac",
                    "pathNode": "audioUrl"
                },
                "playlist": "audio01",
                "pathNode": "audioUrl"
            },
            {
                "tracks": [
                    {
                        "type": "SUBTITLES"
                    }
                ],
                "segment": {
                    "suffix": ".webvtt",
                    "pathNode": "Urlsubtitle"
                },
                "playlist": "subtite01",
                "pathNode": "Urlsubtitle"
            }
        ]
    },
    "id": 345698
}
Parameter Type Sample Description
URL Parameters
streamId Integer 50005 Unique identifier for each stream.

Status 202

  1. Run List Streams to get the value of the streamId URL parameter.

  2. Make a GET request to /config-media-live/v1/msl-origin/streams/{streamId}.

  3. Modify the Stream response object for your request.

  4. Make a PUT request to /config-media-live/v1/msl-origin/streams/{streamId}.

Remove a Stream

Deletes the specified Stream.

DELETE /config-media-live/v1/msl-origin/streams/{streamId}

Sample: /config-media-live/v1/msl-origin/streams/50005

Parameter Type Sample Description
URL Parameters
streamId Integer 50005 Unique identifier for each stream.

Status 200

  1. Run List Streams to get the value of the streamId URL parameter.

  2. Make a DELETE request to /config-media-live/v1/msl-origin/streams/{streamId}.

List All Live Origins

Retrieves a list of all Live Origins associated with the profile.

GET /config-media-live/v1/msl-origin/origins{?region,cpcode}

Sample: /config-media-live/v1/msl-origin/origins?region=Europe&cpcode=876213

Parameter Type Sample Description
Optional Query Parameters
cpcode Integer 876213 The Media Services Live Content Provider code.
region String Europe Specifies the geographical region where the origin is located.

Status 200 application/json

Response Body:

[
    {
        "cpcode": 765456,
        "storageCpcode": 987654,
        "hostName": "demo-host1.akamaiorigin.net",
        "location": "GERMANY",
        "createdDate": "2017-05-05",
        "id": null
    },
    {
        "cpcode": 765987,
        "storageCpcode": 678765,
        "hostName": "demo-host2.akamaiorigin.net",
        "location": "EUROPE",
        "createdDate": "2017-05-05",
        "id": null
    },
    {
        "cpcode": 146549,
        "storageCpcode": 678765,
        "hostName": "demo-host3.akamaiorigin.net",
        "location": "EUROPE",
        "createdDate": "2017-05-03",
        "id": null
    }
]

Get Live Origin Details

Retrieves the details of the specified Live Origin.

GET /config-media-live/v1/msl-origin/origins/{id}

Sample: /config-media-live/v1/msl-origin/origins/68

Parameter Type Sample Description
URL Parameters
id Integer 68 Unique identifier for each origin.

Status 200 application/json

Response Body:

{
    "cpcode": 876213,
    "status": "SUCCEEDED",
    "hostName": "demoHost1.akamaiorigin.net",
    "id": 68,
    "versions": [
        {
            "additionalHostNames": [],
            "notes": "Initial Version",
            "sslEnabled": false,
            "version": 1,
            "createdBy": "username",
            "createdDate": "2017-06-12T17:28:19.825Z",
            "active": true
        }
    ]
}
  1. Run List All Live Originsto get the value of the id URL parameter.

  2. Make a GET request to /config-media-live/v1/msl-origin/origins/{id}.

Get Activation Status

Retrieves the activation status of an origin.

GET /config-media-live/v1/msl-origin/origins/{id}/status

Sample: /config-media-live/v1/msl-origin/origins/68/status

Parameter Type Sample Description
URL Parameters
id Integer 68 Unique identifier for each origin.

Status 200 application/json

Response Body:

{
    "status": "PENDING"
}
  1. Run List All Live Originsto get the value of the id URL parameter.

  2. Make a GET request to /config-media-live/v1/msl-origin/origins/{id}/status.

Create an Origin Version

Creates a new live origin version. additionalHostnames enum values can have up to 16 alphanumeric and dot characters. Only alphabets, numerals and periods (.) are allowed.

PUT /config-media-live/v1/msl-origin/origins/{id}/versions{?activate}

Sample: /config-media-live/v1/msl-origin/origins/68/versions?activate=true

Content-Type: application/json

Request Body:

{
    "additionalHostnames": [
        "hello1.com",
        "hello2.com"
    ]
}
Parameter Type Sample Description
URL Parameters
id Integer 68 Unique identifier for each origin.
Required Query Parameters
activate Boolean true Enable this origin version.

Status 202 application/json

Response Body:

{
    "additionalHostnames": [
        "hello1.com",
        "hello2.com"
    ],
    "notes": "Additional Notes",
    "sslEnabled": false,
    "version": 8,
    "createdBy": "userName",
    "createdDate": "2017-03-13T09:46:31.276",
    "active": false
}
  1. Run List All Live Origins to get the value of the id URL parameter.

  2. Specify true for the activate parameter.

  3. Form an OriginVersionHostname object for the request.

  4. Make a PUT request to /config-media-live/v1/msl-origin/origins/{id}/versions{?activate}.

Activate an Origin Version

Activates the specified version of Live Origin.

PUT /config-media-live/v1/msl-origin/origins/{id}/versions/{version}/activate

Sample: /config-media-live/v1/msl-origin/origins/68/versions/2/activate

Parameter Type Sample Description
URL Parameters
id Integer 68 Unique identifier for each origin.
version Integer 2 Version of the origin.

Status 202 application/json

Response Body:

{
    "status": "PENDING"
}
  1. Run List All Live Originsto get the value of the id URL parameter.

  2. Make a GET request to /config-media-live/v1/msl-origin/origins/{id} to get the value of the version URL parameter.

  3. Make a PUT request to /config-media-live/v1/msl-origin/origins/{id}/versions/{version}/activate.

Get Transcoding Presets

Retrieves the Media Services Live transcoding preset values.

GET /config-media-live/v1/msl-origin/presets

Status 200 application/json

Response Body:

[
    {
        "renditions": [
            {
                "video": {
                    "width": 640,
                    "height": 360
                },
                "id": "video_1080p_8000k"
            }
        ],
        "name": "1080p",
        "format": "HLS"
    },
    {
        "renditions": [
            {
                "video": {
                    "width": 640,
                    "height": 360
                },
                "id": "video_sd_1000k"
            },
            {
                "video": {
                    "width": 640,
                    "height": 360
                },
                "id": "video_sd_800k"
            },
            {
                "video": {
                    "width": 320,
                    "height": 180
                },
                "id": "video_sd_200k"
            },
            {
                "video": {
                    "width": 320,
                    "height": 180
                },
                "id": "video_sd_400k"
            },
            {
                "video": {
                    "width": 640,
                    "height": 360
                },
                "id": "video_1080p_8000k"
            },
            {
                "video": {
                    "width": 480,
                    "height": 270
                },
                "id": "video_sd_600k"
            },
            {
                "video": {
                    "width": 1024,
                    "height": 576
                },
                "id": "video_sd_2500k"
            },
            {
                "video": {
                    "width": 768,
                    "height": 432
                },
                "id": "video_sd_1500k"
            },
            {
                "video": {
                    "width": 1280,
                    "height": 720
                },
                "id": "video_720p_4000k"
            }
        ],
        "name": "1080p-720p-sd",
        "format": "HLS"
    },
    {
        "renditions": [
            {
                "video": {
                    "width": 1280,
                    "height": 720
                },
                "id": "video_720p_4000k"
            }
        ],
        "name": "720p",
        "format": "HLS"
    },
    {
        "renditions": [
            {
                "video": {
                    "width": 640,
                    "bitRate": 1000000
                },
                "id": "hls_640_360_1000k"
            },
            {
                "video": {
                    "width": 1920,
                    "bitRate": 8000000
                },
                "id": "hls_1920_1080_8000k"
            },
            {
                "video": {
                    "width": 1280,
                    "bitRate": 4000000
                },
                "id": "hls_1280_720_4000k"
            },
            {
                "video": {
                    "width": 320,
                    "bitRate": 400000
                },
                "id": "hls_320_180_400k"
            },
            {
                "video": {
                    "width": 1024,
                    "bitRate": 2500000
                },
                "id": "hls_1024_576_2500k"
            },
            {
                "video": {
                    "width": 480,
                    "bitRate": 600000
                },
                "id": "hls_480_270_600k"
            },
            {
                "video": {
                    "width": 320,
                    "bitRate": 200000
                },
                "id": "hls_320_180_200k"
            },
            {
                "video": {
                    "width": 768,
                    "bitRate": 1500000
                },
                "id": "hls_768_432_1500k"
            },
            {
                "video": {
                    "width": 640,
                    "bitRate": 800000
                },
                "id": "hls_640_360_800k"
            }
        ],
        "name": "pankaj:hls_upto_1080p",
        "format": "HLS"
    },
    {
        "renditions": [
            {
                "video": {
                    "width": 640,
                    "bitRate": 1000000,
                    "frameRate": 10,
                    "height": 360
                },
                "id": "hls_640_360_1000k"
            },
            {
                "video": {
                    "width": 1920,
                    "bitRate": 8000000
                },
                "id": "hls_1920_1080_8000k"
            },
            {
                "video": {
                    "width": 1280,
                    "bitRate": 4000000
                },
                "id": "hls_1280_720_4000k"
            },
            {
                "video": {
                    "width": 320,
                    "bitRate": 400000
                },
                "id": "hls_320_180_400k"
            },
            {
                "video": {
                    "width": 1024,
                    "bitRate": 2500000
                },
                "id": "hls_1024_576_2500k"
            },
            {
                "video": {
                    "width": 480,
                    "bitRate": 600000
                },
                "id": "hls_480_270_600k"
            },
            {
                "video": {
                    "width": 320,
                    "bitRate": 200000
                },
                "id": "hls_320_180_200k"
            },
            {
                "video": {
                    "width": 768,
                    "bitRate": 1500000
                },
                "id": "hls_768_432_1500k"
            },
            {
                "video": {
                    "width": 640,
                    "bitRate": 800000
                },
                "id": "hls_640_360_800k"
            }
        ],
        "name": "test-preset",
        "format": "HLS"
    }
]

Last modified: 10/25/2017