Media Services API Data Model

This section describes the various data objects the Media Services API exchanges.

Domain

Domain resources enable you to view existing domain configurations, add new versions to existing domains, create new domains, and delete domains. You can also look at the activation status and activate a particular domain version in the staging and production environments.

Sample Stream Packaging Domain configuration:

<?xml version="1.0" encoding="UTF-8"?>
<domain>
    <configuration-details>
        <configuration-name>TestConfig</configuration-name>
        <hostname>hello1234-lh.akamaihd.net</hostname>
        <reporting-cpcode>125213</reporting-cpcode>
        <configuration-type>Universal Streaming Live</configuration-type>
        <access-control-group>C-SYPLCV</access-control-group>
    </configuration-details>
    <archive-configuration>
        <archive-cpcode>7338</archive-cpcode>
        <archive-storage-location>EU/US preferred</archive-storage-location>
    </archive-configuration>
    <domain-versions>
        <domain-version>
            <delivery-formats>
                <hd-flash-1.0>Disabled</hd-flash-1.0>
                <adobe-hds>Disabled</adobe-hds>
                <apple-hls>Enabled</apple-hls>
            </delivery-formats>
            <security>
                <securehd-policy-editor>Enabled</securehd-policy-editor>
                <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
            </security>
            <advanced-configuration>
                <adobe-hds-advanced-config>
                    <hds-segment-duration>5</hds-segment-duration>
                </adobe-hds-advanced-config>
                <apple-hls-advanced-config>
                    <hls-segment-duration>10</hls-segment-duration>
                    <audio-only-stream-from-lowest-bitrate>Enabled</audio-only-stream-from-lowest-bitrate>
                </apple-hls-advanced-config>
            </advanced-configuration>
        </domain-version>
    </domain-versions>
</domain>

Sample HLS, HDS, and DASH Ingest Domain configuration

<?xml version="1.0" encoding="UTF-8"?>
<domain>
    <configuration-details>
        <configuration-name>TestConfig</configuration-name>
        <hostname>hello1234-i.akamaihd.net</hostname>
        <reporting-cpcode>125226</reporting-cpcode>
        <configuration-type>HD iPhone Live</configuration-type>
        <access-control-group>C-SYPLCV</access-control-group>
    </configuration-details>
    <archive-configuration>
        <archive-cpcode>22307</archive-cpcode>
        <archive-storage-location>Asia/EU preferred</archive-storage-location>
    </archive-configuration>
    <domain-versions>
        <domain-version>
            <segment-duration>11</segment-duration>
            <security>
                <securehd-policy-editor>Enabled</securehd-policy-editor>
                <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
            </security>
            <ingest-settings>
                <encoder-ips-allow-all>Enabled</encoder-ips-allow-all>
                <encoder-ips-cidr-blocks-list>
                    <encoder-ips-cidr-block>
                        <ip-or-cidr-block>1.2.43.5</ip-or-cidr-block>
                    </encoder-ips-cidr-block>
                </encoder-ips-cidr-blocks-list>
            </ingest-settings>
        </domain-version>
    </domain-versions>
</domain>

Domain Tags

Tag Type Description
Required
archive-configuration Domain.archive-configuration Contains details about the archive, such as archive CP code, archive name, domain name, and DVR pathname.
configuration-details Domain.configuration-details Contains details about the configuration, such as its name, hostname, reporting CP code, configuration type, and access control group.
domain-versions DomainVersion Specifies a set of domain versions.

Domain.archive-configuration

Contains details about the archive, such as archive CP code, archive name, domain name, and DVR pathname.

Tag Type Description
Required
archive-cpcode Number The storage group CP code associated with the configuration.
archive-name String The name of your domain archive configuration.
domain-name String The name of the domain you are connecting to.
dvr-path String The pathname of the digital video recorder.

Domain.configuration-details

Contains details about the configuration, such as its name, hostname, reporting CP code, configuration type, and access control group.

Tag Type Description
Required
access-control-group String If you have multiple contracts, specify which group you want the stream to be configured in.
configuration-name String The unique name that you give the configuration.
configuration-type String Type of configuration: Universal Streaming Live or On-Demand for Stream Packaging, or HD iPhone Live for HLS, HDS, and DASH ingest.
hostname String The hostname that you use for your domain. Ensure that this is a name that you own to prevent duplication with other users.
reporting-cpcode Number The CP code used for reporting and billing your streams.

DomainVersion

If you change the configuration’s security features, the system creates a new version of the configuration.

Sample Stream Packaging domain version configuration:

<?xml version="1.0" encoding="UTF-8"?>
<domain-version>
    <delivery-formats>
        <hd-flash-1.0>Disabled</hd-flash-1.0>
        <adobe-hds>Disabled</adobe-hds>
        <apple-hls>Enabled</apple-hls>
    </delivery-formats>
    <security>
        <securehd-policy-editor>Enabled</securehd-policy-editor>
        <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
    </security>
    <advanced-configuration>
        <adobe-hds-advanced-config>
            <hds-segment-duration>6</hds-segment-duration>
        </adobe-hds-advanced-config>
        <apple-hls-advanced-config>
            <hls-segment-duration>10</hls-segment-duration>
            <audio-only-stream-from-lowest-bitrate>Enabled</audio-only-stream-from-lowest-bitrate>
        </apple-hls-advanced-config>
    </advanced-configuration>
</domain-version>

Sample HLS, HDS, and DASH ingest domain version configuration:

<?xml version="1.0" encoding="UTF-8"?>
<domain-version>
    <segment-duration>12</segment-duration>
    <security>
        <securehd-policy-editor>Enabled</securehd-policy-editor>
        <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
    </security>
    <ingest-settings>
        <encoder-ips-allow-all>Enabled</encoder-ips-allow-all>
    </ingest-settings>
</domain-version>

DomainVersion Tags

Tag Type Description
Required
security DomainVersion.security Encapsulates security features for your configuration.
Optional
advanced-configuration DomainVersion.advanced-configuration Specifies advanced configuration for HDS and HLS. Required only for packaging streams.
delivery-formats DomainVersion.delivery-formats Enables or disables one of the following delivery formats: hd-flash-1.0 to enable FLV-delivery URLs, adobe-hds to enable Adobe HTTP Dynamic Streaming, or apple-hls to enable Apple HTTP Live Streaming. Required only for packaging streams.
ingest-settings Object Specifies the way you would like to authorize (by IP address) the encoder ability to broadcast streams associated with the configuration. Either allow all IPs with no restrictions, or add allowed encoder IP or IP Ranges (CIDR blocks), up to 50 entries allowed. Required only for passthrough streams.
segment-duration Number Specifies the length of your segment in seconds. This must be any value greater than 10. Required only for passthrough streams.

DomainVersion.advanced-configuration

Specifies advanced configuration for HDS and HLS. Required only for packaging streams.

Tag Type Description
Required
adobe-hds-advanced-config DomainVersion.advanced-configuration-hds Enables Adobe HTTP Dynamic Streaming advanced configuration.
apple-hls-advanced-config DomainVersion.advanced-configuration-hls Enables Apple HTTP Live Streaming advanced configuration.

DomainVersion.advanced-configuration-hds

Tag Type Description
Required
hds-segment-duration Number Specify a duration (between 2 and 6 seconds) for your segments/fragment. This value should be equal to, or a multiple of, your GOP interval. The default value is six seconds, which would work for one-, two-, three-, and six-second GOP sizes. If your interval is different from these values, set the appropriate value in this field. Setting this value incorrectly could cause undesirable bit rate switch downs in HDCore versions lower than 2.8.

DomainVersion.advanced-configuration-hls

Tag Type Description
Required
hls-segment-duration Number Specify a duration (between 2 and 60 seconds) for your segments/fragment.
audio-only-stream-from-lowest-bitrate Enumeration Specifies whether audio only stream from lowest bitrate is Enabled or Disabled. If it is enabled, Media Services Live automatically extracts an audio-only stream from your lowest published bit rate.

DomainVersion.delivery-formats

Enables or disables one of the following delivery formats: hd-flash-1.0 to enable FLV-delivery URLs, adobe-hds to enable Adobe HTTP Dynamic Streaming, or apple-hls to enable Apple HTTP Live Streaming. Required only for packaging streams.

Tag Type Description
Required
adobe-hds Enumeration Specifies whether Adobe HTTP Dynamic Streaming is Enabled or Disabled.
apple-hls Enumeration Specifies whether Apple Live Streaming is Enabled or Disabled.
hd-flash-1.0 Enumeration Specifies whether Flash delivery is Enabled or Disabled.

DomainVersion.security

Encapsulates security features for your configuration.

Tag Type Description
Required
securehd-policy-editor Enumeration Specifies whether the SecureHD policy editor is Enabled or Disabled. The SecureHD policy editor (SPE) is available only if this feature is included in your contract. For details about the SPE, see the SecureHD Policy Editor User’s Guide.
Optional
hd-flash DomainVersion.security.hd-flash Enables Flash (Media Services Live stream packaging) delivery.

DomainVersion.security.hd-flash

Tag Type Description
Required
player-verification Enumeration Specifies whether Player Verification is Enabled or Disabled. This option ensures that only player files you authorized are allowed to connect to your streams.
token-authorization Enumeration Specifies whether Token Authorization is Enabled or Disabled. Enable this option and specify the Token Authorization password. This is the shared secret between you and Media Services Live. If you enable Token Authorization for your configuration, it will apply on a URL basis to all streams using the configuration.
Optional
geo-blocking Enumeration Specifies whether Geo Blocking is Enabled or Disabled. Enables or disables blocking users based on their geographical location.

Stream

Stream resources enable you to add a new stream for an existing domain, edit a stream, and delete a stream. The Stream object encapsulates data for both packaged and passthrough stream types, including the encoder-settings tag required only for packaged stream types.

Sample HLS, HDS, and DASH stream configuration:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
    <stream-type>HD iPhone/iPad Live</stream-type>
    <stream-name>Streamhls</stream-name>
    <primary-contact-name>Jack King</primary-contact-name>
    <secondary-contact-name>Jane Doe</secondary-contact-name>
    <notification-email>jking@example.com</notification-email>
    <dvr-settings>
        <dvr>Enabled</dvr>
        <dvr-window>24</dvr-window>
    </dvr-settings>
</stream>

Sample Stream Packaging configuration, showing additional encoder-settings:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
    <stream-type>Universal Streaming Live</stream-type>
    <stream-name>MyStream</stream-name>
    <primary-contact-name>Jack King</primary-contact-name>
    <secondary-contact-name>Jane Doe</secondary-contact-name>
    <notification-email>jking@example.com</notification-email>
    <encoder-settings>
        <primary-encoder-ip>1.2.3.4</primary-encoder-ip>
        <backup-encoder-ip>8.8.8.8</backup-encoder-ip>
        <password>secret</password>
    </encoder-settings>
    <dvr-settings>
        <dvr>Enabled</dvr>
        <dvr-window>36</dvr-window>
    </dvr-settings>
</stream>

Stream Tags

Tag Type Description
Required
dvr-settings Stream.dvr-settings Specifies the amount of DVR time in your stream.
notification-email String The email that you send to notify the customer that the stream is successfully provisioned.
primary-contact-name String The primary person in your organization to contact regarding entry point availability issues.
secondary-contact-name String The secondary person in your organization to contact regarding entry point availability issues.
stream-id String A unique ID for your stream.
stream-name String The name for your stream. The stream name can be up to 20 characters long and can only include alphanumeric and underscore characters.
stream-type String Stream delivery type: HLS, HDS, or DASH.
Optional
encoder-settings Stream.encoder-settings Specifies the IP address of your primary and backup encoders used for the stream. Required for packaged stream types, not for passthrough streams.
entrypoints Stream.entrypoints.[n] Specifies the IP address of the primary and backup entrypoints that are obtaining the stream on Media Services Live.
hd-flash-1.0-playback-url String The URL that you use for playback. This is the value that you use in your client side Flash application’s connect() and play() methods.
hds-playback-url String The URL that you use for playback. This is the value that you use in your client side Flash application’s connect() and play() methods.
hls-playback-url String The URL that you use for playback.
security-1.0 Stream.security–1.0 Specifies security features (such as player verification and token authorization) for your configuration.
status String The status of the stream: Provisioned, Encoder IP Not Pingable, or Not Yet Provisioned.

Stream.dvr-settings

Specifies the amount of DVR time in your stream.

Tag Type Description
Required
dvr Enumeration The amount of DVR time in your stream. The values are: No DVR: Disables DVR and Archive/NetStorage. Use this setting only for 24x7 events. Unlimited DVR: Enables unlimited DVR time. Use this setting only for one-off events. Limited DVR: Enables you to specify the amount of DVR time. Use this setting only for 24x7 events. If your DVR time is greater than 30 minutes, archive storage on NetStorage is required.

Stream.encoder-settings

Specifies the IP address of your primary and backup encoders used for the stream. Required for packaged stream types, not for passthrough streams.

Tag Type Description
Required
backup-encoder-ip String The backup video encoder IP address.
password String Optionally, type a password for your encoder to use to access the entrypoints. Passwords can be made up of any character type, but must be no more than ten characters long. Leave this option blank if you want the system to generate a password.
primary-encoder-ip String The primary encoder IP address. Use two encoders with separate IP addresses for primary and backup for redundancy.
Optional
username String Type a user name that the encoder must use to access the entrypoints.

Stream.entrypoints.[n]  

Specifies the IP address of the primary and backup entrypoints that are obtaining the stream on Media Services Live.

Tag Type Description
Required
domain-name String The name of the domain in which you publish your stream.
type Enumeration The domain type: Primary or Backup.

Stream.security–1.0

Specifies security features (such as player verification and token authorization) for your configuration.

Tag Type Description
Required
player-verification Enumeration Indicates whether player verification is is Enabled or Disabled.
token-authorization Enumeration Indicates whether token authorization is is Enabled or Disabled.

Event

The Event resources enable you to specify details about your streaming event.

Sample event configuration:

<?xml version="1.0" encoding="UTF-8"?>
<event>
    <stream-id>10005</stream-id>
    <event-name>news_event</event-name>
    <primary-event>
        <archive-start-time>05/14/2015 19:42:10 AM</archive-start-time>
        <archive-end-time>06/14/2015 07:37:42 PM</archive-end-time>
    </primary-event>
    <backup-event>
        <archive-start-time>05/13/2015 19:42:10 AM</archive-start-time>
        <archive-end-time>06/15/2015 07:37:42 PM</archive-end-time>
    </backup-event>
</event>

Event Tags

Tag Type Description
Required
backup-event Event.* The backup event start date and time and end date and time.
event-name String The name of the event.
primary-event Event.* The primary event start date and time and end date and time.
stream-id String The numerical stream ID.

Event.*

Specifies the primary or backup event start and end time.

Tag Type Description
Required
archive-end-time String The date and time when the archive must end.
archive-start-time String The date and time when the archive must end.

Archive

Archive management resources enable you to view and update events for a stream.

Sample archive configuration:

<?xml version="1.0" encoding="UTF-8"?>
<archive-storage-locations>
    <archive-storage-location>
        <name>EU/EU preferred</name>
    </archive-storage-location>
</archive-storage-locations>

Archive Tags

Tag Type Description
Required
name String Name of the archived storage location.

Contact

Use the contact tags to configure the name of the people responsible for the stream entrypoints.

Sample Contact configuration:

<?xml version="1.0" encoding="UTF-8"?>
<contacts>
    <contact>
        <name>John Doe</name>
    </contact>
</contacts>

Contact Tags

Tag Type Description
Required
name String The name of the person responsible for the stream entrypoint’s availability.

Country

Use the country tag to specify the Country name and code.

Sample country configuration:

<?xml version="1.0" encoding="UTF-8"?>
<countries>
    <country>
        <country-code>AL</country-code>
        <country-name>ALBANIA</country-name>
    </country>
</countries>

Country Tags

Tag Type Description
Required
country-code String The two letter country code.
country-name String The country name.

CPCode

CP code resources enable you to specify the Content Provider code associated with the stream.A Content Provider code is necessary to track all web traffic handled by Akamai servers. It is supplied to you when you purchase a product, and you need it to activate any associated properties. You can generate additional CP codes, typically to implement more detailed billing and reporting functions and assign to custom properties.

Sample CP code configuration:

<?xml version="1.0" encoding="UTF-8"?>
<available-cpcode-list>
    <reporting-cpcode-list>
        <cpcode-list>
            <cpcode>567891</cpcode>
            <cpcode-name>MYCPCODE - Media Services Live</cpcode-name>
            <network-service-list>
                <USS_LIVE_SERVICE_TYPES>HD_Live::Universal_Streaming</USS_LIVE_SERVICE_TYPES>
                <network-service>
                    <service>Universal Streaming Live (Adobe Flash)</service>
                </network-service>
            </network-service-list>
            <top-level-group-list>
                <top-level-group>1-ABCDEF</top-level-group>
            </top-level-group-list>
        </cpcode-list>
    </reporting-cpcode-list>
</available-cpcode-list>

CPCode Tags

Tag Type Description
Required
cpcode Number The Content Provider code associated with the stream.
cpcode-name String The Content Provider code name associated with the stream.
network-service-list CPCode.network-service-list The network service list.
top-level-group-list Object The top-level CP code directory list.

CPCode.network-service-list

Tag Type Description
Required
IPHONE_LIVE_SERVICE_TYPES String The HLS service types.
NS_SERVICE_TYPES Array The Net Storage service types.
USS_LIVE_SERVICE_TYPES String The stream packaging service types.
network-service String The CP code network service types.

CPCode.network-service-list.network-service

Tag Type Description
Required
service String The CP code service: uss_live_service_types for Stream Packaging, iphone_live_service_type for Media Services Live, netstorage_services for Net Storage services.

Last modified: 12/13/2016