--- title: "Retrieve similar images" method: GET path: "/v3/images/{id}/similar" tags: ["Images"] --- # Retrieve similar images `GET /v3/images/{id}/similar` ## Request - Base URL: `https://api.gettyimages.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.gettyimages.com/v3/images/{id}/similar` - Auth: one of: - API key in header `Api-Key` - OAuth 2 - Authorization code: `https://authentication.gettyimages.com/oauth2/auth` - Client credentials - Password - Token URL: `https://authentication.gettyimages.com/oauth2/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint will provide a list of images that are similar to the specified asset id. You'll need an API key and access token to use this resource. ## Working with Fields Sets Fields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available: #### Summary Fields Set The **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every image in your result set when you include **summary_set** in your request. ``` { "images": [ "asset_family", "caption", "collection_code", "collection_id", "collection_name", "display_sizes": [ { "name": "thumb" } ] "license_model", "max_dimensions", "title" ] } ``` #### Display Fields Set The **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every image in your result set when you include **display_set** in your request. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "images": [ "display_sizes": [ { "is_watermarked": , "name": "comp", "uri": "" }, { "is_watermarked": , "name": "preview", "uri": "" }, { "is_watermarked": , "name": "thumb", "uri": "" } ] ] } ``` ## Path parameters - `id` string, required ## Query parameters - `fields` GettyImagesServicesConnectPublicControllersSearchModelImagesFieldValues[] - `page` integer - `page_size` integer ## Headers - `Accept-Language` string: Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only). ## Response `200` OK - GettyImagesServicesConnectPublicModelsSearchNewModelsSearchResponse1GettyImagesServicesConnectPublicModelsSearchNewModelsEditorialImage - `result_count` integer - `images` GettyImagesServicesConnectPublicModelsSearchNewModelsEditorialImage[], nullable - `istock_collection` string, nullable - `editorial_segments` string[], nullable - `editorial_source` GettyImagesServicesConnectPublicModelsSearchEditorialSource - `id` integer - `event_ids` integer[], nullable - `era` string, nullable - `people` string[], nullable - `istock_exclusive` boolean, nullable - `allowed_use` GettyImagesServicesConnectPublicModelsAllowedUse - `how_can_i_use_it` string, nullable: Indicates how the asset can be used - `release_info` string, nullable: Indicates release status - `usage_restrictions` string[], nullable: Indicates asset usage restriction, if any - `editorial_use_only` boolean: Indicates whether the asset is for editorial use only - `alternative_ids` object, nullable - `artist` string, nullable - `asset_family` string, nullable - `asset_type` string, nullable - `call_for_image` boolean, nullable - `caption` string, nullable - `collection_code` string, nullable - `collection_id` integer, nullable - `collection_name` string, nullable - `color_type` string, nullable - `contributor` GettyImagesServicesConnectPublicModelsContributor: Contributor information for an image or video - `member_name` string, nullable: The contributor's member name - `display_name` string, nullable: The contributor's display name - `copyright` string, nullable - `date_camera_shot` string, date-time, nullable - `date_created` string, date-time, nullable - `display_sizes` GettyImagesServicesConnectPublicModelsSearchImageSearchItemDisplaySize[], nullable - `is_watermarked` boolean - `name` string, nullable - `uri` string, nullable - `download_product` string, nullable - `download_sizes` GettyImagesServicesConnectPublicModelsImagesImageDownloadSize[], nullable - `bytes` integer - `downloads` GettyImagesServicesConnectPublicModelsImagesImageDownloadAuthorization[], nullable - `product_id` string, nullable - `product_type` string, nullable - `uri` string, nullable - `agreement_name` string, nullable - `height` integer - `media_type` string, nullable - `name` 'x_small' | 'small' | 'medium' | 'large' | 'x_large' | 'xx_large' | 'vector' - `width` integer - `dpi` integer - `graphical_style` string, nullable - `id` string, nullable - `keywords` GettyImagesServicesConnectPublicModelsKeyword[], nullable - `keyword_id` string, nullable - `text` string, nullable - `type` string, nullable - `relevance` integer, nullable - `largest_downloads` GettyImagesServicesConnectPublicModelsDownload[], nullable - `product_id` string, nullable - `product_type` string, nullable - `uri` string, nullable - `agreement_name` string, nullable - `license_model` string, nullable - `max_dimensions` GettyImagesServicesConnectPublicModelsMaxDimensions - `height` integer - `width` integer - `orientation` string, nullable - `product_types` string[], nullable - `quality_rank` integer, nullable - `referral_destinations` GettyImagesServicesConnectPublicModelsReferralDestination[], nullable - `site_name` string, nullable - `uri` string, nullable - `territory_restrictions` GettyImagesServicesConnectPublicModelsTerritoryRestriction[], nullable - `country_code` string, nullable - `type` string, nullable - `description` string, nullable - `title` string, nullable - `uri_oembed` string, nullable - `date_submitted` string, date-time, nullable - `facets` GettyImagesServicesConnectPublicControllersSearchFacetsSearchFacetsResponse - `specific_people` GettyImagesServicesConnectPublicControllersSearchFacetsSpecificPeople[], nullable - `id` integer - `name` string, nullable - `events` GettyImagesServicesConnectPublicControllersSearchFacetsFacetEvent[], nullable - `id` integer - `name` string, nullable - `date` string, date-time - `locations` GettyImagesServicesConnectPublicControllersSearchFacetsLocation[], nullable - `id` integer - `name` string, nullable - `artists` GettyImagesServicesConnectPublicControllersSearchFacetsArtist[], nullable - `name` string, nullable - `entertainment` GettyImagesServicesConnectPublicControllersSearchFacetsEntertainment[], nullable - `id` integer - `name` string, nullable - `auto_corrections` GettyImagesServicesConnectPublicModelsSearchAutoCorrections - `phrase` string, nullable - `related_searches` GettyImagesServicesConnectPublicDomainServicesAssetRelatedSearch[], nullable - `phrase` string, nullable - `url` string, nullable ## Other responses - `400`: InvalidParameterValue - `401`: AuthorizationTokenRequired - `403`: UnauthorizedDisplaySize - `404`: ImageNotFound - `500`: InvalidIStockCollection ## Changes - **2026-09-04** `ddfa6c9c9f0c`: 1 breaking - removed the enum value `detail_set` from the property `items/` of the `query` request parameter `fields` - **2026-06-08** `410649649a3f`: 1 info - added the optional property `images/items/istock_exclusive` to the response with the `200` status - **2025-11-20** `81cb0e852242`: 3 breaking, 1 warning, 11 info - the response property `images/items/alternative_ids/additionalProperties/` became nullable for the status `200` - the response property `images/items/call_for_image` became nullable for the status `200` - the response property `images/items/quality_rank` became nullable for the status `200` - removed the optional property `images/items/istock_licenses` from the response with the `200` status - …11 more - **2025-05-16** `ff5eea8aa032`: 1 breaking, 2 warning - removed the enum value `entity_details` from the property `items/` of the `query` request parameter `fields` - removed the optional property `images/items/keywords/items/entity_types` from the response with the `200` status - removed the optional property `images/items/keywords/items/entity_uris` from the response with the `200` status - **2024-08-26** `00000cbae4c7`: 1 info - added the enum value `comp_webp` to the property `items/` of the `query` request parameter `fields` [Operation history](https://skmtc.dev/gettyimages/apis/getty-images-api/changes/v3/images/:id/similar/get.md) --- [API](https://skmtc.dev/gettyimages/apis/getty-images-api.md) - [All operations](https://skmtc.dev/gettyimages/apis/getty-images-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gettyimages/apis/getty-images-api/revisions/f20ce986456b?raw)