v1
latestOpenAPI 3.0.42026-07-1376217536.1 KBSearch for creative images based on url
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:
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
Specifies the Getty image id to use in the search.
Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
Use to include or exclude collections from search. The default is include
Exclude images that are only available for editorial (non-commercial) use. Default value is false.
Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.
Specifies the maximum number of facets to return per type. Default is 300.
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
Specifies the location of the image to use in the search.
Specifies whether or not to include facets in the result set. Default is "false".
Restricts results to iStock exclusive assets when true, or non-exclusive assets when false. The default is null (no filter).
Request results starting at a page number (default is 1).
Request number of images to return in each page. Default is 30, maximum page_size is 100.
Free-text search query.
Filter images to those from one of your product types. Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
Headers
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).
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).
Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more.
Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
Response
OK