開発者コンソール
アクセスいただきありがとうございます。こちらのページは現在英語のみのご用意となっております。順次日本語化を進めてまいりますので、ご理解のほどよろしくお願いいたします。

Amazon Music Web API

Playback V1.0

Web Playback

API endpoints for retrieving and updating track objects for playback. For an explanation of the basics of playback, see the playback overview.

Create New Session

POST
/v1/playback/sessions
Authorization Scope: [music::playback]

Initialize a new session and playback queue. Either playParams.id or playParams.containerIds must be provided.

Request Parameters

Name Data Type Required Description
playParams.id string Yes The ID (MRN format) of the item for playback.
playParams.containerIds string[] No An array of strings of IDs (MRN format) defining the container context of the current playback item. It can be a list of tracks or a single container such as a playlist or album.
playbackOptions.shuffleMode string No Enable or disable shuffle mode for playback. Allowed values are 'SHUFFLE_ON' and 'SHUFFLE_OFF'.
playbackOptions.loopMode string No Enable or disable shuffle mode for playback. Allowed values are 'LOOP_ON' and 'LOOP_OFF'.
playbackOptions.startAsStation bool No Start a station based on the requested track. If this parameter is set, shuffleMode will be ignored.
playbackOptions.playbackContinuationMode string No An optional parameter specifying whether to continue populating the playback queue at the end of the specified context or not. Supported values are 'AUTOPLAY_ON' and 'AUTOPLAY_OFF'.
limit number No This sets the size of the playback queue window returned to the client. Must be a number between 1 and 11 inclusive.

Example

curl --request POST '<base url>/v1/playback/sessions' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "playParams": {
        "id": "mrn:1.0:catalog:track:asin:B084KVZP2G",
        "containerIds": [
            "mrn:1.0:catalog:album:asin:B084KYMDXT"
        ]
    },
    "playbackOptions": {
        "playbackContinuationMode": "AUTOPLAY_ON",
        "shuffleMode": "SHUFFLE_OFF",
        "loopMode": "LOOP_OFF",
        "startAsStation": false
    },
    "limit": 5
}'

Response

Amazon Music response object containing:

Name Data Type Required Description
data InitialPlaybackSessionResponse Yes Playback session object including a limited window of the new playback queue.

The response body will provide a limited window of the playback queue that has been created on the Amazon Music server for this playback session. It contains up to 11 upcoming tracks in the queue.

Once the client has started playback of the first track and sent the corresponding playback event to /v1/playback/event, this track will become the current track of the queue.

Example response for an Unlimited subscriber

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": true
        },
        "entities": [
            {
                "sessionId": "1abc0c30-70b1-42ea-9f0f-20049d2b9aa3",
                "entityReferenceId": "56dc5334-c30a-4bfd-a8e8-9b92bfedefc2",
                "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"56dc5334-c30a-4bfd-a8e8-9b92bfedefc2\",\"metricsSpec\":\"TRACK\",\"playQueueId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": {
                    "next": {
                        "isAllowed": true
                    },
                    "previous": {
                        "isAllowed": true
                    },
                    "scrubForward": {
                        "isAllowed": true
                    },
                    "scrubBackward": {
                        "isAllowed": true
                    },
                    "loopOne": {
                        "isAllowed": true
                    },
                    "rate": {
                        "isAllowed": false
                    },
                    "queueMutations": {
                        "isAllowed": true
                    },
                    "queueView": {
                        "isAllowed": true
                    },
                    "loopAll": {
                        "isAllowed": true
                    },
                    "shuffle": {
                        "isAllowed": true
                    }
                },
                "track": {
                    "id": "B084KW75Z6",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KW75Z6&do=play&ref=dm_ff_amazonmusic.3p",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000347977163&ld=true&sd=true&hd=true&uhd=true&3d=true&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=026c7644-785d-44c9-ba37-8a54606b323c&rgn=NA&dtype=A3PMWP4IZPXWSV",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders":...,
                        "applicationCertificate": null,
                        "progressMilliseconds": null
                    },
                    "title": "The Adults Are Talking [Explicit]",
                    "subtitle": "The Strokes - The New Abnormal [Explicit]",
                    "isrc": "USRC11902726",
                    "images": ...,
                    "duration": 309,
                    "album": {
                        "id": "B084KP4NBH",
                        "title": "The New Abnormal [Explicit]"
                    },
                    "artists": [
                        {
                            "id": "B00G70DLAS",
                            "name": "The Strokes"
                        }
                    ]
                }
            },
            {
                "sessionId": "1abc0c30-70b1-42ea-9f0f-20049d2b9aa3",
                "entityReferenceId": "d9e552aa-1acb-42e3-b0a7-fbab15a2abf1",
                "metricId": "{\"entityId\":\"B084KPC3Q7\",\"playbackInstanceId\":\"d9e552aa-1acb-42e3-b0a7-fbab15a2abf1\",\"metricsSpec\":\"TRACK\",\"playQueueId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": ...
                },
                "track": ...
            },
            {
                "sessionId": "1abc0c30-70b1-42ea-9f0f-20049d2b9aa3",
                "entityReferenceId": "074a07d0-e5f1-428a-801f-b3bbe67d0950",
                "metricId": "{\"entityId\":\"B084KMZM11\",\"playbackInstanceId\":\"074a07d0-e5f1-428a-801f-b3bbe67d0950\",\"metricsSpec\":\"TRACK\",\"playQueueId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": ...,
                "track": ...
            }
        ],
        "metadata": {
            "loopMode": "LOOP_OFF",
            "shuffleMode": "SHUFFLE_OFF",
            "playbackState": "STOPPED"
        }
    }
}

The reponse contains metadata for the created playback queue (the current and upcoming tracks), including PlaybackMetadata (current loop and shuffle mode) and allowed customer Actions.

The Actions object attached to each playqueue entity contains valuable information that the client will need for rendering playback transport controls and a view of the queue. It specifies which transport controls (scrubbing, skipping, switching playback rate) can or must not be enabled, and if applicable, a reason for it. Depending on the subscription tier, certain controls might be deactivated because the customer has exceeded their allowed skip limit. For some cases, mostly station playback, the client might not allowed to show the queue of upcoming tracks (queueView).

In the example response above, almost all customer actions are allowed, meaning that the client should enable the corresponding transport controls (e.g. next, previous). The client is not supposed to modify the playback rate, which is typically the case for Music, as opposed to Podcast content.

Example response for a Prime subscriber

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": true
        },
        "entities": [
            {
                "sessionId": "31c0cf5c-b7a0-49eb-b1f6-40ec1f2dfcb3",
                "entityReferenceId": "03f4704e-a7bd-4128-80d5-5d8d68d719dd",
                "metricId": "{\"entityId\":\"B084KPC3Q7\",\"playbackInstanceId\":\"03f4704e-a7bd-4128-80d5-5d8d68d719dd\",\"metricsSpec\":\"TRACK\",\"selectionSourceSubType\":\"47d3c49c-1aed-4d40-9822-ea121fd64789\",\"fulfillmentSourceType\":\"AUGMENTED_SHUFFLE\",\"isCustomerSelectedEntity\":\"false\",\"selectionSourceId\":\"B084KYMDXT\",\"isAugmentedTrack\":\"false\",\"isOnDemandQueue\":\"false\",\"fulfillmentSourceId\":\"d9dd8917-996a-464d-9ad3-df72cae0c93a\",\"resourceType\":\"PRIME_MUSIC\",\"selectionSourceSessionId\":\"d9dd8917-996a-464d-9ad3-df72cae0c93a\",\"selectionSourceType\":\"ALBUM\",\"playQueueId\":\"31c0cf5c-b7a0-49eb-b1f6-40ec1f2dfcb3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": {
                    "next": {
                        "isAllowed": true,
                        "remainingSkips": 6
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    "scrubForward": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    "scrubBackward": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    "loopOne": {
                        "isAllowed": false
                    },
                    "rate": {
                        "isAllowed": true
                    },
                    "queueMutations": {
                        "isAllowed": false
                    },
                    "queueView": {
                        "isAllowed": false
                    },
                    "loopAll": {
                        "isAllowed": false
                    },
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                  ...
                }
            },
            ...
        ]
        "metadata": {
            "loopMode": "LOOP_OFF",
            "shuffleMode": "SHUFFLE_OFF",
            "playbackState": "STOPPED"
        }
    }

In this example, the client will have to disable certain transport controls, like 'previous' or 'scrubbing'. Skipping to the 'next' track is allowed, but only for another 6 skips until this customers skip limit is reached.

Subsequent calls to the event reporting and queue navigation endpoints will show a decrease in remainingSkips until eventually the action next will become disallowed.

Get Current Track

GET
/v1/playback/sessions/{sessionId}/current
Authorization Scope: [music::playback]

Retrieves a playback object for the current track.

The current track is determined by the last start event the client has sent for the track it is currently playing. Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Example

curl --request GET '<base url>/v1/playback/sessions/<your session ID>/current' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name Data Type Required Description
data PlaybackDataResponse No Playback data for the requested track.

Example

(Some lines omitted for brevity)

{
    "data": {
        "entities": [
            {
                "sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
                "entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
				...
                "actions": {
                    "next": {
                        "isAllowed": false,
                        "remainingSkips": 0,
                        "disableType": "NO_MORE_SKIPS"
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    ...
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                    "id": "B0BS2S4WXN",
                    "type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://...",
                    "playbackInformation": {
                        "url": "https://...",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders": {
                            ...
                        }
                    },
                    "title": "Flowers",
                    "subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
                    "isrc": "USSM12209777",
					...
                    ]
                }
            }
        ]
    }
}

Get Next Tracks

GET
/v1/playback/sessions/{sessionId}/next
Authorization Scope: [music::playback]
Retrieves playback objects for upcoming tracks in the queue.

Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Query Parameters

Name Data Type Required Description
limit number No This sets the number of upcoming tracks to fetch in advance. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<your session ID>/next?limit=5' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name Data Type Required Description
data PlaybackDataResponse No Playback data for the requested tracks

Example

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": true,
            "token": null
        },
        "entities": [
            {
                "sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
                "entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
				...
                "actions": {
                    "next": {
                        "isAllowed": false,
                        "remainingSkips": 0,
                        "disableType": "NO_MORE_SKIPS"
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    ...
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                    "id": "B0BS2S4WXN",
                    "type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders": {
                            "x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
                            "x-amz-music-asin": "B0BS2S4WXN",
                            "x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
                            "x-amz-music-device-type": "A3DNCSDVBULX7K",
                            "x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
                            "x-amz-music-customer-id": "ASWQDKQ3AFS23",
                            "x-amz-music-drm-type": "WIDEVINE"
                        }
                    },
                    "title": "Flowers",
                    "subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
                    "isrc": "USSM12209777",
					...
                    ]
                }
            }
        ]
    }
}

Get Previous Tracks

GET
/v1/playback/sessions/{sessionId}/previous
Authorization Scope: [music::playback]
Retrieves playback objects for the previous tracks in the queue.

Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Query Parameters

Name Data Type Required Description
limit number No This sets the size of the playback queue. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<your session ID>/previous?limit=1' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name Data Type Required Description
data PlaybackDataResponse No Playback data for the requested tracks

Example

(Some lines omitted for brevity)

{
    "data": {
        "entities": [
            {
                "sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
                "entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
				...
                "actions": {
                    "next": {
                        "isAllowed": false,
                        "remainingSkips": 0,
                        "disableType": "NO_MORE_SKIPS"
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    ...
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                    "id": "B0BS2S4WXN",
                    "type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders": {
                            "x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
                            "x-amz-music-asin": "B0BS2S4WXN",
                            "x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
                            "x-amz-music-device-type": "A3DNCSDVBULX7K",
                            "x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
                            "x-amz-music-customer-id": "ASWQDKQ3AFS23",
                            "x-amz-music-drm-type": "WIDEVINE"
                        }
                    },
                    "title": "Flowers",
                    "subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
                    "isrc": "USSM12209777",
					...
                    ]
                }
            }
        ]
    }
}

Get Playback Queue

GET
/v1/playback/sessions/{sessionId}/queue
Authorization Scope: [music::playback]

Returns playback data for the current playback queue, including the tracks available through /v1/playback/sessions/{sessionId}/current and /v1/playback/sessions/{sessionId}/next.

Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Note that for performance reasons this endpoint will only return a reduced amount of queue metadata. It does not provide the customer actions or playback information required to download the playback assets. The endpoint is intended to serve UI rendering purposes only.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Query Parameters

Name Data Type Required Description
limit number No This sets the number of tracks to fetch. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<sessionId>/queue?limit=10' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Responses

Amazon Music response object containing:

Name Data Type Required Description
data PlaybackDataResponse No Playback data for the requested tracks

Example

{
    "data": {
        "pageInfo": {
            "hasNextPage": false,
            "token": null
        },
        "entities": [
            {
                "sessionId": "388969e8-9241-4a60-a2a8-cba35a90f81",
                "entityReferenceId": "fa22ab8f-c5f7-493e-8dcb-2295decf3c0",
                "actions": {},
                "track": {
                    "id": "B08KC1C6BF",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com.rproxy.goskope.com.mx/albums/B08KBXTZ7X/?trackAsin=B08KC1C6BF&do=play&ref=abc",
                    "previewUrl": null,
                    "title": "Cornfield Chase",
                    "subtitle": "Hans Zimmer - Interstellar (Original Motion Picture Soundtrack) [Expanded Edition]",
                    "isrc": "USNLR1400774",
                    "images": [
                        {
                            "url": "https://m.media-amazon.com/images/I/A1smtRIAUvL.jpg"
                        }
                    ],
                    "duration": 127,
                    "album": {
                        "id": "B08KBXTZ7X",
                        "title": "Interstellar (Original Motion Picture Soundtrack) [Expanded Edition]"
                    },
                    "artists": [
                        {
                            "id": "B000QJK5EQ",
                            "name": "Hans Zimmer"
                        }
                    ]
                }
            },
            {
                ...
            }
        ]
    }
}

Get Active Sessions

GET
/v1/playback/sessions/active
Authorization Scope: [music::playback]
Retrieve all playback sessions across all devices.

Example

curl --request GET '<base url>/v1/playback/sessions/active' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing:

Name Data Type Required Description
data PlaybackSessionResponse No Response containing a list of active playback sessions for the current user.

Example

(Some lines omitted for brevity)

{
    "data": {
        "sessions": [
            {
                "sessionId": "8f48fc53-b52a-4b68-950b-020fe89e3b46",
                "entityReferenceId": "e9c5ad6c-ebba-4c38-966d-c5b5b66ddfa4",
                "track": {
                    "id": "B084KPC3Q7",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KPC3Q7&do=play&ref=dm_ff_amazonmusic.3p",
                    "previewUrl": "https://music.amazon.com/getSampleTrack/B084KPC3Q7?ref=dm_ff_amazonmusic.3p",
                    "title": "Selfless",
                    "subtitle": "The Strokes - The New Abnormal [Explicit]",
                    ...
                },
                "metadata": {
                    "loopMode": "LOOP_OFF",
                    "shuffleMode": "SHUFFLE_OFF",
                    "playbackState": "PLAYING"
                }
            }
        ]
    }
}

Restore Playback Session

GET
/v1/playback/sessions/{sessionId}/entities/{entityReferenceId}
Authorization Scope: [music::playback]
Used to retrieve an inactive playback session as long as it has been active within the last 30 days. Can also be used to refresh the data inside the queue of the current session.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the session to retrieve (from Playback object).
entityReferenceId string Yes The ID of the playback queue entity last played.

Query Parameters

Name Data Type Required Description
limit number No This sets the number of tracks to fetch. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<sessionId>/entities/<entityReferenceId>?limit=5' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name Data Type Required Description
data InitialPlaybackSessionResponse Yes Playback session object

Example

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": false
        },
        "entities": [
            {
                "sessionId": "8f48fc53-b52a-4b68-950b-020fe89e3b46",
                "entityReferenceId": "a6e35026-7d23-4a54-8b2c-6854d8a107ee",
                "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"a6e35026-7d23-4a54-8b2c-6854d8a107ee\",\"metricsSpec\":\"TRACK\",\"selectionSourceSessionId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"resourceType\":\"UNLIMITED_MUSIC\",\"playQueueId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": {
                    "next": {
                        "isAllowed": true
                    },
                    "previous": {
                        "isAllowed": true
                    },
                    "scrubForward": {
                        "isAllowed": true
                    },
                    "scrubBackward": {
                        "isAllowed": true
                    },
                    "loopOne": {
                        "isAllowed": true
                    },
                    "rate": {
                        "isAllowed": false
                    },
                    "queueMutations": {
                        "isAllowed": true
                    },
                    "queueView": {
                        "isAllowed": true
                    },
                    "loopAll": {
                        "isAllowed": true
                    },
                    "shuffle": {
                        "isAllowed": true
                    }
                },
                "track": {
                    "id": "B084KW75Z6",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KW75Z6&do=play&ref=dm_ff_amazonmusic.3p",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000347977163&ld=true&sd=true&hd=true&uhd=true&3d=true&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c0b137a6-d8d8-44ed-a410-00f3a559591c&rgn=NA&dtype=A3PMWP4IZPXWSV",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseUrl": null,
                        "licenseHeaders": {
                            "x-amz-music-rid": "c0b137a6-d8d8-44ed-a410-00f3a559591c",
                            "x-amz-music-asin": "B084KW75Z6",
                            "x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
                            "x-amz-music-device-type": "A3PMWP4IZPXWSV",
                            "x-amz-music-device-id": "defd7da3-bfe1-4e30-93a7-e7d6c3962c63",
                            "x-amz-music-customer-id": "A2UVA8V9BOYUMQ",
                            "x-amz-music-drm-type": "WIDEVINE"
                        },
                        "applicationCertificate": null,
                        "progressMilliseconds": null
                    },
                    "title": "The Adults Are Talking [Explicit]",
                    "subtitle": "The Strokes - The New Abnormal [Explicit]",
                    "isrc": "USRC11902726",
                    "images": [
                        {
                            "url": "https://m.media-amazon.com/images/I/91hcERG6MkL.jpg"
                        }
                    ],
                    "duration": 309,
                    "album": {
                        "id": "B084KP4NBH",
                        "title": "The New Abnormal [Explicit]"
                    },
                    "artists": [
                        {
                            "id": "B00G70DLAS",
                            "name": "The Strokes"
                        }
                    ]
                }
            },
            ...
        ],
        "metadata": {
            "loopMode": "LOOP_OFF",
            "shuffleMode": "SHUFFLE_OFF",
            "playbackState": "PLAYING"
        }
    }
}

Queue Next Track

POST
/v1/playback/sessions/{sessionId}/queue/next
Authorization Scope: [music::playback]
Insert a track into the playback queue immediately after the current track.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Request Parameters

Name Data Type Required Description
playParams.id string Yes The ID (MRN format) of the item to be added.

Example

curl --request POST '<base url>/v1/playback/sessions/<sessionId>/queue/next' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "playParams": {
        "id": "mrn:1.0:catalog:track:asin:B084KPC3Q7"
    }
}'

Responses

HTTP status 201 on success.

The client is required to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Queue Last Track

POST
/v1/playback/sessions/{sessionId}/queue/last
Authorization Scope: [music::playback]
Add a track to the end of the playback queue.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Request Parameters

Name Data Type Required Description
playParams.id string Yes The ID (MRN format) of the item to be added.

Example

curl --request POST '<base url>/v1/playback/sessions/<sessionId>/queue/last' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "playParams": {
        "id": "mrn:1.0:catalog:track:asin:B084KPC3Q7"
    }
}'

Responses

HTTP status 201 on success.

The client may need to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Set Playback Mode to Loop

PUT
/v1/playback/sessions/{sessionId}/loop
Authorization Scope: [music::playback]
Set the playback queue to loop the current track.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Request Parameters

Name Data Type Required Description
loopMode string Yes Enable or disable loop mode. Allowed values are 'LOOP_ONE', 'LOOP_ALL', and 'LOOP_OFF'

Example

curl --request PUT '<base url>/v1/playback/sessions/<sessionId>/loop' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "loopMode": "LOOP_ALL"
}'

Responses

HTTP status 200 on success.

The client is required to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Set Playback Mode to Shuffle

PUT
/v1/playback/sessions/{sessionId}/shuffle
Authorization Scope: [music::playback]
Set the playback queue to shuffle the upcoming tracks.

Path Parameters

Name Data Type Required Description
sessionId string Yes The ID of the current session (from Playback object).

Request Parameters

Name Data Type Required Description
body.shuffleMode string Yes Enable or disable shuffle mode. Allowed values are 'SHUFFLE_ON' and 'SHUFFLE_OFF'

Example

curl --request PUT '<base url>/v1/playback/sessions/<sessionId>/shuffle' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "shuffleMode": "SHUFFLE_ON"
}'

Responses

HTTP status 200 on success.

The client is required to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Report Single Event

POST
/v1/playback/event
Authorization Scope: [music::playback]

Report a single playback event to the Amazon Music service.

Body Parameters

Name Data Type Required Description
metricId string Yes The metric ID to report. Pick the identifier associated with the current playqueue entry.
event PlaybackEventStart | PlaybackEventStop Yes The event object, containing details about the reported playback event.
options.takeOverType object No Concurrency handling strategy. The parameter can be undefined or take one of the values 'AUTO' and 'FORCE'. Only applicable when sending 'start' type events.

Event fields

Name Data Type Required Description
type string Yes The type of event, which can either be start or stop.
clientTimestampInMilliseconds integer Yes The client's current time in milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC)
initialPlaybackDelayMilliseconds integer Yes Time between when a customer expects to hear music (or stop hearing music) and when playback actually starts (or stops).
deviceTimezone string Yes The device timezone, measured in offset hours. For example, -08:00 is the timezone of California.
playbackCurrentSpeed double Yes Current playback speed factor. For example, 1.0 describes regular playback, and 1.25 is 25% faster.

Only for start events

Name Data Type Required Description
playbackStartAbsoluteOffsetMilliseconds integer Yes Absolute offset in milliseconds from where the playback starts within a track. The value can range from 0 to the total duration of a track.

Only for stop events

Name Data Type Required Description
durationSeconds integer Yes Playback duration in seconds since the start of the track or since the last interruption.
entityProgressSeconds integer Yes The current absolute playback position within this track. If the track does not complete, report the farthest point in the progress bar.
rebufferCount integer Yes Number of times, playback was interrupted since the last start event due to rebuffering.
terminationReason string Yes Reason for why playback was terminated. Valid values are: userStop, userNext, userPrev, trackFinished, trackScrub, systemStop

terminationReason

  • If the user skips next or previous, the client should emit a stop event for the current track with an appropriate reason such as userNext or userPrev.
  • If the user scrubs, emit a stop event with trackScrub.
  • If the current track is paused, emit userStop.
  • If the current track finishes playing, emit trackFinished.
  • For any other reason for interruption, emit systemStop.

Example start event

curl --request POST '<base url>/v1/playback/event' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"84c44b4e-48ce-47f8-936f-7f3fd7dcb867\",\"metricsSpec\":\"TRACK\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"playQueueId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
    "event": {
        "type": "start",
        "clientTimestampInMilliseconds": 1716493161481,
        "initialPlaybackDelayMilliseconds": 571,
        "deviceTimezone": "+02:00",
        "playbackCurrentSpeed": 1.0,
        "playbackStartAbsoluteOffsetMilliseconds": 0
    },
    "options": {
        "takeOverType": "AUTO"
    }
}'

Example stop event

curl --request POST '<base url>/v1/playback/event' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"84c44b4e-48ce-47f8-936f-7f3fd7dcb867\",\"metricsSpec\":\"TRACK\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"playQueueId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
    "event": {
        "type": "stop",
        "clientTimestampInMilliseconds": 1716493236481,
        "initialPlaybackDelayMilliseconds": 0,
        "deviceTimezone": "+02:00",
        "playbackCurrentSpeed": 1.0,
        "durationSeconds": 75,
        "entityProgressSeconds": 75,
        "rebufferCount": 0,
        "terminationReason": "userStop"
    }
}'

Responses

HTTP status 201 on success.

HTTP status 422 on start type events if a concurrency error has been detected that requires user interaction for resolution.

Concurrency Error Handling

The /v1/playback/event endpoint supports 2 concurrency handling options that clients can use to resolve playback conflicts.

Without the takeOverType parameter defined, concurrency conflicts will always return a 422 error response (MAX_CONCURRENCY_REACHED) to a start event request to the client. The client can then decide how to resolve the conflict - either by displaying a prompt to take over the session, or by stopping the new playback attempt. If the client ignores the concurrency error, playback will fail after a certain number of preloaded tracks.

{
    "status": 422,
    "code": "MAX_CONCURRENCY_REACHED",
    "message": "Maximum number of concurrent listening is reached.",
    "reference": "5cb76055-be81-4cce-8b41-732c11bbc944"
}

With takeOverType: AUTO specified in the start event request body, the client delegates concurrency resolution to the backend. When a playback conflict occurs, the backend will attempt to automatically take precedence over the other device concurrently streaming and to start the new playback session on the current device. This allows for uninterrupted listening without UI disruption. In rare cases, e.g. when the other device is competing with the same take-over strategy, the event endpoint will still return a 422 error response (TAKE_OVER_DEVICE_STREAMING_ERROR) to the client.

{
    "status": 422,
    "code": "TAKE_OVER_DEVICE_STREAMING_ERROR",
    "message": "Failed to take over device streaming.",
    "reference": "f9637f25-5e13-4d68-98e7-2378af5469a7"
}

To force a takeover after seeing a concurrency error, the client can re-send the /v1/playback/event request with the takeOverType: FORCE option. This will make the backend take over the existing stream for the current device and instruct the other device to terminate playback.

In summary, takeOverType: AUTO handles concurrency resolution automatically for most cases, while takeOverType: FORCE provides a way to explicitly take over after initially seeing a concurrency error. Clients can choose one or the other to best fit their playback and UI needs.

Report Multiple Events

POST
/v1/playback/events
Authorization Scope: [music::playback]

Report multiple playback events to the Amazon Music service within a single HTTP request.

Body Parameters

Name Data Type Required Description
events[].metricId string Yes The metric ID to report. Pick the identifier associated with the playqueue entry the event relates to.
events[].event object Yes The event object, containing details about the reported playback event.
options.takeOverType object No Concurrency handling strategy. Allowed values are 'AUTO' and 'FORCE'.

Example request

curl --request POST '<base url>/v1/playback/events' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "events": [
        {
            "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"a6e35026-7d23-4a54-8b2c-6854d8a107ee\",\"metricsSpec\":\"TRACK\",\"selectionSourceSessionId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"resourceType\":\"UNLIMITED_MUSIC\",\"playQueueId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
            "event": {
                "type": "stop",
                "clientTimestampInMilliseconds": 1732718286,
                "initialPlaybackDelayMilliseconds": 0,
                "deviceTimezone": "+02:00",
                "playbackCurrentSpeed": 1.0,
                "durationSeconds": 241,
                "entityProgressSeconds": 241,
                "rebufferCount": 0,
                "terminationReason": "trackFinished"
            }
        },
        {
            "metricId": "{\"entityId\":\"B084KPC3Q7\",\"playbackInstanceId\":\"e9c5ad6c-ebba-4c38-966d-c5b5b66ddfa4\",\"metricsSpec\":\"TRACK\",\"selectionSourceSessionId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"resourceType\":\"UNLIMITED_MUSIC\",\"playQueueId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
            "event": {
                "type": "start",
                "clientTimestampInMilliseconds": 1732718347,
                "initialPlaybackDelayMilliseconds": 61,
                "deviceTimezone": "+02:00",
                "playbackCurrentSpeed": 1.0,
                "playbackStartAbsoluteOffsetMilliseconds": 0
            }
        }
    ],
    "options": {
        "takeOverType": "AUTO"
    }
}'

Responses

HTTP status 201 on success.

HTTP status 422 on concurrency errors.