--- title: "Search for creative images based on url" method: GET path: "/v3/search/images/creative/by-image" tags: ["Search"] --- # Search for creative images based on url `GET /v3/search/images/creative/by-image` ## 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/search/images/creative/by-image` - 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) Search for **similar creative images** by passing an `image_url` to an uploaded image OR an `asset_id` of an asset in our catalog. All responses will have the `exclude_nudity` filter automatically applied. ## Searching by URL Before calling the search by image endpoint, an image in JPEG format must be uploaded to `https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}`, where the client defines the `{CLIENT_IMAGE.jpg}` portion of the URL. For example, using cURL: ``` sh curl -i -X PUT https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg -H 'Content-Type: image/jpeg' -H 'Api-Key: API_KEY' --data-binary "@testimage.jpg" ``` Once the image has been uploaded, use the full URL in the `image_url` parameter, e.g. `image_url=https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg`. - Uploaded files must be 10MB or smaller. - Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately. - Uploads expire after 24 hours. - Uploads and searches must be performed using the _same_ API Key. ## Searching by asset id When searching by `asset_id`, any image or video asset id in the Getty/iStock catalog can be used as the source for similar images. ## Query parameters - `asset_id` string - `collection_codes` string[] - `collections_filter_type` 'include' | 'exclude' - `exclude_editorial_use_only` boolean - `facet_fields` GettyImagesServicesConnectPublicControllersSearchFacetsCreateImageSearchFacetsFields[] - `facet_max_count` integer - `fields` GettyImagesServicesConnectPublicControllersSearchModelCreativeImagesFieldValues[] - `image_url` string - `include_facets` boolean - `istock_exclusive` boolean - `page` integer - `page_size` integer - `phrase` string - `product_types` string[] ## 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). - `GI-Country-Code` string: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more. ## Response `200` OK - GettyImagesServicesConnectPublicModelsSearchSearchByImageResourceResults - `image_fingerprint` string, nullable - `related_searches` GettyImagesServicesConnectPublicDomainServicesAssetRelatedSearch[], nullable - `phrase` string, nullable - `url` string, nullable - `result_count` integer - `images` GettyImagesServicesConnectPublicModelsSearchNewModelsCreativeImage[], nullable - `istock_collection` 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 ## Other responses - `400`: InvalidParameterValue - `401`: AuthorizationTokenRequired - `403`: UnauthorizedDisplaySize - `404`: AssetNotFound - `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`: 5 info - added the new optional `query` request parameter `collection_codes` - added the new optional `query` request parameter `collections_filter_type` - added the new optional `query` request parameter `istock_exclusive` - added the enum value `istock_exclusive` to the property `items/` of the `query` request parameter `fields` - …1 more - **2025-11-20** `81cb0e852242`: 1 breaking, 1 info - the response property `images/items/alternative_ids/additionalProperties/` became nullable for the status `200` - added the optional property `images/items/allowed_use/editorial_use_only` to the response with the `200` status - **2025-05-16** `ff5eea8aa032`: 1 breaking - the `images` response's property type changed from no type to `array` for status `200` - **2024-08-26** `00000cbae4c7`: 2 info - added the new optional `query` request parameter `phrase` - 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/search/images/creative/by-image/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)