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 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 |
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.
To receive Alexa advertising IDs, you must indicate that your skill delivers advertising, publish a privacy policy, and submit your skill for recertification. For more details, see Steps to Add Alexa Advertising ID to Your Skill.
Structure
Property | Description | Type | Required |
---|---|---|---|
|
Customer-resettable, unique identifier that maps to the Formatted as a version 4 UUID string separated by dashes (8-4-4-4-12). |
String |
Yes |
|
Indicates whether the customer wants to receive interest-based ads. Set to |
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 seekingCOMMAND - 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 trackFor type COMMAND , the value for name can be one of the following:NEXT - for skipping to the next itemPREVIOUS - 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
orPROGRAM_SERIES
RELEASE_WINDOW
– (Podcast only) the release date windowSORT_TYPE
– describes whether audio contents or selection criteria should be ranked byPOPULARITY
orRECENCY
before being returned to AlexaFOLLOW_STATUS
– (Podcast only) indicates whether the user follows or subscribes to a program seriesTOPIC_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 |
---|---|---|---|
|
A identifier for the item that is opaque to Alexa. Note that the item should be unique within the queue. |
yes |
string |
|
Describes which business rules Alexa should run when playing or displaying this item. See the PlaybackInfo object for details. |
yes |
string |
|
Metadata for the item. |
yes |
object |
|
Duration of the item in milliseconds. If the item is a live stream, do not return this field. |
no |
long |
|
List of ItemControl objects used by Alexa to determine which controls should be clickable in the Alexa app. |
no |
list |
|
Object which contains rules for the item. See ItemRules for details. |
yes |
object |
|
yes |
object |
|
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 |
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 playlistPROGRAM
- 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 adSAMPLE - describes an item whose stream is a shorter version of a full trackAD - 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 |
---|---|---|---|
|
List of items in the play queue preview. |
Yes |
Array of objects |
|
Metadata for the item, such as type, whether the item is the latest, name, art, authors. |
Yes |
Object |
|
Context for the playback initialization. |
No |
Object |
|
Type of context. The acceptable value is |
Yes if |
String |
|
Provider token value to be sent back to the provider during the playback initiation. |
Yes if |
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 queueLOOP - for toggling loop mode for the queueNote 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 |
---|---|---|---|
|
Contains user-specific information from the request. |
|
Yes |
|
Describes a request's location. |
|
No |
|
(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. |
|
No |
|
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. |
|
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 pointing to the VAST document. |
yes |
string |
Examples
{
"type": "VAST",
"uri": "https://example.com/ad/manifest/some-vast.xml"
}
Related topics
- Understand the Music, Radio, and Podcast Skill API
- Alexa Music, Radio, and Podcast Skill API Components Reference
Last updated: Feb 09, 2024