Technical Documentation

The Getty Images API brings the best visual content straight to you and your customers, letting you integrate outstanding images, videos, and illustrations from Getty Images and iStock directly into your platform.

The Getty Images API is currently at version 3. Use the following base URI to access version 3 endpoints.

https://api.gettyimages.com/v3/

TLS

The Getty Images API requires connections to be secured via TLS. TLS versions 1.2 and 1.3 are currently supported with the following encryption ciphers:

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• ECDHE-RSA-AES128-GCM-SHA256
• ECDHE-RSA-AES128-SHA256
• ECDHE-RSA-AES256-GCM-SHA384
• ECDHE-RSA-CHACHA20-POLY1305
• ECDHE-RSA-AES256-SHA384

Authentication

The Getty Images API requires all requests to include an Api Key to authenticate the client. The API Key is sent from the client in the api-key HTTP header. Consider the following raw HTTP request:

GET /v3/countries HTTP/2
Host: api.gettyimages.com
accept: application/json

The service would respond with:

HTTP/2 401
content-type: application/json
content-length: 26

{"message":"Unauthorized"}

The request must have the api-key header in order to be successful:

GET /v3/countries HTTP/2
Host: api.gettyimages.com
accept: application/json
api-key: <API_KEY>

Authorization

The Getty Images API allows, and in some cases requires, requests to include an access token to authorize elevated client privileges. See Authorization for more detailed information on obtaining an access token.

The access token is sent via the standard Authorization HTTP header with the Bearer scheme:

GET /v3/countries HTTP/2
Host: api.gettyimages.com
accept: application/json
api-key: <API_KEY>
authorization: Bearer <ACCESS_TOKEN>

Acquire an access token using one of the Getty Images API OAuth2 grants. This example uses the OAuth2 client credentials grant:

POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

client_id=<API_KEY>&client_secret=<API_SECRET>&grant_type=client_credentials

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
        "access_token":"accesstokendata",
        "token_type":"Bearer",
        "expires_in":1800,
}

If elevated client privilege is required but missing, the API returns an authorization challenge in the response.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Download",error="invalid_token",error_description="The access token is missing"

Request Throttling

The Getty Images API throttles client requests based on limits associated with the client’s API Key. These rate limits are configured when a customer is initially setup to use the API. Contact a customer support representative to discuss changes to the rate limit.

Response message when exceeding calls per second limit:

HTTP/1.1 429 Too Many Requests
X-Error-Detail: Account Over Queries Per Second Limit

{"message": "Account Over Queries Per Second Limit"}

Schema

All API access is over HTTPS. All data is sent and received as JSON.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/search/images/creative?phrase=books"

HTTP/2 200
content-type: application/json; charset=utf-8
content-length: 29728

{"result_count": 867845, "images": [ /* snipped */ ]}

The Getty Images API returns UTC date/time values in ISO 8601 format.

YYYY-MM-DDTHH:MM:SSZ

Summary, Detail, and Custom Representations

Some fields are computationally expensive for the API to provide or require additional access privileges; and therefore, are not returned by default. Clients can specify additional fields be returned for a resource using the fields querystring parameter.

The default set of fields returned are the summary_set. Both of the following produce the same response.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800
curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=summary_set

The API provides a detail_set specifier that will include additional fields.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=detail_set

Alternately, clients can pass a comma delimited list of the specific fields they are interested in.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=id,title"

Some fields are in neither summary_set nor detail_set and must be explicitly specified.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=download_sizes"

Some fields require additional access priviledges and must be explicitly specified. In these cases clients must also provide an access token.

curl -i -H "Api-Key:<YOUR_API_KEY>" -H "Authorization: Bearer <access_token>" \
"https://api.gettyimages.com/v3/images/83454800?fields=downloads"

Download Sizes

Authorizing download of an image is computationally expensive. Therefore, clients that wish to receive details of available download sizes for images must explicitly specify that they want this information via the fields querystring parameter. The following tables show the available and allowed fields arguments for the endpoints that can return sizes and/or links to the downloadable image.

Note that clients using the download_sizes or largest_downloads arguments must also provide an access token.

Display Sizes

Display sizes can be retrieved by passing any of the following arguments in the fields parameter.

Request Headers

Some aspects of an API response can be controlled via various HTTP headers.

Accept-Language

Many Getty Images API operations will respond with localized strings if a supported language is specified. The accept-language header is used to specify the desired language. See the Interactive Documentation for the list of languages supported in the accept-language header.

GET /v3/countries HTTP/2
Host: api.gettyimages.com
accept: application/json
accept-language: zh-HK
api-key: ****

GI-Country-Code

Some operations return results tailored to the country an end-user is located in. When the API calls are not being made directly by the end-user, the service is unable to determine the end-user’s location. In those cases, an API client can override the automatic detection by sending in the gi-country-code header. Not all API customers are allowed to use this header, so contact Getty Images API support to discuss using this feature.

GET /v3/search/images/creative?phrase=football HTTP/2
Host: api.gettyimages.com
accept: application/json
gi-country-code: GBR
api-key: ****

Caching

Many operations will return cached responses. Creative Image Search, for example, will cache results for 24 hours. The API will return headers which specify how the results should be cached on the client side.

Example raw HTTP response

HTTP/2 200
content-type: application/json; charset=utf-8
content-length: 16398
content-language: en-US
cache-control: public
cache-control: must-revalidate
cache-control: max-age=86400
vary: Accept-Encoding,Authorization,Api-Key,Accept,GI-Country-Code,Accept-Language
x-cache: Hit from cloudfront
age: 120

Cache-control and vary headers instruct on how the data can be cached at the client. The max-age value also provides the maximum amount of time that the results may be cached at the API service itself.

Resources

The Getty Images API provides a RESTful API centered around resources, identified by a URI, that can be acted upon by the standard HTTP verbs. Descriptions of the Getty Images API resources are provided on our interactive documentation page.

HTTP Verbs

The Getty Images API strives to use appropriate HTTP verbs to perform actions on our resources.

Parameters

Some API endpoints take parameters specified as a segment in the path.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800"

Additional options can be specified as HTTP querystring parameters.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/search/images?phrase=books"

Some resources allow filtering on their representations using the fields querystring parameter.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=id,title"

In the last example the response will contain only the fields id and title.

HTTP Status Codes

Errors are communicated to the client via HTTP Status Codes. The following is not a comprehensive list, as there are plenty of resources describing them elsewhere.

400 - Bad Request

A 400 status code generally means the request submitted was not formatted correctly. This could be anything from invalid parameter names in a query string to asking for a page number in search results that goes beyond the number of search results found.

In most cases, a response body of type application/vnd.getty.error+json is returned, which gives more details on what was wrong with the request.

In the example below, there were 7 pages of results, but the request specified page=8:

{
  "ErrorCode": "InvalidPage",
  "ErrorMessage": "page must be less than or equal to 7, results count 698"
}

The ErrorCode property can be used in application code to determine the cause of the error. ErrorMessage is informational and should not be checked for specific wording in code.

401 - Unauthorized

Omitting, misspelling, or sending invalid Api-Key will result in a 401 Unauthorized response. This could also happen when attempting to download an image or video that is not included in the customer’s agreement.

HTTP/2 401
content-type: application/json
content-length: 26

{"message":"Unauthorized"}

404 - Not Found

A 404 status code could indicate a number of things. For example, the route requested does not exist, or when requesting metadata for a specific image id that does not exist:

< HTTP/2 404
< content-type: application/vnd.getty.error+json
< content-length: 73

{"ErrorCode":"ImageNotFound","ErrorMessage":"Image id not found: *****"}

429 - Too Many Requests

A 429 status code indicates the client has sent too many requests in a given amount of time. When an API account is created, Getty Images will assign a rate limit. Rate limits are defined by a number of queries per second (QPS). A rate limit could be defined as 5 QPS for example.

HTTP/2 429
content-type: application/json
content-length: 31

{"message":"Too Many Requests"}

The easiest way to handle 429 status responses is to use a fault-handling library such as Polly for .NET or Tenacity for Python. Libraries for other languages can be found on GitHub. Avoiding authorization calls before a token has expired will also help.

Rate limits can be adjusted by Getty Images support staff on an as-needed basis.

500 - Internal Server Error

A 500 status response indicates that something went wrong on the server. Most of the time, resending the request after a brief delay will result in a successful response. If that doesn’t work, please notify Getty Images support staff about the problem.

Hypermedia

All resources may have one or more URI properties linking to other resources. These provide explicit URIs to additional resources, saving API clients from the need to construct the URIs on their own.

Here’s an example of a search result providing a URI for downloading the image’s largest size.

{
  "images": [
    {
      "id": "3231670",
      "largest_downloads": [
        {
          "media_type": "image/jpeg",
          "bytes": 2226077,
          "downloads": [
            {
              "product_type": "premiumaccess",
              "uri": "https://api.gettyimages.com/v3/downloads/3231670"
            }
          ],
          "height": 3000,
          "width": 1607
        }
      ]
    }
  ]
}

A POST to the provided URI with a valid Api-Key and access token will download the image.

HTTP Redirects

The Getty Images API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection and be prepared to follow the redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests. The API currently uses 302 Found and 303 See Other for redirects.

Pagination

Many Getty Images API endpoints provide support for pagination of results. Pagination can be controlled by using the page and page_size querystring parameters. Default values will be used if none are provided.

• The page parameter defaults to 1.
• Search results default to a page_size of 30 items per page. Valid values are: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 25, 30, 50, 60, 75, 100.

Use the result_count property of paged result sets to calculate the number of pages available.

This example demonstrates requesting the first page, containing 20 items, of search results.

curl -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/search/images?phrase=dogs&page=1&page_size=20"

Cross Origin Resource Sharing

We support cross origin resource sharing (CORS) on all endpoints except /oauth2/token and /oauth2/auth.

Tips and Best Practices

• Do not store API keys and secrets in the source code of an application. This can lead to secrets leaking to the public via source code repositories. Use something like HashiCorp Vault to keep secrets safe.

• Use bulk operations rather than calling single operations multiple times. For example, if an application had a list of image IDs that it needed metadata for, the application should call the /v3/images endpoint with a comma-separated list of image IDs in the query string.

• Download URLs are not permalinks and should be used shortly after they are received. They are good for less than 24 hours. If there is a requirement to do massive downloads, please contact a support representative to discuss more efficient methods for getting bulk images or videos.

• Search operations do not support paging through every asset in large result sets. Search should not be used as a method for ingesting all assets a customer has access to. Contact support if there is a need to ingest all assets available via an agreement or subscription.

• SDKs are available for multiple languages. They can be helpful for managing access tokens and making HTTP calls.