Experiment with this API

Download an Image

Use this endpoint to generate download URLs and related data for images you are authorized to download.

Most product offerings have enforced periodic download limits such as monthly, weekly, and daily. When this operation executes, the count of allowed downloads is decremented by one for the product offering. Once the download limit is reached for a given product offering, no further downloads may be requested for that product offering until the next download period.

The download limit for a given download period is covered in your product agreement established with Getty Images.

Quickstart

You'll need an API key and a Resource Owner Grant or Implicit Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

To include your API token and a Bearer token to the header (example in curl):

-H "Api-Key: <your api key>"
-H "Authorization: Bearer <your-token>"

Your request would look like this using curl:

curl -X POST -H "Api-Key: <your api key>" -H "Authorization: Bearer <your-token>" https://api.gettyimages.com/v3/downloads/images/<asset id>?auto_download=false

Auto Downloads

The auto_download request query parameter specifies whether to automatically download the image.

If the auto_download request query parameter is set to true, the API will return an HTTP status code 303 See Other. Your client code will need to process this response and redirect to the URI specified in the Location header to enable you to automatically download the file. The redirection workflow follows the HTTP 1.1 protocol.

Client Request:

https://api.gettyimages.com/v3/downloads/images/<asset_id>?auto_download=true

Server Response:

HTTP/1.1 303 See Other
Location: https://delivery.gettyimages.com/...


If the auto_download request query parameter is set to false, the API will return a HTTP status code 200, along with the URI in the response body which can be used to download the image.

Client Request:

https://api.gettyimages.com/v3/downloads/images/<asset_id>?auto_download=false

Server Response:

HTTP/1.1 200 OK
{
    "uri": "https://delivery.gettyimages.com/..."
}

Request Headers

Api-Key string Provide your API key. Required.
Authorization string Provide access token in the format of 'Bearer {token}'. Required.

URI Path Parameters

id string Id of image to download. Required.

Querystring Parameters

auto_download boolean Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a Location header set to the location of the image. If false is specified, the download URI will be returned in the response message.
file_type string File Type expressed with three character file extension. Possible values: eps jpg
height string Specifies the pixel height of the particular image to download. Available heights can be found in the images/{ids} response for the specific image. If left blank, it will return the largest available size.
product_id integer Identifier of the instance for the selected product offering type.
product_type string Product type. Possible values: easyaccess editorialsubscription imagepack premiumaccess royaltyfreesubscription creditpack

Request Body Fields

PremiumAccessDownloadData

download_notes string Associate a note with the download of an image.
project_code string Specifies the associated project code saved with the downloaded of an image.

Response Status Codes

200 OK
303 See Other
400 InvalidRequestParameterValue
400 ParameterNotSupported
400 ProductIdNotSpecified
400 ProductTypeNotSpecified
401 AuthorizationTokenRequired
401 Unauthorized
401 NoDownloadAuthorization
401 NoAgreement
401 InsufficientCredits
401 UserHasNoSubscriptions
401 OverageLimitReached
401 ProductIdNotAvailableForUser
404 ImageNotFound
404 FileDownloadSizeNotFound