Alexa Music, Radio, and Podcast Skill API Components Reference

This page describes the objects within the Music Skill API request and response messages. The objects are listed alphabetically.

AdManifest

The base structure for all ad manifest objects. Contains ad specification and supports the type field. See VastManifest.

Structure

Field Description Required Type

type

Type of ad manifest.

yes

string

AdMetadata

Contains metadata for an ad item.

Structure

AdMetadata extends BaseMetadata where type is set to AD. In addition to base fields, AdMetadata has the following field.

Field Description Required Type

manifest

An AdManifest object that contains additional information about this ad item.

no

object

Examples

{
  "type": "AD",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "some advertisement"
    },
    "display": "Some advertisement"
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  },
  "manifest": {
    "type": "VAST",
    "uri": "https://example.com/ad/manifest/some-vast.xml"
  }
}

Advertising

The Advertising object provides the customer's advertising ID and preference for receiving interest-based ads. Alexa includes the Advertising object in requests to music skills that declare that the skill delivers advertising. For more details, see About Alexa Advertising ID.

Structure

Property Description Type Required

advertisingId

Customer-resettable, unique identifier that maps to the ifa attribute of the OpenRTB API specification.

Formatted as a version 4 UUID string separated by dashes (8-4-4-4-12).
Example: E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367

String

Yes

limitAdTracking

Indicates whether the customer wants to receive interest-based ads. Set to true when the customer opts out of interest-based ads and tracking.
The limitAdTracking property maps to the lmt attribute of the OpenRTB API specification.

Boolean

Yes

Examples

The following examples show settings that indicate that the customer opted out of interest-based ads and tracking.

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": true
}

"advertising": {
    "advertisingId": "00000000-0000-0000-0000-00000000",
    "limitAdTracking": true
}

The following example shows settings that indicate that the customer opted in to interest-based ads and tracking.

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": false
}

Art

Contains artwork for a media content. Images must be in PNG or JPG file format. For other requirements for Alexa skill content, including background images, see Policy Requirements.

Synonyms

Cover Art, Cover, Program Series Art

Structure

Field Description Required Type
contentDescription Description of the art for accessibility purposes. Optional but recommended. no string
sources List of ArtSource objects each describing one size of the art. See the ArtSource object for more information. yes list

Examples

{
  "contentDescription": "A close-up picture of the artist Lady Gaga.",
  "sources": [
    {
      "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
      "size": "X_SMALL",
      "widthPixels": 48,
      "heightPixels": 48
    },
    {
      "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
      "size": "SMALL",
      "widthPixels": 60,
      "heightPixels": 60
    },
    {
      "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
      "size": "MEDIUM",
      "widthPixels": 110,
      "heightPixels": 110
    },
    {
      "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
      "size": "LARGE",
      "widthPixels": 256,
      "heightPixels": 256
    },
    {
      "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
      "size": "X_LARGE",
      "widthPixels": 600,
      "heightPixels": 600
    }
  ]
}

ArtSource

Contains information about a single size of a media content's art (for example, album cover art). Images must be in PNG or JPG file format. For other requirements for Alexa skill content, including background images, see Policy Requirements.

Synonyms

Cover Art Image, Cover URL

Structure

Field Description Required Type
url The URL for the image of this size. URL must be HTTPS. yes string
size The size for the image. Alexa can use this optional field to help determine which size of ArtSource to use. If the skill knows the exact image dimensions and populates widthPixels or heightPixels, the skill should also populate this field to the appropriate size based on those values. However, this field can be populated without having to specify widthPixels or heightPixels if unknown. If an image size is unknown then this field can be left blank. Valid values and recommended image sizes for each:
"X_SMALL" (recommended for images approximately 48 x 48 pixels)
"SMALL" (recommended for 60 x 60 pixels)
"MEDIUM" (recommended for 110 x 110 pixels)
"LARGE" (recommended for 256 x 256 pixels)
"X_LARGE" (recommended for 600 x 600 pixels)		 no string
widthPixels The exact width of the image in pixels, if known. If unknown, omit this field. no integer
heightPixels The exact height of the image in pixels, if known. If unknown, omit this field. no integer

Examples

{
  "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
  "size": "X_SMALL",
  "widthPixels": 48,
  "heightPixels": 48
}

Background

The base structure for background image object types. This structure appears as the background field of the BaseMetadata object. Don't use the Background object type directly. Instead, use one of the Background object subtypes. Currently StaticImagesBackground is the only subtype.

Structure

Field Description Required Type
type A string describing the type of background image. Currently the only possible value is "STATIC_IMAGES". yes enum

Examples

{
    "type": "STATIC_IMAGES"
}

BackgroundImage

Contains a single image for Alexa to display in the background while music is playing.

Structure

Field Description Required Type
art An Art object containing the image. yes object

Examples

{
    "art": {
        "contentDescription": "",
        "sources": [{
            "url": "url",
            "size": "LARGE",
            "widthPixels": 256,
            "heightPixels": 256
        }]
    }
}

BaseControl

BaseControl captures the base structure that's extended by ItemControl and QueueControl.

Structure

Field Description Required Type
type The type of the control. This can be one of the following:
ADJUST - for controls such as seeking
COMMAND - for controls such as skipping		 yes string
name The name of the control.

For type ADJUST, the value for name can be one of the following:
SEEK_POSITION - enables user to seek forward and back within a currently playing track

For type COMMAND, the value for name can be one of the following:
NEXT - for skipping to the next item
PREVIOUS - for skipping to the previous item		 yes string
enabled Informs Alexa whether the control is enabled. For some control types, this determines whether the button for the control should be clickable: set the value to true when the control should be clickable by the user in the Alexa app. yes Boolean

Examples

{
  "type": "COMMAND",
  "name": "NEXT",
  "enabled": true
}

BaseMetadata

The base structure for all metadata objects.

Structure

Field Description Required Type
type Type of the metadata. The values for this field are different for each subtype of BaseMetadata. The type field determines what fields are expected in addition to the ones in the BaseMetadata object. yes string
name MetadataNameProperty object containing the name of the item to which this metadata applies, such as the name of an album or playlist. For example, this could be used in an Alexa voice prompt spoken before content begins to play. yes object
art An Art object containing specific artwork for the item to which this metadata applies, such as an album cover. yes object
background A Background object containing metadata for the background image that Alexa displays while music is playing. no object

Examples

The following example is for artwork that Alexa displays in playlists and search results.

{
  "type": "ARTIST",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "nirvana"
    },
    "display": "Nirvana"
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

The following example is for background images that Alexa displays when music is playing.

{
    "type": "TRACK",
    "name": {
        "speech": "",
        "display": ""
    },
    "art": {
        "contentDescription": "",
        "sources": [{
            "url": "url",
            "size": "LARGE",
            "widthPixels": 256,
            "heightPixels": 256
        }]
    },
    "background": {
        "type": "STATIC_IMAGES",
        "images": [{
            "art": {
                "contentDescription": "",
                "sources": [{
                    "url": "url",
                    "size": "LARGE"
                }]
            }
        }]
    }
}

Content

The content object includes an identifier (reference) and metadata (for example, album name, author name, title, type, etc.). The content object can represent a single track, an album, a playlist, a custom station, a live station, or a program. content objects are global and can be shared between different users. For example, if content object 1234 is the album "King Animal" by Soundgarden, this is true for any user who receives content object 1234, and if a user receives content object 1234 a year later, it should still represent the album King Animal by Soundgarden.

The content object is the primary object for the Alexa.Media.Search interface.

Structure

Field Description Required Type
id Globally (in the skill's domain) unique identifier of the content (for example, album ID, playlist ID, track ID, etc.). Note that this identifier should uniquely identify some piece of content like an album or a playlist or a track. yes string
actions An object describing whether the content is playable, browsable, or both. Note that this field should only be present for content returned for display use cases. See the ContentActions object for more details. no object
metadata Metadata for the content. The value is an instance of MediaMetadata. See the MediaMetadata object for more details. yes object
playQueuePreview An object that previews the metadata of the items that play in the play queue when the item is initiated. For details, see PlayQueuePreview. no object

Examples

The following examples show artist, track, and album objects.

Example artist

{
  "id": "1021012f-12bb-4938-9723-067a4338b6d0",
  "actions": {
    "playable": true,
    "browsable": false
  },
  "metadata": {
    "type": "ARTIST",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "macklemore"
      },
      "display": "Macklemore"
    },
    "art": {
      "sources": [
        {
          "url": "https:example.com/images/cover/48x48.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        },
        {
          "url": "https:example.com/images/cover/60x60.jpg",
          "size": "SMALL",
          "widthPixels": 60,
          "heightPixels": 60
        },
        {
          "url": "https:example.com/images/cover/110x110.jpg",
          "size": "MEDIUM",
          "widthPixels": 110,
          "heightPixels": 110
        },
        {
          "url": "https:example.com/images/cover/256x256.jpg",
          "size": "LARGE",
          "widthPixels": 256,
          "heightPixels": 256
        },
        {
          "url": "https:example.com/images/cover/600x600.jpg",
          "size": "X_LARGE",
          "widthPixels": 600,
          "heightPixels": 600
        }
      ]
    }
  }
}

Example track

{
  "id": "1021012f-12bb-4938-9723-067a4338b6d0",
  "actions": {
    "playable": true,
    "browsable": false
  },
  "metadata": {
    "type": "TRACK",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "remember high school"
      },
      "display": "Remember High School"
    },
    "authors": [
      {
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "macklemore"
          },
          "display": "Macklemore"
        }
      }
    ],
    "album": {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "the language of my world"
        },
        "display": "The Language of My World"
      }
    },
    "art": {
      "sources": [
        {
          "url": "https:example.com/images/cover/48x48-000000-80-0-0.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        },
        {
          "url": "https:example.com/images/cover/60x60-000000-80-0-0.jpg",
          "size": "SMALL",
          "widthPixels": 60,
          "heightPixels": 60
        },
        {
          "url": "https:example.com/images/cover/110x110-000000-80-0-0.jpg",
          "size": "MEDIUM",
          "widthPixels": 110,
          "heightPixels": 110
        },
        {
          "url": "https:example.com/images/cover/256x256-000000-80-0-0.jpg",
          "size": "LARGE",
          "widthPixels": 256,
          "heightPixels": 256
        },
        {
          "url": "https:example.com/images/cover/600x600-000000-80-0-0.jpg",
          "size": "X_LARGE",
          "widthPixels": 600,
          "heightPixels": 600
        }
      ]
    }
  }
}

Example album


{
  "id": "1021012f-12bb-4938-9723-067a4338b6d0",
  "actions": {
    "playable": true,
    "browsable": false
  },
  "metadata": {
    "type": "ALBUM",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "the language of my world"
      },
      "display": "The Language of My World"
    },
    "authors": [
      {
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "macklemore"
          },
          "display": "Macklemore"
        }
      }
    ],
    "art": {
      "sources": [
        {
          "url": "https:example.com/images/cover/48x48.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        },
        {
          "url": "https:example.com/images/cover/60x60.jpg",
          "size": "SMALL",
          "widthPixels": 60,
          "heightPixels": 60
        },
        {
          "url": "https:example.com/images/cover/110x110.jpg",
          "size": "MEDIUM",
          "widthPixels": 110,
          "heightPixels": 110
        },
        {
          "url": "https:example.com/images/cover/256x256.jpg",
          "size": "LARGE",
          "widthPixels": 256,
          "heightPixels": 256
        },
        {
          "url": "https:example.com/images/cover/600x600.jpg",
          "size": "X_LARGE",
          "widthPixels": 600,
          "heightPixels": 600
        }
      ]
    }
  }
}

ContentActions

An object describing whether a content object represents content that's playable, browsable, or both.

The flags in this object are intended to support display use cases where the user can click a content object to play all its contents (for example, play an entire album) or the user can click a content object to view the items within (for example, see the tracks listing for the album) and perhaps play one item.

Structure

Field Description Required Type
playable Determines whether the content is playable. Defaults to true. no Boolean
browsable Determines whether the content is browsable. no Boolean

Examples

{
  "playable": true,
  "browsable": false
}

ContentFormat (Premium audio only)

Supplies a content type identifier for the type of content that can be played on an Alexa device. Specific content type identifiers are provided by the music service provider as part of onboarding their skill. When content type identifiers are sent in a Music Skill SPI request to a skill, the request contains only identifiers that were previously provided by the provider. No request ever contains an identifier that's supported by some other provider.

Synonyms

Content Type, Content Type Identifier, Content Format Type

Structure

Field Description Required Type
type The content type. For Music Skills APIs the only supported value is AUDIO. yes string
contentTypeId The content type identifier (provided by the MSP) that the target device supports. yes string

Examples

{
  "type" : "AUDIO",
  "contentTypeId": "CT-1234"
}

Endpoint (Premium audio only)

Contains information about the audio player on the target device.

This object might be present in the Request Context for the following Music Skill APIs:

A list of Endpoint objects might be present in the payload for the following Music Skill API:

The Endpoint object isn't used in any of the other Music Skill APIs. If a provider doesn't support premium audio, or alternate audio quality streams, this object isn't present in any requests. This object is present only in V3 API requests when the provider supports premium audio or alternate audio quality streams.

Synonyms

Audio Player Metadata, Audio Player

Structure

Field Description Required Type
id The endpoint identifier. This identifier is either a UUID or some other opaque identifier. If it is a UUID, providers shouldn't attach any meaning to the endpoint identifier, as it may be different between requests, even for the same customer and device. yes string
players A list of Player objects that provide metadata about the playback device. yes list

Examples

{
  "id": "bi39pe0g5k0pqo42phdtffk7iv8da1bx",
  "players": [
    {
      "playbackMethodType": "ALEXA_AUDIO_PLAYER_QUEUE",
      "id": "AudioPlayer",
      "properties": {
        "supportedContentFormats": [
          {
            "type": "AUDIO",
            "contentTypeId": "CT-1234"
          },
          {
            "type": "AUDIO",
            "contentTypeId": "CT-1235"
          },
          {
            "type": "AUDIO",
            "contentTypeId": "CT-1236"
          }
        ]
      }
    }
  ]
}

EntityMetadata

Metadata for entities like artists, songs, etc.

Structure

Field Description Required Type
name Name of the entity to be used in Alexa voice prompts or for display use cases. See the MetadataNameProperty object for details. yes object

Examples

{
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "rap god"
    },
    "display": "Rap God (Explicit)"
  }
}

EntityType

The following list contains all entity types supported by the Alexa Music, Radio, and Podcast Skill API:

  • TRACK – a song like Lady Gaga's "Gypsy"
  • ALBUM – an album like Lady Gaga's "ARTPOP"
  • ARTIST – an artist like "Lady Gaga"
  • PLAYLIST – a playlist like "Relaxing Sounds"
  • GENRE – a genre like "Jazz"
  • STATION – a station like "C.N.N."
  • MEDIA_TYPE – describes different types of audio content, for example, SONG or PROGRAM_SERIES
  • RELEASE_WINDOW – (Podcast only) the release date window
  • SORT_TYPE – describes whether audio contents or selection criteria should be ranked by POPULARITY or RECENCY before being returned to Alexa
  • FOLLOW_STATUS – (Podcast only) indicates whether the user follows or subscribes to a program series
  • TOPIC_NAME - (Podcast only) describes the topic of a program series. See Implement episode search by topic.
  • PLAY_STATUS - Indicates whether the customer has played the content.

Feedback

Describes the user's feedback or preference about an item. For example, if the user had previously indicated "thumbs up" for the item, the skill should set the feedback type to PREFERENCE and the feedback value to POSITIVE.

This component is an optional field that the skill provides in the response payload of the Initiate, GetItem, GetNextItem, and GetPreviousItem directives. Alexa uses this information to display the user's previously-indicated feedback in the Alexa app and on Alexa-enabled devices with a screen. Alexa doesn't send any information to the skill when a user provides feedback about an item.

Synonyms

Preference, Thumbs Up/Down

Structure

Field Description Required Type
type The type of feedback. This only supported value is PREFERENCE. yes string
value The value of feedback. Can be either POSITIVE or NEGATIVE. yes string

Examples

{
    "type": "PREFERENCE",
    "value": "POSITIVE"
}

Filters

An object which describes filters that the skill should apply to search results (selection criteria and content) before returning a response to the Alexa service.

Structure

Field Description Required Type
explicitLanguageAllowed Determines whether results with explicit language are allowed. yes Boolean

Examples

{
  "explicitLanguageAllowed": true
}

HeaderCategory (DRM)

HeaderCategory extends HeaderType and contains the list of HTTP headers for each category.

Structure

Field Description Required Type
type One of the following values:

KEY - Fetch the License.
MANIFEST - Fetch the manifests and variants of an item.
AUDIOSEGMENT - Fetch the audio chunks that are described by the manifest.
ALL - The device sends this header type in all calls related to the uniform resource indicator (URI) for an item.		 yes enum
headers List of all headers in the HeaderType category. Maximum list size is 20 headers. yes list of HttpHeader objects

Examples

{
    "type" : "KEY"
}

HeaderType (DRM)

HeaderType specifies the purpose of the header the device sends to the music service provider.

Structure

Field Description Required Type
type One of the following values:

KEY - Fetch the License.
MANIFEST - Fetch the manifests and variants of an item.
AUDIOSEGMENT - Fetch the audio chunks that are described by the manifest.
ALL - The device sends this header type in all calls related to the URI for an item.		 yes enum

Examples

{
    "type": "KEY",
    "headers": [
        {
            "name": "X-AlexaMusic-ExampleMsp-LicenseToken",
            "value": "fbfd3378-a72d-45ef-9782-4edf140f5dd7"
         }
     ]
}

HttpHeader (DRM)

HttpHeader represents an HTTP header used for Digital Rights Management (DRM).

Structure

Field Description Required Type
name Name of the HTTP header. Limited to "Authorization" and strings prefixed with "x-". Maximum length is 256 single-byte characters. yes string
value Value of the HTTP header. Maximum length is 4096 single-byte characters. yes string

Examples

{
        "name": "X-AlexaMusic-Example-LicenseUrl",
        "value": "https://Example.com/license/"
}

Item

An (audio) item that contains within it an identifier and metadata (for example, art URLs, author name, title, etc.), and a Stream containing the playback URL. Note that in some cases, the duration of an item needs to be displayed when there is no stream for that item. That is why the duration field is a peer to the stream field and not a member of it.

Synonyms

Audio Item, Track, Song, Program

Structure

Field Description Required Type

id

A identifier for the item that is opaque to Alexa. Note that the item should be unique within the queue.

yes

string

playbackInfo

Describes which business rules Alexa should run when playing or displaying this item. See the PlaybackInfo object for details.

yes

string

metadata

Metadata for the item.

For playbackInfo types DEFAULT and SAMPLE, the value is an instance of MediaMetadata, where the metadata type field can be TRACK (for music), STATION (for radio), or PROGRAM (for podcasts). See the MediaMetadata object for details.
For playbackInfo type AD, the value is an instance of AdMetadata. See the AdMetadata object for details.
(
Note: Ads aren't supported for podcasts.)

yes

object

durationInMilliseconds

Duration of the item in milliseconds. If the item is a live stream, do not return this field.

no

long

controls

List of ItemControl objects used by Alexa to determine which controls should be clickable in the Alexa app.

no

list

rules

Object which contains rules for the item. See ItemRules for details.

yes

object

stream Object that contains stream information for this item. See the Stream object for more information.

yes

object

feedback

User's feedback about the item, if it exists. For example, if the user had previously indicated "thumbs up" for this item, the skill should set the feedback type to PREFERENCE and the feedback value to POSITIVE. See the Feedback object for more information.

no

object

Examples

{
  "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
  "playbackInfo": {
    "type": "DEFAULT"
  },
  "metadata": {
    "type": "TRACK",
    "name": {
      "speech": {
        "type": "PLAIN_TEXT",
        "text": "gypsy"
      },
      "display": "Gypsy"
    },
    "authors": [
      {
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "lady gaga"
          },
          "display": "Lady Gaga"
        }
      }
    ],
    "album": {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "art pop"
        },
        "display": "ARTPOP"
      }
    },
    "art": {
      "sources": [
        {
          "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
          "size": "X_SMALL",
          "widthPixels": 48,
          "heightPixels": 48
        },
        {
          "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
          "size": "SMALL",
          "widthPixels": 60,
          "heightPixels": 60
        },
        {
          "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
          "size": "MEDIUM",
          "widthPixels": 110,
          "heightPixels": 110
        },
        {
          "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
          "size": "LARGE",
          "widthPixels": 256,
          "heightPixels": 256
        },
        {
          "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
          "size": "X_LARGE",
          "widthPixels": 600,
          "heightPixels": 600
        }
      ]
    }
  },
  "durationInMilliseconds": 248000,
  "controls": [
    {
      "type": "COMMAND",
      "name": "NEXT",
      "enabled": true
    },
    {
      "type": "COMMAND",
      "name": "PREVIOUS",
      "enabled": false
    }
  ],
  "rules": {
    "feedbackEnabled": true
  },
  "stream": {
    "id": "STREAMID_92_14629004",
    "uri": "http://cdn.example.com/api/1/a2f318467fbf282999|6adc0880e0abd03d03b1ba6ac.mp3",
    "offsetInMilliseconds": 0,
    "validUntil": "2018-05-10T19:11:35Z"
  },
  "feedback": {
    "type": "PREFERENCE",
    "value": "POSITIVE"
  }
}

{
    "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
    "playbackInfo": {
        "type": "DEFAULT"
    },
    "metadata": {
        "type": "PROGRAM",
        "name": {
            "speech": {
                "type": "PLAIN_TEXT",
                "text": "[PROGRAM_NAME]"
            },
            "display": "[PROGRAM_NAME]"
        },
        "series": {
            "name": {
                "speech": {
                    "type": "PLAIN_TEXT",
                    "text": "[PROGRAM_SERIES_NAME]"
                },
                "display": "[PROGRAM_SERIES_NAME]"
            }
        },
        "art": {
            "sources": [
                {
                    "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
                    "size": "X_SMALL",
                    "widthPixels": 48,
                    "heightPixels": 48
                },
                {
                    "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
                    "size": "SMALL",
                    "widthPixels": 60,
                    "heightPixels": 60
                },
                {
                    "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
                    "size": "MEDIUM",
                    "widthPixels": 110,
                    "heightPixels": 110
                },
                {
                    "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
                    "size": "LARGE",
                    "widthPixels": 256,
                    "heightPixels": 256
                },
                {
                    "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
                    "size": "X_LARGE",
                    "widthPixels": 600,
                    "heightPixels": 600
                }
            ]
        }
    },
    "durationInMilliseconds": 318000,
    "controls": [
        {
            "type": "COMMAND",
            "name": "NEXT",
            "enabled": true
        },
        {
            "type": "COMMAND",
            "name": "PREVIOUS",
            "enabled": true
        },
        {
            "type": "ADJUST",
            "name": "SEEK_POSITION",
            "enabled": true
        }
    ],
    "rules": {
        "feedbackEnabled": true
    },
    "stream": {
        "id": "STREAMID_92_14629004",
        "uri": "https://cdn.example.com/api/1/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
        "offsetInMilliseconds": 60000,
        "validUntil": "2018-05-10T19:11:35Z"
    },
    "feedback": {
        "type": "PREFERENCE",
        "value": "POSITIVE"
    }
}

ItemControl

An object that describes a control that the user can take on an item. Examples are skip forward and skip backward buttons. Note that item controls will override any existing queue controls of the same type.

Synonyms

Track Button Control

Structure

The object has the same structure as BaseControl.

Examples

{
  "type": "COMMAND",
  "name": "NEXT",
  "enabled": true
}

ItemReference

Identifiers to identify a specific Item.

Structure

Field Description Required Type
id The Item identifier. yes string
queueId The ID of the Queue containing the Item. yes string
contentId Content identifier that uniquely identifies the content to be played on the device. For more information, see Understand contentId. yes string

Examples

{
  "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
  "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
  "contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}

ItemRules

Describes rules for what the user can do with an item. One example of a rule is whether the user can provide feedback about an audio item. Note that item level rules will override queue level rules.

Synonyms

Item Rules

Structure

Field Description Required Type
feedbackEnabled Determine whether the user is allowed to provide feedback for a given item. Defaults to the flag specified in the QueueFeedbackRule. no Boolean

Examples

{
  "feedbackEnabled": false
}

Location

Describes the location of a request. Use this information to enforce geographical restrictions on content or decide which language version of metadata to return to Alexa for media items.

Structure

Field Description Required Type
originatingLocale The locale for the user. This is the locale that the user specified based on the language setting on the device. When the locale isn't required for the skill to process a request, this field may be absent. Following are the supported values: de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, it-IT, ja-JP, pt-BR. no string
countryCode Code (based on ISO 3166-1 alpha-2) for the country where the request was made. This might be the country of the registered account of the user who made the request, or the country of the target device owned by that user. no string

Examples

{
  "originatingLocale": "en-US",
  "countryCode": "US"
}

MediaMetadata

Contains metadata (for example, album name, author name, title, "type", etc.) for a media item (i.e., Content or Item).

Base structure

MediaMetadata extends BaseMetadata, and supports the following metadata types:

  • ALBUM - for an album (Music only)
  • ARTIST - for an artist (Music only)
  • GENRE - for a genre (Music only)
  • PLAYLIST - for a playlist
  • PROGRAM - for a program (episode) or program series (Podcast only)
  • STATION - for a station (Radio only)
  • TRACK - for a track/song (Music only)

Structure for ALBUM

In addition to base fields, ALBUM has the following field.

Field Description Required Type
authors A list of EntityMetadata objects for the authors of the album. This is used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. yes list

Structure for ARTIST, GENRE, PLAYLIST, and STATION

These types have the same structure as the base.

Structure for PROGRAM (Podcast only)

In addition to base fields, PROGRAM has the following fields.

Field Description Required Type
authors A list of EntityMetadata objects for the authors of the album. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. yes list
series An EntityMetadata object for the series of programs containing the content. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. Required for subscription playback. object
releaseDate Publication date of this program. no ISO-8601 String
programNumber The ordinal number of this program. no integer
season Information about the season. See the Season object for more information. no object

Structure for PROGRAM_SERIES (Podcast only)

In addition to base fields, PROGRAM_SERIES has the following fields.

Field Description Required Type
authors A list of EntityMetadata objects for the authors of the album. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. yes list

Structure for TRACK

In addition to base fields, TRACK has the following fields.

Field Description Required Type
authors A list of EntityMetadata objects for the authors of the album containing the content. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. no list
album An EntityMetadata object for the album that contains the content. This is usually used in the Alexa voice prompt spoken before the content begins to play. See the EntityMetadata object for more information. no object

Examples - ALBUM

{
  "type": "ALBUM",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "art pop"
    },
    "display": "ARTPOP"
  },
  "authors": [
    {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "lady gaga"
        },
        "display": "Lady Gaga"
      }
    }
  ],
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Examples - ARTIST

{
  "type": "ARTIST",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "lady gaga"
    },
    "display": "Lady Gaga"
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Examples - STATION

{
  "type": "STATION",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "c n n"
    },
    "display": "C.N.N."
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

Examples - TRACK

{
  "type": "TRACK",
  "name": {
    "speech": {
      "type": "PLAIN_TEXT",
      "text": "thrift shop"
    },
    "display": "Thrift Shop"
  },
  "authors": [
    {
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "macklemore"
        },
        "display": "Macklemore"
      }
    }
  ],
  "album": {
    "name": {
      "speech": {
        "type": "",
        "text": ""
      },
      "display": ""
    }
  },
  "art": {
    "sources": [
      {
        "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
        "size": "X_SMALL",
        "widthPixels": 48,
        "heightPixels": 48
      },
      {
        "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
        "size": "SMALL",
        "widthPixels": 60,
        "heightPixels": 60
      },
      {
        "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
        "size": "MEDIUM",
        "widthPixels": 110,
        "heightPixels": 110
      },
      {
        "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
        "size": "LARGE",
        "widthPixels": 256,
        "heightPixels": 256
      },
      {
        "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
        "size": "X_LARGE",
        "widthPixels": 600,
        "heightPixels": 600
      }
    ]
  }
}

MediaReference

A polymorphic object used to identify a specific media item (Item) to be used in cases where a media item must be identified in a domain-agnostic manner.

Structure

Field Description Required Type
namespace Identifies the interface of the property object. In the case of music skills, the namespace is Alexa.Audio.PlayQueue. The value of this field identifies the possible types for the name and value fields in this object. yes string
name The name of the content being consumed by the Alexa user. The possible set of values for this field are determined by the value of the namespace field. In the case of music skills, this field's value is always item. yes object
value Identifies a specific piece of content. For the Alexa.Audio.PlayQueue namespace, and item name, the value property must contain an ItemReference object. See the following example. yes object

Examples

{
  "namespace": "Alexa.Audio.PlayQueue",
  "name": "item",
  "value": {
    "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
    "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
    "contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
  }
}

MetadataNameProperty

Metadata used for voice prompt or display use cases of entity (artist, song, etc.) names.

Structure

Field Description Required Type
speech Name of the entity to be used in Alexa voice prompts. See the SpeechInfo object for details. yes object
display Name of the entity to be used in display use cases such as in the Alexa app. Currently the Alexa service ignores this field. yes string

Examples

{
  "speech": {
    "type": "PLAIN_TEXT",
    "text": "thrift shop"
  },
  "display": "Thrift Shop"
}

PlaybackInfo

An object that describes which business rules Alexa should run when playing an item. More specifically:

For advertisements, Alexa will follow these rules:

  • No skipping or seeking allowed
  • No mention of the advertisement in prompts (or display use cases) for what's playing next
  • Alexa may want to inform users (in the app's Now Playing screen) that an advertisement is currently playing
  • Some potential differences in metadata for an advertisement versus a default track

For samples, Alexa will render different prompts (mentioning that an item is a sample and not the full track), and it may potentially augment the item's metadata.

Structure

Field Description Required Type
type The type of playback info. The field can have one of the following values:

DEFAULT - describes an item that is neither a sample nor an ad
SAMPLE - describes an item whose stream is a shorter version of a full track
AD - describes an item whose stream is an advertisement
(Note: Ads aren't supported for podcasts.)		 yes string

Examples

{
  "type": "DEFAULT"
}

PlaybackMethod

When Alexa has a reference to some content as a result of GetPlayableContent, and wants to start playback for the user, it invokes the skill with the content reference so the skill can realize the content into a PlaybackMethod. So, PlaybackMethod is a realization of Content.

It is up to the skill to determine whether a queue can be reused between users or streaming sessions. For example, to support concurrency limit use cases, a queue might have to be unique for each user or streaming session. As another example, music cast from an app to an Alexa device should likely share the same queue from which the app was playing before casting. It is important to note that you can optimize play queue creation by sharing the same queue between different users without storing any information for each user or device. This is possible because in the Queue interfaces, Alexa includes the item ID, queue ID, and content reference in each request. Therefore, you don't need to store progress state for each user within a certain play queue.

Synonyms

Queue

Structure

Field Description Required Type
type The type of the playback method. The only allowed value is ALEXA_AUDIO_PLAYER_QUEUE. yes string

AudioPlayer-based (Queue)

Field Description Required Type
id The identifier for this play queue that is opaque to Alexa. If the skill wants to enforce concurrency limits, then the queue ID should be unique for each user. Note that all Music Skill API requests after a queue is created will report this queue ID back to the skill in all requests. yes string
controls List of QueueControl objects used by Alexa to determine which controls should be clickable in the Alexa app. Note that some queue-level controls might be overridden at the item-level. See the QueueControl object for more information. no list
rules Identifies rules that apply to all audio items in the play queue. Note that some queue-level rules may be overridden at the item-level. yes object
queueIdsToDeactivate If the skill enforces concurrency limits, it can either reject new Initiate requests with a DEVICE_LIMIT_REACHED error or it can create a new queue and return a list of existing queue IDs for Alexa to deactivate before initiating playback for the new queue. no list
firstItem The first item from this queue that Alexa should play for the user. See the Item object for more information. yes string

Examples

AudioPlayer response

{
  "type": "ALEXA_AUDIO_PLAYER_QUEUE",
  "id": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
  "controls": [
    {
      "type": "TOGGLE",
      "name": "SHUFFLE",
      "enabled": true,
      "selected": false
    },
    {
      "type": "TOGGLE",
      "name": "LOOP",
      "enabled": true,
      "selected": false
    }
  ],
  "rules": {
    "feedback": {
      "type": "PREFERENCE",
      "enabled": true
    }
  },
  "firstItem": {
    "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
    "playbackInfo": {
      "type": "DEFAULT"
    },
    "metadata": {
      "type": "TRACK",
      "name": {
        "speech": {
          "type": "PLAIN_TEXT",
          "text": "thrift shop"
        },
        "display": "Thrift Shop"
      },
      "art": {
        "sources": [
          {
            "url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
            "size": "X_SMALL",
            "widthPixels": 48,
            "heightPixels": 48
          },
          {
            "url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
            "size": "SMALL",
            "widthPixels": 60,
            "heightPixels": 60
          },
          {
            "url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
            "size": "MEDIUM",
            "widthPixels": 110,
            "heightPixels": 110
          },
          {
            "url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
            "size": "LARGE",
            "widthPixels": 256,
            "heightPixels": 256
          },
          {
            "url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
            "size": "X_LARGE",
            "widthPixels": 600,
            "heightPixels": 600
          }
        ]
      }
    },
    "durationInMilliseconds": 235000,
    "controls": [
      {
        "type": "COMMAND",
        "name": "NEXT",
        "enabled": true
      },
      {
        "type": "COMMAND",
        "name": "PREVIOUS",
        "enabled": false
      }
    ],
    "rules": {
      "feedbackEnabled": true
    },
    "stream": {
      "id": "STREAMID_92_14629004",
      "uri": "http://cdn.example.com/api/1/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
      "offsetInMilliseconds": 0,
      "validUntil": "2018-05-10T19:11:35Z"
    },
    "feedback": {
      "type": "PREFERENCE",
      "value": "POSITIVE"
    }
  }
}

Player (Premium audio only)

Represents an audio player on an Alexa device. This object is used to pass player properties to partners.

Synonyms

Audio Player

Structure

Field Description Required Type
playbackMethodType Specifies the PlaybackMethod type that will be used for playback. Currently, the only supported value is ALEXA_AUDIO_PLAYER_QUEUE, for queues for which Alexa internally achieves playback using the AudioPlayer interface. yes string
id A string that will only have the value "AudioPlayer". yes string
properties A Properties object represents the properties of a player application. yes object

Examples

{
  "playbackMethodType": "ALEXA_AUDIO_PLAYER_QUEUE",
  "id": "AudioPlayer",
  "properties": {
    "supportedContentFormats": [
      {
        "type": "AUDIO",
        "contentTypeId": "CT-1234"
      },
      {
        "type": "AUDIO",
        "contentTypeId": "CT-1235"
      },
      {
        "type": "AUDIO",
        "contentTypeId": "CT-1236"
      }
    ]
  }
}

PlayQueuePreview

An object that previews the metadata of the items that play in the play queue when the item is initiated.

Structure

Field Description Required Type

items

List of items in the play queue preview.

Yes

Array of objects

items[].metadata

Metadata for the item, such as type, whether the item is the latest, name, art, authors.

Yes

Object

items[].playbackInitializationContext

Context for the playback initialization.

No

Object

items[].playbackInitializationContext.type

Type of context. The acceptable value is PROVIDER_TOKEN. This token can be sent back to the provider during the playback initiation.

Yes if playbackInitializationContext is present

String

items[].playbackInitializationContext.value

Provider token value to be sent back to the provider during the playback initiation.

Yes if playbackInitializationContext is present

String

Examples

{ "payload": {
    "playQueuePreview": {
      "items": [{
          "metadata": {
              "type": "PROGRAM",
              "isLatest": true,
              "name": {
                  "speech": {
                      "type": "PLAIN_TEXT",
                      "text": "The Most Empty Downtown in America"
                  },
                  "display": "The Most Empty Downtown in America"
              },
              "art": {},
              "authors": [{}],
              "series": {},
              "releaseDate": {}
          },
          "playbackInitializationContext": {
              "type": "PROVIDER_TOKEN",
              "value": "<token value>"
          }
      }]
  }
  }
}

Properties (Premium audio only)

A properties object represents the properties of a player application.

Synonyms

Player Properties

Structure

Field Description Required Type
supportedContentFormats A list of ContentFormat objects that identify the content type identifiers (contentTypeId values) that the target device can play and which are supported by the music service provider. The content type identifiers are provided by the music service provider to Alexa as part of the skill onboarding process. no list

Examples

{
  "supportedContentFormats" : [
    {
      "type" : "AUDIO",
      "contentTypeId": "CT-1234"
    },
    {
      "type" : "AUDIO",
      "contentTypeId": "CT-1235"
    },
    {
      "type" : "AUDIO",
      "contentTypeId": "CT-1236"
    }
  ]
}

QueueControl

An object that describes a control that the user could apply to a queue or the items in the queue. Examples are shuffle and loop. Note that some queue controls can be overridden at the item level. Note that if the enablement status of a control isn't specified, Alexa assumes the control is disabled.

Structure

The base object extends BaseControl and has the following structure.

Field Description Required Type
type The object supports the following types in addition to the base types:
TOGGLE - for controls such as shuffle		 yes string
name The object supports the following names in addition to the base names:

For type TOGGLE, the value can be one of the following:
SHUFFLE - for toggling shuffle mode for the queue
LOOP - for toggling loop mode for the queue

Note the following controls are overridable at the item level: SEEK_POSITION, NEXT, PREVIOUS		 yes string

TOGGLE Type

In addition to base fields, TOGGLE type has the following fields.

Field Description Required Type
selected Indicates that a control should render in a selected state. For example, if a user has turned on loop mode in the provider's app, when the queue is casted to an Alexa device, the loop control will have a selected value of true. Defaults to false. no Boolean

Examples

{
  "type": "ADJUST",
  "name": "SEEK_POSITION",
  "enabled": true
}

{
  "type": "TOGGLE",
  "name": "LOOP",
  "enabled": true,
  "selected": true
}

QueueFeedbackRule

An object that describes whether feedback of a specific type is allowed at the queue level.

Synonyms

Queue Preference Setting, Queue Thumbs Up/Down Setting

Structure

Field Description Required Type
type The type of feedback. The only supported value is PREFERENCE. yes string
enabled Whether feedback should be enabled. If false, Alexa will render error prompts (VUI) or show error messages (GUI) when the user tries to provide feedback. Note that this flag can be overridden on an item-by-item basis. yes Boolean

Examples

{
  "type": "PREFERENCE",
  "enabled": true
}

QueueRules

Identifies rules that apply to all items in the play queue.

Synonyms

Queue Settings

Structure

Field Description Required Type
feedback Used to identify whether feedback of a specific type is allowed for a queue. If absent, Alexa assumes that no type of feedback is supported for this queue. See QueueFeedbackRule for details. Note that enablement of feedback can be overridden at the item level. no object

Examples

{
  "feedback": {
    "type": "PREFERENCE",
    "enabled": true
  }
}

RequestContext

Describes the context of an Alexa Music Skill API request. If the music service provider supports premium audio in their skill, requests for GetItem, GetNextItem, GetPreviousItem, and JumpToItem contain an Endpoint object in the RequestContext containing information about what types of audio quality streams are supported on the target device.

Synonyms

Context

Structure

Field Description Type Required

user

Contains user-specific information from the request.

User object

Yes

location

Describes a request's location.

Location object

No

endpoint

(Premium audio only) Contains player-specific information that indicates which premium audio formats the device can play. Included when the provider supports premium audio and the device is capable of playing one of the content types provided by the provider. If the provider doesn't support premium audio, this field isn't present in the request.

Endpoint object

No

advertising

Provides the customer's advertising ID and preference for receiving interest-based ads. Included in requests to skills that declare that the skill delivers advertising.

Advertising object

No

Examples

The following example shows a request context for a skill that enables advertising.

{
  "user": {
    "id": "amzn1.ask.account.1",
    "accessToken": "someToken.1"
  },
  "location": {
    "originatingLocale": "en-US",
    "countryCode": "US"
  },
  "advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": true
  }
}

The following request context shows a request when a provider supports premium audio and one of these Music Skill APIs:

{
  "user": {
    "id": "amzn1.ask.account.1",
    "accessToken": "someToken.1"
  },
  "location": {
    "originatingLocale": "en-US"
  },
  "endpoint": {
    "id": "bi39pe0g5k0pqo42phdtffk7iv8da1bx",
    "players": [
      {
        "playbackMethodType": "ALEXA_AUDIO_PLAYER_QUEUE",
        "id": "AudioPlayer",
        "properties": {
          "supportedContentFormats": [
            {
              "type": "AUDIO",
              "contentTypeId": "CT-1234"
            },
            {
              "type": "AUDIO",
              "contentTypeId": "CT-1235"
            },
            {
              "type": "AUDIO",
              "contentTypeId": "CT-1236"
            }
          ]
        }
      }
    ]
  }
}

{
  "user": {
    "id": "amzn1.ask.account.1",
    "accessToken": "someToken.1"
  },
  "location": {
    "originatingLocale": "en-US",
    "countryCode": "US"
  }
}

ResolvedSelectionCriteria

Content selection criteria in resolved form. A ResolvedSelectionCriteria object identifies attributes that can be resolved (by searching) to a Content object.

Structure

Field Description Required Type
rawSelectionCriteriaId The opaque identifier for the RawSelectionCriteria that was used to come up with the attributes for this ResolvedSelectionCriteria. When returning resolved selection criteria back to Alexa, the skill must include this field based on the raw selection criteria that it used to come up with the resolved criteria. no string
attributes A list of ResolvedSelectionCriteriaAttribute objects where each one represents one attribute of the ResolvedSelectionCriteria. Note: The relationship between ResolvedSelectionCriteriaAttributes is of type AND. yes list

Examples

{
  "rawSelectionCriteriaId": "e7f74c2c-eec7-452c-ad53-7f82509232c8",
  "attributes": [
    {
      "type": "GENRE",
      "entityId": "G1"
    },
    {
      "type": "ARTIST",
      "entityId": "A2"
    },
    {
      "type": "MEDIA_TYPE",
      "value": "TRACK"
    }
  ]
}

ResolvedSelectionCriteriaAttribute

A single attribute within a resolved content selection criteria. A ResolvedSelectionCriteriaAttribute object conveys a single aspect of a user's request in refined or processed form, such as the song name "Thrift Shop" (with skill-provided entity ID) in Alexa, play the song Thrift Shop.

For example, you can use SORT_TYPE attributes to support customer utterances such as the following:

  • POPULARITY: Alexa, play popular country music.
  • RECENCY: Alexa, play new music on Spotify.

Synonyms

Catalog Match, Entity

Base structure

Field Description Required Type
type The type of the attribute. See EntityType for all possible values. yes string

Structure for resolved attributes

Attributes for content items in a catalog, such as tracks or program series, have an entityId field.

Field Description Required Type
entityId A skill-provided identifier for the piece of content this attribute represents. This identifier gets ingested as part of one of the skill's catalogs. Note that the identifier should uniquely identify a specific piece of content in the skill's data domain. If a provider shares entity IDs across entity types, then because this ID is already scoped by the type (the other attribute in this object), the provider should still be able to uniquely identify content using this ID. Also note that Alexa will not modify the skill-provided identifier in any way before sending it to the skill as part of an API request. yes string

Structure for FOLLOW_STATUS attributes

FOLLOW_STATUS attributes have the following structure that extends the base structure:

Field Description Required Type
value (Podcast only) Must be FOLLOWED, which indicates that the user is requesting content for a program series that they have followed or subscribed to through a provider's app or website. yes string

Structure for MEDIA_TYPE attributes

MEDIA_TYPE attributes have the following structure that extends the base structure:

Field Description Required Type
value The value for the attribute, which can be one of the following:
ALBUM
MUSIC_VIDEO
PLAYLIST
PROGRAM
PROGRAM_SERIES (Podcast only)
SEASON (Podcast only)
SONG
STATION (Radio only)
TRACK		 yes string

Structure for SORT_TYPE attributes

SORT_TYPE attributes have the following structure that extends the base structure:

Field Description Required Type
value The value for the attribute. For music and radio, this must be one of the following:
POPULARITY
RECENCY
For podcasts, it must be one of the following:
PROGRAM
SEASON		 yes string

SORT_TYPE examples for music

{
    "type": "ARTIST",
    "entityId": "126564"
}

{
    "type": "MEDIA_TYPE",
    "value": "TRACK"
}

{
    "selectionCriteria": {
        "attributes": [
            {
                "type": "MEDIA_TYPE",
                "value": "TRACK"
            },
            {
                "type": "SORT_TYPE",
                "value": "POPULARITY",
                "target": null,
                "sortOrder": null
            }
        ]
    }
}

SORT_TYPE examples for podcasts

{
    "selectionCriteria": {
        "attributes": [
            {
                "type": "SORT_TYPE",
                "value": "RECENCY",
                "target": {
                  "type": "MEDIA_TYPE",
                  "value": "SEASON"
                },
                "sortOrder": "ASC"
            }
        ]
    }
}

Structure for PROGRAM_NUMBER attributes

PROGRAM_NUMBER attributes have the following structure that extends the base structure:

Field Description Required Type
value This represents the episode number requested by the customer. yes integer

Structure for RELEASE_WINDOW attributes

RELEASE_WINDOW attributes have the following structure that extends the base structure.

The value field represents the release date window of the content, which the user can include in their request to narrow their search for a particular episode of a program.

Alexa resolves the timestamp and provides a time window. The DateTime format is ISO 8601, for example, 2019-01-29TT07:00:00.000Z.

Amazon recommends that the skill searches for matching episodes using the provided window to provide customers with a consistent experience across different time zones, especially for skills with international customers.

In rare cases where the customer's preferred time zone is missing, Alexa sends the release window with start and end time represented using the local timestamp, for example, 2019-01-29TT07:00:00.000Z. Amazon recommends that the skill resolves this window using the podcast creator's location as a reference.

Field Description Required Type
value This represents the release date window of the content. yes string

Structure for SEASON_NUMBER attributes

SEASON_NUMBER attributes have the following structure that extends the base structure:

Field Description Required Type
value This represents the Season number requested by the customer. yes integer

Structure for TOPIC_NAME attributes

TOPIC_NAME describes the topic of a program series. See Implement episode search by topic. TOPIC_NAME attributes have the following structure that extends the base structure:

Field Description Required Type
value This represents the topic about which the customer is requesting. Amazon recommends that the skill searches for matching episodes with the additional topic name to provide customers with the most relevant contents. yes string

Structure for PLAY_STATUS attributes

PLAY_STATUS indicates if a customer has played or not played the content of a collection, or an item, or both.

Field Description Required Type
type Accepts one value: PLAY_STATUS. yes string
value The value for the content play status. yes object
value.collection Play status of the collection media in the request. no object
value.collection.type Type of the collection media. For example, Program_Series is a collection. For available media type, see MEDIA_TYPE. no string
value.collection.status Play status of the collection media type. It accepts two values:
PLAYED to indicate the content has played.
NOT_PLAYED to indicate the content hasn't played.		 no string
value.item Play status of an item. no string
value.item.type Type of the item. For example, PROGRAM is an item in the play list. For available media type, see MEDIA_TYPE. no string
value.item.status Play status of the item type. It accepts two values:
PLAYED to indicate the content has played.
NOT_PLAYED to indicate the content hasn't played.		 no string

Examples

{
    "type": "PLAY_STATUS",
    "value": {
        "collection": {
            "type": "PROGRAM_SERIES",
            "status": "PLAYED"
        },
        "item": {
            "type": "PROGRAM",
            "status": "NOT_PLAYED"
        }
    }
}​​​​​

SpeechInfo

Captures the details of how Alexa should render text in voice prompts to the user.

Structure

See the OutputSpeech Object for the structure of the object. Note that currently only PLAIN_TEXT is supported.

Examples

{
  "type": "PLAIN_TEXT",
  "text": "lady gaga"
}

Season (Podcast only)

Captures information about the season of a program series.

Structure

Field Description Required Type
number The ordinal number of the season. yes integer
name The name of the season. no string

StaticImagesBackground

StaticImagesBackground extends Background and contains metadata for background images that Alexa displays while music is playing. Images must be in PNG or JPG file format. For other requirements for Alexa skill content, including background images, see Policy Requirements.

Structure

Field Description Required Type
type A string describing the type of background image. Currently the only possible value is "STATIC_IMAGES". yes enum
images List of BackgroundImage objects for the background images. yes list

Examples

{
    "type": "STATIC_IMAGES",
    "images": [{
        "art": {
            "contentDescription": "",
            "sources": [{
                "url": "url",
                "size": "LARGE"
            }]
        }
    }]
}

Stream

Contains the stream URI that Alexa sends to devices as part of an AudioPlayer play directive, along with other stream-related information such as the playback offset in milliseconds, the expiration time of the URI, and an identifier for the stream.

Synonyms

URL, playback URL

Structure

Field Description Required Type
contentFormat (Premium audio only) A ContentFormat object containing the content type identifier selected by the provider from the supported content type identifiers in the request. The provider should always return a value if the request contained content formats. If the provider doesn't support premium audio, then no requests contain content formats, and the response doesn't need to contain a selected content format. yes, if the request contains a list of supported content formats object
id A unique opaque (to Alexa) identifier for the stream. Note that the same stream (with the same identifier) can be re-used across User and Queue instances. yes string
uri URI of the stream (file or audio-chunk playlist). This URI is sent to the Alexa device media player to play the content. URIs must be HTTPS. yes string
offsetInMilliseconds Offset, in milliseconds, at which to start playback of the stream. Defaults to 0. no long
endOffsetInMilliseconds Offset, in milliseconds, at which to stop playback. If endOffsetInMilliseconds is greater than the actual track length, it's ignored, and the stream plays to the end. Must be greater than or equal to offsetInMilliseconds. If endOffsetInMilliseconds is less than offsetInMilliseconds, a validation exception is raised. no long
validUntil ISO 8601 representation of when the stream URI expires. Use the ISO 8601 extended format with UTC offset, for example 2019-01-29TT07:00:00.000Z.

At the time of the skill returning a stream to Alexa, the validUntil date must be in the future, ideally at least 15 minutes, but it can be hours, days, or years in the future. This value is passed to Alexa devices in the play directive as part of the AudioResourceLocator. Defaults to roughly 60 seconds after the stream object is received from the music skill.

Note the expiration of the stream URI is defined as the latest point of time when the stream can be initiated with the given URI. Once initiated, the stream should be allowed to continue to completion without expiration.

For example, a 5-minute track has a validUntil value of 09:00 AM today. If the Alexa device begins streaming the track at 08:58 AM, the track should successfully play its entire 5 minute duration, ending at 09:03 AM.		 no string
contentTypeId (premium audio) Content format type ID corresponding to the URI. Devices use this field to understand the manifest posted at the URI (HLS, MPEG-DASH). no string
requestHeaders (DRM) List of HeaderCategory objects required for the device to play the stream. The device uses these when making different calls to the music service provider. no list

Examples

{
  "id": "STREAMID_92_14629004",
  "uri": "http://cdn.example.com/api/1/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
  "offsetInMilliseconds": 0,
  "validUntil": "2018-11-10T19:11:35Z"
}

{
    "id": "STREAMID_92_14629004",
    "uri": "https://cdn.example.com/api/1/streaming-dash-manifest.mpd",
    "offsetInMilliseconds": 0,
    "endOffsetInMilliseconds": 93125,
    "validUntil": "2018-05-10T19:11:35Z",
    "contentTypeId": "CT_EXAMPLE_DRM",
    "requestHeaders": [
         {
            "type": "KEY",
            "headers": [
                 {
                    "name": "X-AlexaMusic-ExampleMsp-LicenseToken",
                    "value": "fbfd3378-a72d-45ef-9782-4edf140f5dd7"
                 }
             ]
         },
         {
            "type": "MANIFEST",
            "headers": [
                 {
                    "name": "X-AlexaMusic-ExampleMsp-ManifestUrl",
                    "value": "https://amazonMusic.com/manifest/"
                 }
             ]
         },
         {
            "type": "AUDIOSEGMENT",
            "headers": [
                 {
                    "name": "X-AlexaMusic-ExampleMsp-AudioSegment-ASIN",
                    "value": "B07ZQ7Z83Y"
                 }
             ]
         },
         {
            "type": "ALL",
            "headers": [
                 {
                    "name": "X-AlexaMusic-ExampleMsp-RequestId",
                    "value": "0fe36d7f-6d67-4367-b5df-6a9505e5a5ef"
                 }
             ]
        }
     ]
}

User

Describes information about the user who initiated a request to the music skill.

Synonyms

Customer Information

Structure

Field Description Required Type
id Unique identifier for the user who made the request. Not all music skills will support account linking, and those skills can make use of the user identifier to distinguish API calls triggered by different Alexa users. As an example use case, for skills that do not require account linking, this identifier may be used by the skill to rate limit a specific user.

Note: This ID changes every time the user disables and re-enables the skill.		 yes string
accessToken OAuth 2.0 access token from a user's linked account. This property is null if the user has not linked an account with the skill. If this field is present, the skill should use this field to identify the user and should ignore the user identifier provided in this object. no string

Examples

{
  "id": "amzn1.ask.account.1",
  "accessToken": "someToken.1"
}

UserContentProperties

Describes information about when the user last played the content.

Field Description Required Type
lastPlayed ISO 8601 representation of when the content was last played for the user. Use the ISO 8601 extended format with UTC offset, for example, 2019-01-29TT07:00:00.000Z. The timestamp should correspond to when the content stopped playing for the user on any platform managed by the skill provider. If the content is currently playing, the skill should return the start time. Required for state persistence. When available, it serves as a RESUME marker. string

Examples

{
    "userContentProperties": {
        "lastPlayed": "2018-04-11T15:15:25Z"
    }
}

VastManifest

Describes a video ad serving template (VAST) manifest. VastManifest extends AdManifest. In addition to base fields, it has the following field.

Structure

Field Description Required Type

uri

URI pointing to the VAST document.

yes

string

Examples

{
  "type": "VAST",
  "uri": "https://example.com/ad/manifest/some-vast.xml"
}
Was this page helpful?

Last updated: Feb 09, 2024