Sign In
Sign In

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.