Amazon Music Device API
Request Headers
The following HTTP Request headers are generally supported by Device API endpoints:
| Header | Type | Description |
|---|---|---|
| Accept-Language | string | A valid language code (see section on Localization for list) |
| Authorization | string | A bearer token obtained from the Login With Amazon authorization service |
| X-Amz-Music-Site | string | A unique site identifier |
| X-Amz-Music-Images-Accept | MIME type | The requested format for images |
| X-Amz-Music-Images-Shrink | shrink-spec (see below) | The requested maximum image size |
| X-Amz-Workaround | string | Request that the API use the alternative redirect method |
| X-Amzn-Audio-DRMType | string | A comma separated list of supported DRM solutions. Ex value: widevine |
| X-Amzn-Audio-Device-Capability | string | A comma separated list of supported playback qualities. |
| X-Amzn-Audio-Preferences | string | Deprecated. HLS or AAC. |
| X-Amzn-Audio-Device-Support-Max | string | Deprecated. Sample rate/bit rate. |
| X-Amz-Device-Max-Sample-Rate | string | Deprecated. Options: LOW, MEDIUM, HIGH. |
Accept-Language
Please see the section on Language Localization for details.
Authorization
For information on obtaining a bearer authorization token, see Login With Amazon (LWA).
Ex: Authorization: Bearer Atza|...
Images
X-Amz-Music-Images-Accept allows the client to specify a format for images, for example: png. The X-Amz-Music-Images-Shrink request header allows the client to specify maximum image size in pixels. It takes the form:
X-Amz-Music-Images-Shrink: navigation-node=800x800, track=1200x1200, *=400x400
navigation-node, track, and * specify image roles, and their values specify the maximum dimensions.
This header allows a different maximum size to be specified for each image role. The valid image roles are:
- navigation-node
- item
- track-container
- track
- *
The pseudo-role * allows the client to specify a default maximum size for any image role that does not have its own maximum size specified.
With the exception of images in “My Music”, an image larger than the specified maximum size will be scaled down uniformly, preserving aspect ratio, so that its size in each dimension is less than or equal to the specified maximum size in that dimension. The service never crops or enlarges images (except for images in “My Music”).
Important Note on X-Amz-Music-Images-Shrink for "My Music"
Images in the Amazon Music library can only be square (same width & height). Additionally, there are a specific image dimensions that are available:
- 48x48
- 60x60
- 110x110
- 256x256
- 500x500
- 1000x1000
As a result, the image returned will be a size greater than or equal to the value specified in the pseudo-role "*”.
Example:
For the request
X-Amz-Music-Images-Shrink: navigation-node=800x800, track=1200x1200, *=400x400
the image returned will be 500x500.
Workaround Redirect
For client applications that are unable to handle HTTP redirects correctly, the X-Amz-Workaround request header should be submitted with a value of redirect. The Device API will then send redirects using the X-Amz-Redirect-Status and X-Amz-Redirect_Location in the response headers.
Ex: X-Amz-Workaround = REDIRECT
For more information, see the section on redirects.
DRM Type
The X-Amzn-Audio-DrmType request header specifies which DRM solution to use for streaming HD and Spatial audio. At this time, Amazon Music only supports Widevine.
Ex: X-Amzn-Audio-DrmType = WIDEVINE
Audio Quality
The X-Amzn-Audio-Device-Capability request header specifies the audio quality levels supported by your device as a comma-separated list.
These are the audio quality levels currently supported by Amazon Music:
STD_RES- Standard-quality playback using OPUS over Dash.
- Bit rates at low, medium, and high are 48, 192, and 320 kbps respectively.
HI_FI- HD-quality playback using FLAC over DASH.
- 16 bits, from 44.1 kHz.
HI_RES- Ultra HD-quality playback using FLAC over DASH.
- 24 bits, from 44.1 kHz to 192 kHz.
THREE_DIMENSIONAL- Dolby Atmos-quality using DD+.
- 16 bit.
REAL_AUDIO_360- Reality Audio 360 quality over MPEG-H.
- 16 bit.
Ex: X-Amzn-Audio-Device-Capability = STD_RES, HI_FI, HI_RES
Audio Preferences
Legacy applications may use the X-Amzn-Audio-Preferences request header to specify file format. The value can either be PROGRESSIVE/FLAC or HLS/AAC. Partners developing new applications should not use this, but instead use X-Amzn-Audio-Device-Capability.
Ex: X-Amzn-Audio-Preferences = HLS/AAC
Bitrate
Legacy applications may use the X-Amz-Device-Max-Sample-Rate and X-Amzn-Audio-Device-Support-Max request headers to specify the quality of the audio stream. X-Amz-Device-Max-Sample-Rate may have a value of LOW, MEDIUM, or HIGH. X-Amzn-Audio-Device-Support-Max specifies the sample rate / the bit rate (i.e. 24/48). Partners developing new applications should not use these.
Examples:
X-Amz-Device-Max-Sample-Rate = MEDIUM
X-Amzn-Audio-Device-Support-Max = 24/48
Now it's time to learn about Playback. Click here to continue.