Getty Images Node.js SDK

6.5.4 · active · verified Sun Apr 19

The `gettyimages-api` package provides an official Node.js SDK for interacting with the Getty Images API, simplifying common tasks such as searching for creative and editorial images, retrieving image and video metadata, and managing media downloads. It handles credential management, including access token refresh, and employs a fluent API style for constructing requests. The current stable version is 6.5.4, released recently on April 17, 2026. While there isn't a fixed release cadence, updates are regularly pushed, often addressing dependency vulnerabilities, minor bug fixes, or adding small feature enhancements. Key differentiators include its direct support and maintenance by Getty Images, streamlined authentication and token management, and a fluent API design that abstracts away raw HTTP requests and complex URL construction, making API interaction more developer-friendly compared to manual integration.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use CommonJS `require()` syntax in an ES Module context without `type: "module"` in package.json, or using it incorrectly in a file intended for ESM.

fix Ensure `"type": "module"` is set in your `package.json` and use `import api from 'gettyimages-api';`. If you must use CommonJS in a mixed environment, ensure your file extension is `.cjs`.
```
Request failed with status code 401
```
cause The provided API key or secret is invalid, expired, or lacks the necessary permissions for the requested operation.

fix Double-check your `apiKey` and `apiSecret` credentials for correctness. Ensure they are active in your Getty Images developer account and have access to the specific API services you are trying to use.
```
TypeError: client.searchimagescreative(...).withPage is not a function
```
cause The `client` object or its methods are not correctly initialized or the fluent API calls are not chained properly, often due to not `await`ing the client's API call.

fix Ensure `const client = new api(creds);` is correctly instantiated and that all subsequent chained API calls (e.g., `client.searchimagescreative().withPage().execute()`) are `await`ed before trying to access results.

Warnings

breaking Node.js runtime environment 14.20.1 or higher is required. Older versions may not be supported or could lead to unexpected behavior.
Fix: Upgrade your Node.js installation to version 14.20.1 or newer.
gotcha The SDK strongly recommends setting `"type": "module"` in your `package.json` to enable ES Modules and `async/await` syntax. Without it, you might face issues with `import` statements and proper asynchronous execution.
Fix: Add `"type": "module"` to your `package.json` file. If you are strictly using CommonJS, ensure your file extension is `.cjs` or `package.json` does NOT have `"type": "module"` and use `require` (though not recommended).
gotcha To correctly manage token lifetime and minimize API throttle quota usage, create the API client (`new api(creds)`) only once and reuse it across all API calls. Also, always `await` API calls to ensure the cached token is used.
Fix: Instantiate the client once at application startup. Always use `await` before `client.someMethod().execute();`.
breaking In version 6.4.0, editorial searches were updated to consistently use `date_from` and `date_to` parameters to match documented API names. Older, undocumented parameter names might no longer function as expected.
Fix: Review existing editorial search implementations and update any date-related parameters to `date_from` and `date_to`.
breaking A critical vulnerability (CVE-2023-45133) in a transitive dependency (`word-wrap`) was addressed in version 6.2.1. Older versions are susceptible to arbitrary code execution if untrusted content is passed to the vulnerable package.
Fix: Upgrade to `gettyimages-api` version 6.2.1 or newer immediately to mitigate the CVE.
gotcha Version 6.5.0 introduced the ability to pass in a pre-existing token, but version 6.5.1 fixed an issue with token expiration logic that might affect custom token management. If you pass tokens manually, ensure your logic aligns with 6.5.1's behavior.
Fix: If manually managing or passing tokens, ensure you are on version 6.5.1 or newer to benefit from improved token expiration handling.

Install

npm install gettyimages-api npm
yarn add gettyimages-api yarn
pnpm add gettyimages-api pnpm

Imports

api
wrong:
```
const api = require('gettyimages-api');
```
correct:
```
import api from 'gettyimages-api';
```
The SDK strongly recommends ES Modules with `type: "module"` in package.json for async/await usage. CommonJS `require` may lead to issues or require specific file extensions (`.cjs`).

Quickstart

Demonstrates initializing the Getty Images API client and performing a creative image search using environment variables for credentials.

import api from "gettyimages-api";

// Ensure you set these environment variables before running:
// process.env.GETTY_API_KEY and process.env.GETTY_API_SECRET
const creds = {
    apiKey: process.env.GETTY_API_KEY ?? '',
    apiSecret: process.env.GETTY_API_SECRET ?? ''
};

if (!creds.apiKey || !creds.apiSecret) {
    console.error("Error: API Key and Secret must be provided via environment variables.");
    process.exit(1);
}

const client = new api(creds);

async function searchImages() {
    try {
        console.log("Searching for creative images...");
        const response = await client.searchimagescreative()
            .withPage(1)
            .withPageSize(1)
            .withPhrase('ocean')
            .execute();
        console.log("Found image:", JSON.stringify(response.images, null, 2));
    } catch (err) {
        console.error("An error occurred while searching for images:", err.message);
        if (err.response && err.response.data) {
            console.error("API Error details:", JSON.stringify(err.response.data, null, 2));
        }
    }
}

searchImages();

view raw JSON →