Skip to content

Item Rendition Download

Returns a specific rendition of a content item (for example, the high-resolution version of a picture). To learn more, see Content File Formats and Renditions.

Available Renditions

To determine available content file formats and renditions:

Check the format and additional characteristics (for example, height, width and framerate) for the various renditions in the search or feed response.

To differentiate between multiple renditions of the same type:

To differentiate between the names of renditions of the same type (for example, multiple Main, Preview or Thumbnail renditions), numbers representing these characteristics are appended to some of the rendition names. In the following example, height and a number representing framerate are used to name three of the four Main renditions: main, main_576_25, main_1080_25 and main_1080_29.

{// Example: Multiple main renditions of a video content item
"renditions": [
  "main": {
    "title": "Full Resolution (MPG 720x480)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "ccb7b0b1564047a8ac40fb0e7bad3b43",
    "href": "https://api.ap.org/media/v/content/6438ed7dee357c1aebec78eaf15d395a/download",
    "sizeinbytes": 115173376,
    "width": 720,
    "height": 480,
    "originalfilename": "4126272_NTSCESSENCE.mpg",
    "duration": 123680,
    "fileextension": "mpg",
    "mimetype": "video/mpeg",
    "videocodec": "MPEG",
    "framerate": 29.97,
    "averagebitrate": "6144.000000",
    "samplerate": "29.970000",
    "aspectratio": "16:9",
    "pricetag": "Unlimited"
  },
  "main_576_25": {
    "title": "Full Resolution (MPG 720x576)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "13e44de42cdd4dbe95819fb03599f201",
    "href": "https://api.ap.org/media/v/content/6438ed7dee357c1aebec78eaf15d395a/download",
    "sizeinbytes": 115185664,
    "width": 720,
    "height": 576,
    "originalfilename": "4126272_PALESSENCE.mpg",
    "duration": 123680,
    "fileextension": "mpg",
    "mimetype": "video/mpeg",
    "videocodec": "MPEG",
    "framerate": 25,
    "averagebitrate": "6144.000000",
    "samplerate": "25.000000",
    "aspectratio": "16:9",
    "pricetag": "Unlimited"
  },
  "main_1080_25": {
    "title": "Full Resolution (MP4 1920x1080)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "903e1268c16944ccbbdc8726d16f21d3",
    "href": "https://api.ap.org/media/v/content/6438ed7dee357c1aebec78eaf15d395a/download",
    "sizeinbytes": 168340977,
    "width": 1920,
    "height": 1080,
    "originalfilename": "4126272_1080i50ESSENCE.mp4",
    "duration": 123680,
    "fileextension": "mp4",
    "mimetype": "video/mp4",
    "videocodec": "Microsoft MPEG-4",
    "framerate": 25,
    "averagebitrate": "10000.000000",
    "samplerate": "25.000000",
    "aspectratio": "16:9",
    "pricetag": "Unlimited"
  },
  "main_1080_29": {
    "title": "Full Resolution (MP4 1920x1080)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "7711ae97e0d84e5abe09baa947078746",
    "href": "https://api.ap.org/media/v/content/6438ed7dee357c1aebec78eaf15d395a/download",
    "sizeinbytes": 168756699,
    "width": 1920,
    "height": 1080,
    "originalfilename": "4126272_1080i60ESSENCE.mp4",
    "duration": 123680,
    "fileextension": "mp4",
    "mimetype": "video/mp4",
    "videocodec": "Microsoft MPEG-4",
    "framerate": 29.97,
    "averagebitrate": "10000.000000",
    "samplerate": "29.970000",
    "aspectratio": "16:9",
    "pricetag": "Unlimited"
  }]}

Item rendition download links cannot be constructed by your client application because they contain tokens that specify the rendition type, format and additional details required to download each rendition.

To download item renditions:

  • Use item rendition download links available in the search and feed responses.
  • Make sure to append the apikey parameter to the download links.
  • If applicable, append the pricetag parameter to acknowledge pricing on downloads.
  • Make sure that your client application is prepared to process a 402 response to download after a price change that requires a refresh of metadata.

Acknowledging Pricing on Rendition Downloads

When a content item rendition download incurs a charge, AP Media API requires the charge acknowledgment on the download of the content item rendition. Learn more about pricing >>

The API returns the following properties on priced downloads of content item renditions (whether or not the pricing=true parameter is specified in the request):

  • priced. The value of "true" indicates that downloading the rendition incurs a charge. If this property is not present, the rendition download does not result in a charge.
  • pricetag. Describes the nature of the charge; for example, "USD:15.00" for a charge in actual currency; "MeterTick:1" for a charge in virtual currency or "Unlimited" for a download that does not result in a charge (for subscriptions with unlimited downloads).

Downloads Incurring a Charge

When "priced": "true" is returned for the rendition, you must append &pricetag=<pricetag_value> to the rendition download link in addition to the apikey parameter. The <pricetag_value> must be specified exactly as returned in the "pricetag" property value (see examples below).

Charges that require pricing acknowledgment on download include:

  • A charge in virtual currency, such as meter ticks in a metered plan. For example, if "priced": "true" and "pricetag": "MeterTick:1" are returned for the rendition, you must append &pricetag=MeterTick:1 to the renditions.main.href download link in addition to the apikey parameter:

    {// Example: Meter ticks charge in a Metered plan
     "renditions": {
       "main": {
         "title": "Full Resolution (JPG)",
         "rel": "Main",
          ... 
         "href": "https://api.ap.org/media/v/content/03c27b9d165a4cf497bdf22624d271ef/download?role=main",
          ...
         "mimetype": "image/jpeg",
         "priced": "true",
         "pricetag": "MeterTick:1"}}}
    
  • A monetary charge in actual currency in the format <CURRENCY>:<AMOUNT>. For example, if "priced": "true" and "pricetag": "USD:15.00" are returned for the rendition, you must append &pricetag=USD:15.00 to the renditions.main.href download link in addition to the apikey.

    {// Example: Extra charge in a Choice plan
     "renditions": {
       "main": {
         "title": "Full Resolution (JPG)",
         "rel": "Main",
          ... 
         "href": "https://api.ap.org/media/v/content/e4926ecee934485e9ed97f950f744b31/download?role=main",
          ...
         "mimetype": "image/jpeg",
         "priced": "true",
         "pricetag": "USD:15.00"}}}
    

Downloads Not Resulting in a Charge

When the "priced": "true" property is not present on a rendition, downloading the rendition does not result in a charge, and you must append only the apikey parameter to the content item rendition download link.

Examples of downloads not resulting in a charge include downloads of:

  • Preview and thumbnail renditions of a content item (both the "priced" and "pricetag" properties are not present).
  • Main renditions for plans that allow unlimited downloads (the "priced" property is not present, and the "pricetag" property indicates the type of the subscription):

    {// Example: Unlimited subscription 
     "renditions": {
       "main": {
         "title": "Full Resolution (JPG)",
         "rel": "Main",
          ... 
         "href": "https://api.ap.org/media/v/content/50132646dc684173a0b1fc462ff45dba/download?role=main",
          ...
         "mimetype": "image/jpeg",
         "pricetag": "Unlimited"}}}
    
    {// Example: Limited Duration subscription for content within the period included in the plan 
     "renditions": {
       "main": {
         "title": "Full Resolution (JPG)",
         "rel": "Main",
          ...
         "href": "https://api.ap.org/media/v/content/ef93b519c97c4436bdcc3bd2e5a3eace/download?role=main",
          ... 
         "mimetype": "image/jpeg",
         "pricetag": "LimitedDuration"}}}
    

Download Unavailable

If a content item rendition is not available for download, the "href" download link is not included, and the "pricetag" property indicates that the download is unavailable; for example:

{// Example: Unavailable download
 "renditions": {
   "main": {
     "title": "Full Resolution (JPG)",
     "rel": "Main",
      ... 
     "mimetype": "image/jpeg",
     "pricetag": "Unavailable"}}}

Response

Download Allowed

Returns the standard HTTP status code of "302 - Found" and redirects to the URL for the content item binary. Make sure your client application is prepared to follow HTTP Redirect responses from the API.

For information about error codes, see API Codes.

Response Headers

  • x-mediaapi-Q-name. The API method to which the throttle/quota applies (corresponds to the "method" property returned by Account Quotas. Possible values are search, feed, account, download, ondemand, item, other.

  • x-mediaapi-Q-secondsLeft. The number of seconds remaining in the current period.

  • x-mediaapi-Q-used. Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 1/6.

  • x-mediaapi-QDay-minutesLeft. (Optional; returned if a per-day quota is configured) The number of minutes remaining in the current period.

  • x-mediaapi-QDay-used. (Optional; returned if a per-day quota is configured) Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 2/5000000.

Download After a Price Change

If you have stored a download link in your system after requesting it from the API, the price might no longer be the same when you follow that link some time later. For example, you might have reached your monthly plan limit since receiving the initial download links from the API and would now have to pay an extra charge for the image.

If the price has changed, the API returns the code of 402 "Price has changed, check updated pricing information" and a link to the updated content item.

Sample Response

{
 "api_version": "1.0",
 "api_mode": "live",
 "id": "z5KyMgQ32",
 "method": "/content/download.GET",
 "params": {
   "pricing": true
 },
 "error": {
   "status": 402,  // HTTP status code
   "code": 9403,    // AP error code
   "message": "Price has changed, check updated pricing information",
   "item": "https://api.ap.org/media/v/content/b220a09f1b5a4fb1975fcec2f7425e2b?pricing=true"
 }
}

Item Not Available in Plan

If a content item is not included in your plan and is not available for an extra charge, the API does not include download links in search, feed and item metadata responses.

However, in some cases, you might encounter a response indicating that the download is no longer allowed; for example, if you have stored a download link in your system after requesting it from the API, have reached your monthly download limit, and your plan does not allow further downloads.

If a download is no longer allowed, the API returns the code of 403 "Item is unavailable in your plan at this time" error.

Sample Response

{
 "api_version": "1.0",
 "api_mode": "live",
 "id": "z5KyMgQ32",
 "method": "/content/download.GET",
 "params": {},
 "error": {
   "status": 403,  // HTTP status code
   "code": 9402,   // AP error code
   "message": "Item is unavailable in your plan at this time",
   "item": "https://api.ap.org/media/v/content/b220a09f1b5a4fb1975fcec2f7425e2b"
 }
}