Release Notes

New: Gen AI - generate new images that are influenced by a reference image

2024-08-19

We’ve added two new Generative AI endpoints for creating new images that are influenced by a reference image (a previously licensed creative image or a previously generated image).

Influence Color By Image allows the client application to provide an existing licensed (downloaded) Getty Images creative image or an existing generated image, along with prompt text and noise level, as a reference for generating new images. The generated images are influenced by the color palette, tone and location of colors within the reference image. The new endpoint is:

POST /beta/ai/image-generations/influence-color-by-image

Influence Composition By Image allows the client application to provide an existing licensed (downloaded) Getty Images creative image or an existing generated image, along with prompt text and influence level, as a reference for generating new images. The generated images are influenced by the compositional elements like pose, object location and object depth within the reference image. The new endpoint is:

POST /beta/ai/image-generations/influence-composition-by-image

Please refer to Swagger for full details.

NEW: Gen AI remove object endpoint

2024-08-13

We’ve added a new endpoint to our Generative AI product - remove object. Simliar to refine, this functionality requires that you first create and upload a mask that covers one or more objects in a previously licensed creative image or previously generated image. The new POST endpoint is then called, specifying the ID of the previously licensed or generated image along with the URL for the mask. As with other image generation operations, the output provided will be four generated images.

The new endpoint is:

POST /beta/ai/image-generations/object-removal

Please refer to Swagger for full details.

NEW: “Preview” image files are now the same as “comp” image files

2024-08-12

We’ve updated the preview field for images, available in /search and /images responses, to provide URLs that point the same file as comp. Previously, previews were a file that was variable in the pixel length of the longest dimension, as well as being highly unoptimzed for size. With this change, preview and comp are now the same file.

NEW: Enhanced search - easily search using descriptive, everyday language

2024-07-17

We’ve updated our creative image and creative video search functionality with “enhanced search”. Many of you have likely see this on gettyimages.com. Our enhanced search uses machine-learning models to understand natural, conversational language. Now you can search for longer phrases and get more relevant results from our creative image and creative video libraries. This functionality is enabled by default and will work in all languages supported by Getty Images.

Some image and video search use cases may require a precise result set vs. one expanded through enhanced search. For these scenarios, the new “enhanced_search” parameter with a value of “false” can be included in the request. Example:

https://api.gettyimages.com/v3/search/images/creative?graphical_styles=vector&phrase=Seattle%20Golden%20Gardens%20beach&enhanced_search=false

NEW: Gen AI camera controls and background removal

2024-07-11

We’ve updated our generative AI functionality to include camera control settings when generating new images from a text prompt, and added background removal functionality for previously licensed creative stock images and previously generated images. Use of this functionality is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license.

Camera controls

The POST /v3/ai/image-generations endpoint has been updated to include optional parameters that can be used to apply certain camera charactersitics to your generated images. The parameters and values are:

lens_type

  • wide_angle
  • telephoto

depth_of_field

  • shallow
  • deep

Background removal

We have added the new endpoint POST /v3/ai/image-generations/background-removal that can be used to remove the background from a previously licensed creative image or a previously generated image.

Please refer to Swagger for additional details.

SSL/TLS update

2024-05-08

The Getty Images API is updating its SSL/TLS profile, removing support for some vulnerable ciphers. Specifically, we are updating the security policy in our AWS CloudFront distribution from “TLSv1.2_2019” to the latest available, “TLSv1.2_2021”. You can find specific information on the differences here:

https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/secure-connections-supported-viewer-protocols-ciphers.html

NEW: Modify images from the Getty Images creative library

2024-04-11

We’ve updated our Generative AI products with functionality for extending and refining imagery from the Getty Images creative library. Use of these endpoints is restricted to clients with an Gen AI license product and may result in the deduction of a credit depending on the terms of your license. To download a modified image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required.

The new endpoints are:

Extend: POST /v3/ai/image-generations/extend

Refine: POST /v3/ai/image-generations/refine

See Swagger for full documentation, plus the Extend and Refine pages to learn more about this functionality.

NEW: AiGenerator endpoints are now v3

2024-02-02

We have updated most AiGenerator endpoints from beta to v3. The beta versions will continue to be supported while we work with existing clients on making the transition.

See Swagger for all technical documentation.

NEW: creative video search filters

2024-01-19

We’ve added two new creative video search filters - ethnicity and number_of_people - and added new values to the existing compositions creative video search filter.

number_of_people

This is used to filter creative video searches by the number of people in the videos. The possible values are:

  • none
  • one
  • two
  • group

ethnicity

This is used to filter creative video searches by the ethnicity of people in each video. The possible values are:

  • black
  • white
  • east asian
  • hispanic_latinx
  • japanese
  • middle_eastern
  • multiracial_person
  • multiethnic_group
  • native_american_first_nations
  • pacific_islander
  • south_asian
  • southeast_asian

compositions

We’ve added the following values to the existing compositions filter:

  • medium_shot
  • wide_shot
  • part_of_a_series

See Swagger for all technical documentation.

NEW: AI image generation with refine and extend

2024-01-08

We’ve added two new operations to our suite of image generation functionality - refine and extend. Technical documentation can be found in Swagger, and additional information has been posted for both refine and extend.

The process of refining, often called “inpainting” on other platforms, allows users to mask a region of a previously generated image and then fill in the region with new content described via a text prompt. The mask needs to be made of black and white areas, where the white defines the area to be refined, and must be uploaded to our S3 bucket.

Extend, often called “outpainting” on other platforms, enables users to expand content beyond the borders of a previously generated image using text prompts and numerical values, filling in new areas based on the context of the original image.

Use of these endpoints is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license.

NEW: moods creative image search filter

2023-10-25

We’ve added a moods creative image search filter with the following values. When used, this filter will provide images in the general color palette, or mood, of the specified value.

  • black_and_white
  • bold
  • cool
  • dramatic
  • natural
  • vivid
  • warm

Example request: https://api.gettyimages.com/v3/search/images/creative?moods=dramatic&phrase=donuts

NEW: license_model metadata response field for your previous downloads

2023-06-12

We’ve added the license_model field to the GET /v3/downloads response. This field has values of royaltyfree, rightsmanaged and rightsready, and is often used by clients as a data point for determining what action to take with each previously downloaded asset. For example, a client that is allowed to add royaltyfree videos to their DAM, but not rightsready videos, can use this information to take the appropriate action.

2023-06-06

We’ve added an event_ids filter to the GET /v3/search/video/editorial endpoint. This filter can be used to retrieve the list of videos associated with one or more editorial event IDs.

Example request:

https://api.gettyimages.com/v3/search/videos/editorial?event_ids=775825969

NEW: WebP files now available

2023-06-05

We now provide WebP versions for the comp, mid res comp and high res comp files available in /search and /image responses. The URLs for these files can be retrieved by requesting them individually or through display_set. JPG versions of these files are still provided. Please note that mid and high res comps are restricted sizes that not all clients have access to. Example requests:

https://api.gettyimages.com/v3/search/images/creative?fields=comp_webp&phrase=adventure

https://api.gettyimages.com/v3/search/images/editorial?fields=display_set&phrase=football

Update to display image URLs

2022-11-01

We have updated the format of the URLs for thumb, preview, comp, mid res comp and high res comp files to now contain a file extension. This should cause no problems for your application as all URLs should be treated as values that are subject to change at any time and should be used as-is with no modification. If your appliction is not able to use the new URLs, please check to make sure your system is not making any changes to URLs.

New endpoints for OAuth

2022-05-12

New OAuth endpoints are available which fix a bug where the expires_in property was being returned as a string instead of an integer.

New response example:

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

This change will allow more third-party OAuth frameworks to work with our API. The existing endpoints will continue to work for some time, but customers are encouraged to migrate to the new ones as soon as possible.

  • https://authentication.gettyimages.com/oauth2/token
  • https://authentication.gettyimages.com/oauth2/auth

OAuth documentation may be found here

NEW: Search By Image and Search By Video updates

2022-04-01

We have updated the procedure for using our Search By Image and Search By Video functionality. Please see our updated documentation for more information.

Search By Image: https://api.gettyimages.com/swagger/index.html#/Search/get_v3_search_images_creative_by_image

Search By Video: https://api.gettyimages.com/swagger/index.html#/Search/get_v3_search_videos_creative_by_image

NEW: video download redirects

2022-03-29

Beginning today, March 29, 2022, response codes to calls to video download URLs (https://delivery.gettyimages.com…) have changed from an HTTP 200 response to an HTTP 307 Redirect response, redirecting to a new download URL. Please contact us if this causes any issues for your application – apisupport at gettyimages dot com.

NEW: four new search languages

2021-12-10

We now support iStock creative image and video searches in Hungarian, Ukrainian, Romanian and Finnish by using one the following codes in the Accept-Language header:

  • hu
  • uk
  • ro
  • fi

NEW: dpi metadata field

2021-08-24

We’ve added dpi as a metadata field in the download_sizes response field for images in the following endpoints. This data should be helpful to partners in the print space.

  • GET ​/v3​/search​/images/creative
  • GET /v3/search/images/editorial
  • GET /v3/images
  • GET /v3/images/{id}

Example request:

https://api.gettyimages.com/v3/search/images/creative?fields=download_sizes&phrase=croissant

Snippet from the response:

{
  "result_count": 170812,
  "images": [
    {
      "id": "1289353397",
      "download_sizes": [
        {
          "bytes": 106996,
          "height": 339,
          "media_type": "image/jpeg",
          "name": "x_small",
          "width": 509,
          "dpi": 72
        },
        {
          "bytes": 14007755,
          "height": 4480,
          "media_type": "image/jpeg",
          "name": "large",
          "width": 6720,
          "dpi": 300
        },
        {
          "bytes": 1234811,
          "height": 1416,
          "media_type": "image/jpeg",
          "name": "medium",
          "width": 2125,
          "dpi": 300
        },
        {
          "bytes": 221476,
          "height": 484,
          "media_type": "image/jpeg",
          "name": "small",
          "width": 727,
          "dpi": 72
        }
      ]
    }

NEW: safe_search filter

2021-08-18

We’ve added a new creative image and creative video search filter - safe_search. When set to true, this filter will prevent assets from showing up in search results that depict death, graphic content, nudity, profanity, sexually suggestive situations and drugs & alcohol.

The filter is available on these endpoints:

  • GET ​/v3​/search​/images/creative
  • GET ​/v3​/search​/videos/creative

It’s possible that some sensitive material may make it past the filter. These will be assets that lack the necessary keywords that the filter is looking for. If you have any feedback on the results you are seeing, please contact your Getty Images Account or API Support representative.

NEW: Exclude_nudity filter for creative video searches

2021-07-12

The GET /v3/search/creative/videos endpoint has been updated with the exclude_nudity filter. When set to true, this filter will remove videos from your search results that contain frontal, explicit human nudity.

NEW: Search By Video

2021-07-09

We’ve added a new endpoint that lets you find videos that are similar to one you already have - GET /v3/search/videos/creative/by-image.

As the endpoint implies, this operation will respond with videos that are similar to an image you provide, via a URL from the image once it’s loaded to our S3 bucket. This image should be a framegrab from your video. You can also submit the asset ID if you already have a Getty or iStock video in hand. Full details are in Swagger.

NEW: video search filters and metadata - aspect ratio and orientation

2021-06-21

We’ve added two new video search filters and metadata response fields.

aspect_ratio

As a search filter, this can be used to restrict your video search results to assets that are in the specified aspect ratio. Accepted values are 16:9, 9:16, 3:4, 4:3, 4:5, 2:1, 17:9, 9:17. This is available in the following endpoints:

  • GET ​/v3​/search​/videos/creative
  • GET ​/v3​/search​/videos/editorial

orientation

As a search filter, this can be used to restrict your video search results to assets that are in the specified orientation. Accepted values are horizontal and vertical. Orientation is also available as a response field in the metadata endpoints.

  • GET ​/v3​/search​/videos/creative (search filter and response field)
  • GET ​/v3​/search​/videos/editorial (search filter and response field)
  • GET ​/v3​/videos (response field)
  • GET ​/v3​/videos​/{id} (response field)
  • GET ​/v3​/videos​/{id}​/same-series (response field)
  • GET ​/v3​/videos​/{id}​/similar (response field)

As always, you can try these out in Swagger.

NEW: four new search languages

2021-06-04

We now support creative image and video searches in Czech, Indonesian, Thai and Vietnamese by using one the following codes in the Accept-Language header:

  • cs
  • id
  • th
  • vi

NEW: video metadata fields - quality_rank, event_ids, bytes

2021-05-13 We’ve added three new metadata response fields for video assets.

quality_rank

This provides the value (0-4) that notes the quality of a video asset. For editorial videos, it indicates the relevancy of the video in relation to the event at which it was shot - 0 is highly relevant, 4 is less relevant. For creative videos, it encompasses many different aspects such as technical quality, creativity, etc. - 0 is the highest quality, 4 is the least. This field is available in the following endpoints:

  • GET ​/v3​/search​/videos/creative
  • GET ​/v3​/search​/videos/editorial
  • GET ​/v3​/videos
  • GET ​/v3​/videos​/{id}
  • GET ​/v3​/videos​/{id}​/same-series
  • GET ​/v3​/videos​/{id}​/similar

event_ids

For editorial videos, this field indicates the ID for the editorial event that the asset is associated with. This field is available in the following endpoints:

  • GET ​/v3​/search​/videos/editorial
  • GET ​/v3​/videos
  • GET ​/v3​/videos​/{id}
  • GET ​/v3​/videos​/{id}​/same-series
  • GET ​/v3​/videos​/{id}​/similar

bytes

This field indicates the size, in bytes, for each file listed in the download_sizes response field. This field is available in the following endpoints:

  • GET ​/v3​/search​/videos/creative
  • GET ​/v3​/search​/videos/editorial
  • GET ​/v3​/videos
  • GET ​/v3​/videos​/{id}
  • GET ​/v3​/videos​/{id}​/same-series
  • GET ​/v3​/videos​/{id}​/similar

NEW: “exclude_editorial_use_only” video search filter

2021-03-17 We’ve updated the GET ​/v3​/search​/videos​/creative endpoint with a new filter - “exclude_editorial_use_only”. When set to “true”, this filter will remove videos from your results that cannot be licensed or used for commercial purposes. This is helpful for excluding videos that cannot be used for things like advertising and other promotional uses; videos that can only used for editorial purposes.

Sample request:

https://api.gettyimages.com/v3/search/videos/creative?exclude_editorial_use_only=true&phrase=paris

NEW: Asset ID parameter on search by image endpoint

2021-02-18
We’ve updated the GET /v3/search/images/creative/by-image endpoint to include a request parameter for “asset_id”. When used with the ID for a creative image, the API will repond with images that are similar to the one in the request. So if you already know the ID of your image, this can save a bit of time compared to the traditional workflow of loading your jpg to our S3 bucket and then using that URL as the query parameter.

TLS minimum requirements now in place

2021-01-21
As mentioned last month, we have deprecated support for TLS 1.0 and 1.1. We now support only TLS 1.2 and newer.

Upcoming: TLS minimum requirements

2020-12-03
In order to ensure our systems are aligned with the latest security standards, the Getty Images API will be ending support for Transport Layer Security (TLS) versions 1.1 and earlier. We will only support versions 1.2 and newer. This change will go into effect on Tuesday, December 3 at approximately 9 AM PDT.

NEW: download_product search filter and metadata field

2019-09-24
Customers with multiple license agreements (product_types) often find it difficult to know which agreement will be used if they go to download an asset that has multiple product_type values. To aleviate this confusion, we’ve released a new search filter called download_product. This filter is used to narrow your search results to just the assets that can be downloaded from a specific product. Here’s an example request that might thelp to illustrate this concept…

Say you have both a Premium Access product and an Editorial Subscription product, and you want to find images that will download only against the Editorial Subscription. You would use a request like this:

https://api.gettyimages.com/v3/search/images/editorial?download_product=editorialsubscription&fields=download_product,product_types&phrase=seattle

We have included both the download_product response field, so we can confirm that we really do get only Editorial Subscription images, and the product_types response field, so you can see what we mean by an image having multiple products. While an image or video may have multiple products associated to it, it will only ever download from one product. Here’s a snippet of the response:

{
  "result_count": 166619,
  "images": [
    {
      "id": "1176628458",
      "download_product": "editorialsubscription",
      "product_types": [
        "premiumaccess",
        "editorialsubscription"
      ]
    },
    {
      "id": "1176628366",
      "download_product": "editorialsubscription",
      "product_types": [
        "premiumaccess",
        "editorialsubscription"
      ]
    },
    {
      "id": "1176628362",
      "download_product": "editorialsubscription",
      "product_types": [
        "premiumaccess",
        "editorialsubscription"
      ]
    }

This search filter and response filed are available on the following endpoints:

  • GET /v3/search/images
  • GET /v3/search/images/creative
  • GET /v3/search/images/editorial
  • GET /v3/search/videos
  • GET /v3/search/videos/creative
  • GET /v3/search/videos/editorial

NEW: Clip length video search filters

2019-07-30
We have added two new filters to all video search endpoints - min_clip_length and max_clip_length - letting you retrieve videos with a minimum and/or maximum clip length. These are available on the following endpoints:

  • GET /v3/search/videos
  • GET /v3/search/videos/creative
  • GET /v3/search/videos/editorial

You can use one or both filters in a request, specifying the desired values in seconds. In the following example that shows both filters in use, I have added the clip_length field so I can confirm that the results match my request.

https://api.gettyimages.com/v3/search/videos?fields=clip_length&min_clip_length=30&max_clip_length=60&phrase=pizza

Snipped response:

  "result_count": 978,
  "videos": [
    {
      "id": "1012522584",
      "clip_length": "00:00:55:14"
    },
    {
      "id": "933320670",
      "clip_length": "00:00:31:08"
    },
    {
      "id": "606045006",
      "clip_length": "00:00:30:16"
    }

Affiliate Partner Search API Endpoints

2019-06-11
We have two new search API endpoints that are specific to the needs of our Affiliate Partners:

  • GET /v3/affiliates/search/images
  • GET /v3/affiliates/search/videos

These endpoints are optimized for speed and ease of use, providing you with just right amount of metadata needed to add image and video search results to your site. Unlike the JavaScript widget, you’ll need to add your Affiliate ID to the destination URL per the instructions from Impact Radius, our Affiliate management partner.

You can read the full documentation in the AffiliateSearch section of our Open API Documentation (Swagger).

Interested in becoming an Affiliate Partner? Visit our Affiliate hub.

NEW: Lightweight HD video files

2019-06-04
We have a new, lightweight HD, .mp4 video file size available for all new video assets in our catlog. We are working on creating this file for all existing video assets.

To filter your search to videos that have this as an available file, simply set the format_available filter to “hd_web”. It is helpful to also include “download_sizes” in your requested fields. Like this:

https://api.gettyimages.com/v3/search/videos?format_available=hd_web&fields=download_sizes&phrase=coffee

Here’s a (snipped) response example. The new file has a format_name value of “HD Web”.

  "result_count": 30857,
  "videos": [
    {
      "id": "949190044",
      "download_sizes": [
        {
          "bit_depth": "8-bit",
          "compression": "H.264",
          "content_type": "video/quicktime",
          "description": "HD Web 1280x720 @ 25p H.264",
          "format": "HD_WEB",
          "frame_rate": 25,
          "frame_size": "1280x720",
          "height": 720,
          "interlaced": false,
          "name": "hd15",
          "width": 1280
        },
        {
          "bit_depth": "8-bit",
          "compression": "Photo-JPEG",
          "content_type": "video/quicktime",
          "description": "HD 1920x1080 @ 25p Photo-JPEG",
          "format": "HD",
          "frame_rate": 25,
          "frame_size": "1920x1080",
          "height": 1080,
          "interlaced": false,
          "name": "hd1",
          "width": 1920
        },
        {
          "bit_depth": "8-bit",
          "compression": "H.264",
          "content_type": "video/mp4",
          "description": "Web 640x360 @ 25 fps H.264",
          "format": "Web",
          "frame_rate": 25,
          "frame_size": "640x360",
          "height": 360,
          "interlaced": false,
          "name": "lwf",
          "width": 640
        },
        {
          "bit_depth": "8-bit",
          "compression": "Photo-JPEG",
          "content_type": "video/quicktime",
          "description": "4K 3840x2160 @ 25p Photo-JPEG",
          "format": "4K",
          "frame_rate": 25,
          "frame_size": "3840x2160",
          "height": 2160,
          "interlaced": false,
          "name": "4k1",
          "width": 3840
        },
        {
          "bit_depth": "8-bit",
          "compression": "H.264",
          "content_type": "video/quicktime",
          "description": "HD 1920x1080 @ 25p H.264",
          "format": "HD",
          "frame_rate": 25,
          "frame_size": "1920x1080",
          "height": 1080,
          "interlaced": false,
          "name": "hd16",
          "width": 1920
        }
      ]
    },

NEW: Relaxed rules for local hostname redirect URIs

2019-05-07
To make it easier to work with the Getty Images API, authentication workflows requiring a redirect URI (Implicit Grant or Authorization Code) now have more relaxed rules around URIs with a local hostname. First, we will no longer require HTTPS for the URI. Additionally, we won’t require local URIs to be whitelisted with us. So, for example, you’d be able to use these redirect URIs without needing to pre-register them with us:

These relaxed rules should help both during development as well for native applications whose redirect URIs do not need to leave the device (e.g. mobile apps).

Lastly, we still require HTTPS for all URIs that are not on the above list.

NEW: Metadata fields in GET /v3/downloads response

2019-05-07
We’ve added two new fields to the GET /v3/downloads response:

product_id - This field tells you the ID for the product that was used to download an asset. This field will be particulary useful for clients who have multiple Premium Access products. Each product will have it’s own unique ID.

download_source - This field tells you the name (values are gettyimages.com, istockphotos.com or api) of the site that was used to download an asset.

Both fields are available today. Try them out in Swagger!

NEW: Swagger update

2019-05-03 We’ve upgraded to the latest version of Swagger - https://api.gettyimages.com/swagger/index.html. Reminder - we use Swagger for both our API documentation and as the tool you can use to quickly test our API.

NEW: Random sort order

2018-01-02
We have implemented a “random” sort order on the following endpoints:

  • /v3/search/images
  • /v3/search/images/editorial
  • /v3/search/images/creative
  • /v3/search/videos
  • /v3/search/videos/creative
  • /v3/search/videos/editorial

This sort order is useful for when you want your users to see different images appear in the top of their search results (so they don’t all pick the same pizza photo!). While the top results will be random, they will still be relvant.

Try it out in Swagger today! https://api.gettyimages.com/swagger/ui/index#!/Search

NEW: Search Facets

2018-12-13
We have added faceting to image and video search results. Facets provide you with a way of refining your original search. The types of facets are:

Artists - this represents the artists for the images or videos in your search results. Use one of these names in the “artists” parameter, along with your original search, to refine your results to just assets from a specific artist.

Events - this facet represents the events at which images (or video) in your search results were shot. Use the id for a specific event in the event_ids parameter in an Editorial search request to find all images from that event.

Locations - this facet represents the locations for images or videos in your search results. Use the name of one of these locations in the phrase parameter, along with your original phrase value, to refine your results to images from that specific location. Alternatively, you can use the “id” data point in the keyword_ids search parameter.

Specific People - this facet represents the names of specific people in the images or videos in your search results. Use the name of one of these people in the phrase parameter, along with your original phrase value, to refine your results to images of that person. Alternatively, you can use the “id” data point in the keyword_ids search parameter.

There are three parameters used when requesting facets:

  • facet_fields is used to specify which facets are to be returned in the response.
  • include_facets must be set to “true” for facets to be returned in the response.
  • The facet_max_count parameter is used to specify the maximum number of facets to be returned for each type. If not specified, the default value of 300 will be used.

These endpoints provide you with facets for artists and locations:

  • /v3/search/images/creative
  • /v3/search/videos/creative

And these endpoints provide you with facets for artists, events, locations and specific people:

  • /v3/search/images/editorial
  • /v3/search/videos/editorial

Lastly, facets will come back translated if you use the Accept-Language header.

Try it out in Swagger today! https://api.gettyimages.com/swagger/ui/index#!/Search

NEW: Support for Authorization Code Grant

2018-12-12
We now support the Authorization Code grant flow. This flow is very similar to Implicit Grant, and provides our partners with another way to allow Getty Images and/or iStock customers to securely provide their username and password so that they can access content from their license agreement directly in the partner’s application.

OAuth Technical documentation

2018-11-27
We have added the download_sizes field as an optional field for all search requests. This provides you with the list of available files for any given image or video. Please note that including this field in your request may lead to longer than normal response times as it’s an expensive piece of data to generate. We are looking to optimize this in the future.

This field is available in the following endpoints:

  • GET /v3/search/images
  • GET /v3/search/images/creative
  • GET /v3/search/images/creative/by-image
  • GET /v3/search/images/editorial
  • GET /v3/search/videos
  • GET /v3/search/videos/creative
  • GET /v3/search/videos/editorial

Example request: https://api.gettyimages.com/v3/search/images/creative?fields=download_sizes&phrase=chocolate

Example response (snippet):

{
      "id": "951948686",
      "download_sizes": [
        {
          "bytes": 58085,
          "height": 359,
          "media_type": "image/jpeg",
          "name": "x_small",
          "width": 479
        },
        {
          "bytes": 6667900,
          "height": 3750,
          "media_type": "image/jpeg",
          "name": "large",
          "width": 5000
        },
        {
          "bytes": 675488,
          "height": 1502,
          "media_type": "image/jpeg",
          "name": "medium",
          "width": 2003
        },
        {
          "bytes": 266349,
          "height": 889,
          "media_type": "image/jpeg",
          "name": null,
          "width": 1185
        },
        {
          "bytes": 116286,
          "height": 514,
          "media_type": "image/jpeg",
          "name": "small",
          "width": 685
        },
        {
          "bytes": 2799323,
          "height": 2735,
          "media_type": "image/jpeg",
          "name": null,
          "width": 3647
        }

NEW: extended licenses for iStock downloads

2018-10-24
We have added the ability to purchase one or more extended licenses for iStock images and videos using your iStock credits. This is done through a new endpoint: /v3/asset-licensing/{assetId}. Here’s a link to the Open API technical documentation: https://api.gettyimages.com/swagger/ui/index#!/AssetLicensing/AssetLicensing_AcquireAssetLicenseWithCredits

You must first download (/v3/downloads/images/{id} or /v3/downloads/videos/{id}) before you can add an extended license.

This functionality is only available to iStock API keys. You must authenticate with a username that has access to iStock credits.

When you download a file from iStock using credits, you’re buying a standard license that lets you use the file for any personal, business or commercial purposes that aren’t otherwise restricted by the license. That means you can use our content in advertising, marketing, apps, websites, social media, TV and film, presentations, newspapers, magazines and books, and product packaging, among hundreds of other uses. Adding an extended license lets you use our content in even more ways. The extended license options are:

  • Multiseat - If multiple members of your team need to be able to access your downloaded file, this is the option for you.
  • Unlimited - allows for unlimited reproduction/print runs using the image.
  • Resale - allows use on items for resale: physical products, electronic (websites, design templates, e-greeting cards, etc.) templates.
  • Indemnification - Extended Legal Guarantee covers up to $250,000.

More information about iStock licenses can be found on our site: https://www.istockphoto.com/help/licenses

Updates to the site

2018-08-30
We have transitioned our API management provider from Mashery to AWS. This change allows us to more quickly update our APIs and takes advantage of the scale of service that comes from with working with AWS. As such, we’ve made some updates to this site, removing certain sections that were operated by Mashery.

  • Forums - we now have a Status page where we’ll post updates during service interruptions. And this Release Notes page will be kept updated with notes on all the cool new functionality we’re making availabile.
  • Sign in and Account pages - if you need to retrieve your keys/secrets, please email us at apisupport@gettyimages.com.
  • Contact - all Contact links now point to the Contact page on gettyimages.com.

We’ve also cleaned up the Docs section, removing several outdated pages. The API Documentation link now points to our Open API (Swagger) page. This is a more useful tool than the previous documentation - it provides the same info and has the added benefit of letting you actually try the API directly in the documentation.

As always, let us know if you have any questions.

NEW: istock_collection metadata field

2018-08-08
We’ve added a new metadata field called “istock_collection” to the following endpoints. This field, with values of “essentials” or “signature”, will tell you which iStock collection an iStock image is from. Customers with access to the iStock collection (collection code SKP) via their Getty API key (as opposed to an iStock API key) may find this useful as a way of further categorizing iStock images beyond their Getty collection.

  • GET /v3/search/images/creative
  • GET /v3/search/images/creative/by-image
  • GET /v3/search/videos/creative
  • GET /v3/images
  • GET /v3/images/{id}
  • GET /v3/images/{id}/similar
  • GET /v3/videos
  • GET /v3/videos/{id}
  • GET /v3/videos/{id}/similar

NEW: exclude vectors from image search results

2018-07-15
A common feature request from many partners is to be able to filter an image search so that vector art is excluded from image search results. Imagine you’re a business that prints photos for large scale wall installations. The last thing you want is for goofy little icon sets to show up in your customer’s searches.

To accomplish this, we’ve added two things: a value of “vector” to the existing graphical_styles parameter and a new parameter called graphical_styles_filter_type with values of “include” and “exclude”. Here’s how you would exclude vector art from your search request:

https://api.gettyimages.com/v3/search/images/creative?graphical_styles=vector&graphical_styles_filter_type=exclude&phrase=donuts

This functionality is available in the following endpoints:

  • GET /v3/search/images
  • GET /v3/search/images/creative
  • GET /v3/search/images/editorial

Setting the graphical_styles_filter_type to “include” is the same as not using the filter.

New functionality: download with iStock Team Credits

2018-03-30
This week, we released an update that lets iStock users download images using their iStock Team Credits.

First, the /products response now provides you with the number of team credits held by the authenticated iStock user via the “team_credits” field. Here’s an example. Note that “credits_remaining” indicates the number of personal credits held by the user.

{
  "products": [
    {
      "application_website": "iStockPhoto",
      "credits_remaining": 62,
      "download_limit": null,
      "download_limit_duration": null,
      "download_limit_reset_utc_date": null,
      "downloads_remaining": null,
      "expiration_utc_date": null,
      "id": 0,
      "name": null,
      "status": "active",
      "type": "creditpack",
      "agreement_name": null,
      "imagepack_resolution": null,
      "team_credits": 4
    }
  ]
}

Second, the /downloads/images/{id} and /downloads/videos/{id} requests now have a “use_team_credits” parameter that, when set to “true”, will use team credits to download the specified image. Setting the value to “false” or excluding the parameter entirely will download the image with the user’s personal credits. Example request:

https://api.gettyimages.com/v3/downloads/images/535761281?auto_download=false&product_type=credit_pack&use_team_credits=false

New functionality: Search By Image

2018-02-19
You may have noticed that our sites (gettyimages.com and istockphoto.com) have functionality that allows you search for images by uploading your own photo to receive results of similar content from our catalog of creative images.

Well… I have good news for all you Getty Images API fanatics! This same functionality is now available in our API! Load an image to our AWS S3 bucket, receive a URL, then use that URL as the search parameter in your request to /v3/search/images/creative-by-image.

The uses for this functionality are endless… let your users take a photo and then find similar images from the pool of creative content in your license agreement. Find a photo of some tasty donuts online, see what we have in our catalog that’s equally delicious. Tired of using the same stock photo of business people shaking hands? See what other agreeable professionals are lurking in our library! Insider tip: there’s a lot and they’re happily takin' care of Business.

Try it on Swagger

Read more

SDKs and Sample Code Status and Notifications