Getty Images Getting Started: API Key & First Request (2026)

Getting started overview

Integrating with the Getty Images API enables applications to programmatically search, display, and facilitate the download of licensed visual content from Getty Images' extensive collection. This guide focuses on the initial setup process, including account creation, obtaining necessary API credentials, and executing a basic authenticated API call. The core interaction involves making HTTP requests to specific API endpoints, typically returning JSON responses containing image metadata and URLs.

The Getty Images API employs a RESTful architecture, utilizing standard HTTP methods (GET, POST) and returning data primarily in JSON format. Authentication for most API operations relies on an API key and secret, which are generated after registering a developer account. This key-based authentication ensures that only authorized applications can access the content library and associated functionalities.

To ensure a smooth onboarding experience, developers should be familiar with fundamental API concepts, including HTTP request structures, JSON parsing, and handling API responses. The process outlined below aims to provide a functional setup within a short timeframe, allowing developers to quickly explore the API's capabilities.

Quick reference table

Create an account and get keys

Accessing the Getty Images API requires a developer account and an associated API key and secret. These credentials authenticate your application's requests and link them to your account, enabling billing and usage tracking.

Account registration

1. Visit the Getty Images Developer Portal: Navigate to the official Getty Images developer documentation page.
2. Sign Up/Log In: If you already have a Getty Images account, you can typically use those credentials. Otherwise, you will need to create a new account. This process usually involves providing an email address, setting a password, and agreeing to the terms of service.

Application registration and credential generation

Once your developer account is active, you must register an application to receive your API key and secret:

1. Access Your Dashboard: After logging in, locate the section for managing your applications or API keys, often labeled 'My Apps' or 'API Credentials'.
2. Register a New Application: Click on an option to create a new application. You will typically be prompted to provide details such as:
   • Application Name: A descriptive name for your application (e.g., "My Image Search App").
   • Application Description: A brief explanation of your application's purpose.
   • Redirect URI (if applicable): For OAuth 2.0 flows, which are used for user-specific actions like downloading content, a redirect URI is required. For basic search and display, an API key/secret might suffice initially. Consult the Getty Images authentication guide for specific requirements.
3. Generate Credentials: Upon successful registration, the developer portal will display your unique API Key and API Secret. These are sensitive credentials and should be stored securely. Do not embed them directly into client-side code or public repositories. Environment variables or secure configuration management are recommended practices, as detailed in Google Cloud's API key security best practices.

Your first request

With your API Key and Secret, you can now make your first authenticated API call. This example demonstrates a basic search for images using the /search/images endpoint. We'll use a cURL command for simplicity, which is universally available and directly illustrates the HTTP request structure. For production applications, using one of the official SDKs (Python, Node.js, PHP, .NET) is generally recommended for ease of use and error handling.

Using cURL

The Getty Images API requires an access token for most authenticated requests. This token is obtained by exchanging your API Key and Secret. The process typically involves a POST request to an authentication endpoint.

Step 1: Obtain an Access Token

First, make a POST request to the token endpoint to get an access token. Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials.

curl -X POST \
  https://api.gettyimages.com/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=YOUR_API_KEY&client_secret=YOUR_API_SECRET&grant_type=client_credentials'

The response will be a JSON object containing an access_token and its expires_in duration. Extract the access_token for subsequent requests.

{
  "access_token": "YOUR_GENERATED_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Make an Image Search Request

Once you have the access_token, you can use it in the Authorization header for your search requests. Replace YOUR_GENERATED_ACCESS_TOKEN with the token obtained in Step 1.

curl -X GET \
  'https://api.gettyimages.com/v3/search/images?phrase=nature' \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Authorization: Bearer YOUR_GENERATED_ACCESS_TOKEN'

This request searches for images related to the phrase "nature". A successful response will return a JSON object containing an array of image results, each with metadata like title, URL, and asset ID. The response structure for the Getty Images API is detailed in the developer API reference.

Using the Python SDK

For a more integrated approach, the official Python SDK simplifies authentication and request construction.

Step 1: Install the SDK

pip install gettyimages-api

Step 2: Write Python Code

Create a Python file (e.g., getty_search.py) and add the following code. Remember to replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials.

import gettyimages_api

# Replace with your actual API Key and Secret
API_KEY = 'YOUR_API_KEY'
API_SECRET = 'YOUR_API_SECRET'

def main():
    try:
        # Initialize the Getty Images API client
        api_client = gettyimages_api.ApiClient(API_KEY, API_SECRET)

        # Perform an image search
        search_results = api_client.search().images().with_phrase('cityscape').execute()

        if search_results and search_results.get('images'):
            print(f"Found {len(search_results['images'])} images for 'cityscape':")
            for i, image in enumerate(search_results['images'][:5]): # Print first 5 results
                print(f"  {i+1}. Title: {image.get('title')}, ID: {image.get('id')}")
                if image.get('display_sizes') and image['display_sizes'][0].get('uri'):
                    print(f"     URL: {image['display_sizes'][0]['uri']}")
        else:
            print("No images found for 'cityscape'.")

    except gettyimages_api.exceptions.GettyImagesException as e:
        print(f"Getty Images API Error: {e.message}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == '__main__':
    main()

Execute the script: python getty_search.py. This script will print the titles and URLs of the first few images found for "cityscape".

Common next steps

After successfully making your first API call, consider these next steps to further integrate and optimize your use of the Getty Images API:

• Explore Advanced Search Parameters: The /search/images endpoint offers numerous parameters to refine your searches, such as filtering by orientation, content type (photography, illustration), license model, and more. Refer to the Getty Images API reference documentation for a complete list of available parameters and their usage.
• Implement Download Functionality: If your application requires users to download licensed content, you will need to implement the download workflow. This typically involves making a POST request to a download endpoint, which verifies the user's licensing rights and provides a secure download URL. This often requires an OAuth 2.0 flow to act on behalf of a user. The Getty Images developer guides provide specifics on this process.
• Handle Pagination: API responses for search queries are typically paginated. Implement logic to handle page and page_size parameters to fetch additional results and iterate through large datasets efficiently.
• Error Handling and Rate Limits: Implement robust error handling for various API response codes (e.g., 400 Bad Request, 401 Unauthorized, 403 Forbidden, 429 Too Many Requests). Be aware of and respect API rate limits to prevent your application from being temporarily blocked. The Getty Images API documentation outlines specific rate limits.
• Secure Your Credentials: Reiterate the importance of securing your API Key and Secret. For client-side applications, consider using a backend proxy to protect your credentials, as discussed in Twilio's guide to securing API credentials.
• Explore Other Endpoints: Beyond image search, Getty Images may offer endpoints for video search, editorial content, and managing user collections. Review the full API reference to discover other relevant functionalities for your application.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems:

• Authentication Errors (401 Unauthorized, 403 Forbidden):
  • Incorrect API Key/Secret: Double-check that you have copied your API Key and Secret accurately from the Getty Images developer portal. Typos are a frequent cause.
  • Expired Access Token: Access tokens have a limited lifespan (e.g., 3600 seconds or 1 hour). If you're reusing an old token, it might have expired. Always request a new token if you suspect it's invalid.
  • Missing Authorization Header: Ensure the Authorization: Bearer YOUR_ACCESS_TOKEN header is correctly included in your requests, and that the token itself is present and correctly formatted.
  • Incorrect API Key Header: Verify that the Api-Key: YOUR_API_KEY header is also present for requests that require it, as specified in the Getty Images authentication flow.
• Network or Connection Issues:
  • Firewall/Proxy: If you are on a corporate network, a firewall or proxy might be blocking outbound API calls. Consult your network administrator.
  • DNS Resolution: Ensure that api.gettyimages.com resolves correctly.
• Bad Request (400):
  • Missing Required Parameters: Check the API documentation for the specific endpoint you are calling to ensure all required query parameters or request body fields are included.
  • Invalid Parameter Values: Ensure that parameter values conform to the expected data types and formats (e.g., a valid phrase string, correct enum values).
  • Incorrect Content-Type: For POST requests, ensure the Content-Type header matches the format of your request body (e.g., application/json or application/x-www-form-urlencoded).
• Server Errors (5xx):
  • These indicate an issue on the Getty Images API server side. While less common, if you encounter a 5xx error, it's advisable to wait a short period and retry the request. If the issue persists, check the Getty Images developer portal for any service status updates or contact their support.
• SDK Specific Issues:
  • Installation Problems: Verify that the SDK is correctly installed and all dependencies are met.
  • Method Mismatch: Ensure you are calling the correct methods and passing parameters as expected by the SDK. Refer to the SDK's specific documentation and examples.