Item Rendition Download

 

ON THIS PAGE      Show

 

 

 

 

Description

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

 

  Important

 

Do NOT use the rendition title to determine available content file formats and renditions and differentiate between the renditions of the same type (for example, multiple Main, Preview or Thumbnail renditions). Instead, use the duid, a descriptive tag that ties together the important rendition characteristics, if available. Otherwise, use the format and additional characteristics (for example, height, width and framerate).

 

 

 

 
{// Example: Multiple main renditions of a video content item 
"renditions": {
  "main": {
    "title": "Full Resolution (MPG 720x576)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "4fa8da5ef4204604adbad4df38ad61b9",
    "href": "https://api.ap.org/media/v/content/ebbd77b3b332ce680f4cc27d3526fca0/download?role=main&tokens",
    "sizeinbytes": 124499968,
    "width": 720,
    "height": 576,
    "originalfilename": "5218545_Olympics Usmanov_0_PALESSENCE--d61b9.mpg",
    "duration": 134360,
    "fileextension": "mpg",
    "mimetype": "video/mpeg",
    "videocodec": "MPEG",
    "framerate": 25, 
    "averagebitrate": "6144.000000",
    "samplerate": "25.0000",
    "aspectratio": "16:9",
    "duid": "vid-720i-main-50-slate",
    "pricetag": "Unlimited"
  },
  "main_480_29": {
    "title": "Full Resolution (MPG 720x480)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "bbea7f3be6ea41aaadaf068ff5c83b64",
    "href": "https://api.ap.org/media/v/content/ebbd77b3b332ce680f4cc27d3526fca0/download?role=main&tokens",
    "sizeinbytes": 124489728,
    "width": 720,
    "height": 480,
    "originalfilename": "5218545_Olympics Usmanov_0_NTSCESSENCE--83b64.mpg",
    "duration": 134360,
    "fileextension": "mpg",
    "mimetype": "video/mpeg",
    "videocodec": "MPEG",
    "framerate": 29.97,
    "averagebitrate": "6144.000000",
    "samplerate": "29.970000",
    "aspectratio": "16:9",
    "duid": "vid-720i-main-60-slate",
    "pricetag": "Unlimited"
  },
  "main_1080_25": {
    "title": "Full Resolution (MP4 1920x1080)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "18c63e0b68e8463498065e5810d64424",
    "href": "https://api.ap.org/media/v/content/ebbd77b3b332ce680f4cc27d3526fca0/download?role=main&tokens",
    "sizeinbytes": 176740298,
    "width": 1920,
    "height": 1080,
    "originalfilename": "5218545_Olympics Usmanov_0_1080i50ESSENCE--64424.mp4",
    "duration": 134360,
    "fileextension": "mp4",
    "mimetype": "video/mp4",
    "videocodec": "Microsoft MPEG-4",
    "framerate": 25,
    "averagebitrate": "10000.000000",
    "samplerate": "25.000000",
    "aspectratio": "16:9",
    "duid": "vid-1080i-main-50-slate",
    "pricetag": "Unlimited"
  },
  "main_1080_29": {
    "title": "Full Resolution (MP4 1920x1080)",
    "rel": "Main",
    "format": "MPEG",
    "type": "video",
    "contentid": "ecfae43bfec54316aabb0352293f52ba",
    "href": "https://api.ap.org/media/v/content/ebbd77b3b332ce680f4cc27d3526fca0/download?role=main&tokens",
    "sizeinbytes": 177626936,
    "width": 1920,
    "height": 1080,
    "originalfilename": "5218545_Olympics Usmanov_0_1080i60ESSENCE--f52ba.mp4",
    "duration": 134360,
    "fileextension": "mp4",
    "mimetype": "video/mp4",
    "videocodec": "Microsoft MPEG-4",
    "framerate": 29.97,
    "averagebitrate": "10000.000000",
    "samplerate": "29.970000",
    "aspectratio": "16:9",
    "duid": "vid-1080i-main-60-slate",
    "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, feed and item metadata responses.
  • Make sure to supply the API key in the x-api-key request header.
  • 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 (JSON only) The value of "true" indicates that downloading the rendition incurs a charge. If this property is not present in JSON, the rendition download does not result in a charge.
  • pricetag in JSON or signal/[@type="ap:priceTag"] in NewsML-G2. 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 in JSON or a charge in actual or virtual currency is returned in signal/[@type="ap:priceTag"]/@literal in NewsML-G2, you must append &pricetag=<pricetag_value> to the rendition download link in addition to supplying the API key in the x-api-key request header. The <pricetag_value> must be specified exactly as returned in the "pricetag" property value in JSON or in signal/[@type="ap:priceTag"]/@literal in NewsML-G2 (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 in JSON, you must append &pricetag=MeterTick:1 to the renditions.main.href download link in addition to supplying the API key in the x-api-key request header:

    {// JSON 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"}}}

    If <signal type="ap:priceTag" literal="MeterTick:1"> is returned in NewsML-G2, you must append &pricetag=MeterTick:1 to the remoteContent/[@rendition="rnd:highRes"]/@href download link in addition to supplying the API key in the x-api-key request header.

    NewsML-G2 Example: Meter ticks charge in a Metered plan
    <remoteContent residref="cd30a68d515f4c418c69f12a02cc2e6f" href="https://api.ap.org/download_link" rendition="rnd:highRes" ...>
     ...
     <signal type="ap:priceTag" literal="MeterTick:1">
    </remoteContent>

  • 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 in JSON, you must append &pricetag=USD:15.00 to the renditions.main.href download link in addition to supplying the API key in the x-api-key request header.

    {// JSON 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"}}}

    If <signal type="ap:priceTag" literal="USD:15.00"> is returned in NewsML-G2, you must append &pricetag=USD:15.00 to the remoteContent/[@rendition="rnd:highRes"]/@href download link in addition to supplying the API key in the x-api-key request header.

    NewsML-G2 Example: Extra Charge in a Choice Plan
    <remoteContent residref="6501a4803dbe44c7b8afa88ea961259e" href="https://api.ap.org/download_link" rendition="rnd:highRes" ...>
     ...
     <signal type="ap:priceTag" literal="USD:15.00">
    </remoteContent>

Downloads Not Resulting in a Charge

When the "priced": "true" property is not present on a rendition in JSON or a charge in actual or virtual currency is not returned in signal/[@type="ap:priceTag"]/@literal in NewsML-G2, downloading the rendition does not result in a charge, and you must supply only the API key in the x-api-key request header.

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 in JSON; signal/[@type="ap:priceTag"] is not present in NewsML-G2).

  • Main renditions for plans that allow unlimited downloads (the "priced" property is not present, and the "pricetag" property or signal/[@type="ap:priceTag"] indicates the type of the subscription):

    {// JSON 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"}}}

{// JSON 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"}}}

NewsML-G2 Example: Unlimited Subscription
<remoteContent residref="60988eaec87d49d29c70e9b751c714de" href="https://api.ap.org/download_link" rendition="rnd:highRes" ...>
 ...
  <signal type="ap:priceTag" literal="Unlimited">
</remoteContent>

Download Unavailable

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

{// JSON Example: Unavailable download
 "renditions": {
   "main": {
     "title": "Full Resolution (JPG)",
     "rel": "Main",
      ... 
     "mimetype": "image/jpeg",
     "pricetag": "Unavailable"}}}
NewsML-G2 Example: Unavailable download
<remoteContent residref="60988eaec87d49d29c70e9b751c714de" rendition="rnd:highRes" ...>
 ...
  <signal type="ap:priceTag" literal="Unavailable">
</remoteContent>

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": "2.0",
 "api_mode": "live",
 "api_build": "2.0.2", 
 "id": "z5KyMgQ32",
 "method": "/content/download.GET",
 "org_name": "My Organization",
 "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": "2.0",
 "api_mode": "live",
 "api_build": "2.0.2", 
 "id": "z5KyMgQ32",
 "method": "/content/download.GET",
 "org_name": "My Organization",
 "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"
 }
}