GET /v3/search/videos/creative/by-image
Search for similar creative videos by passing an image_url to an uploaded image/frame grab from a video 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 or frame grab 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 videos.
Servers
- https://api.gettyimages.com
Request headers
| Name | Type | Required | Description |
|---|---|---|---|
GI-Country-Code |
String | No |
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. |
Accept-Language |
String | No |
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). |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page |
Integer | No |
Request results starting at a page number (default is 1). Default value: 1 |
include_facets |
Boolean | No |
Specifies whether or not to include facets in the result set. Default is "false". |
phrase |
String | No |
Free-text search query. |
product_types[] |
Array | No |
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. |
facet_fields[] |
Array | No |
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. |
page_size |
Integer | No |
Request number of images to return in each page. Default is 30, maximum page_size is 100. Default value: 30 |
fields[] |
Array | No |
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
exclude_editorial_use_only |
Boolean | No |
Exclude videos that are only available for editorial (non-commercial) use. Default value is false. |
image_url |
String | No |
Specifies the location of the image to use in the search. |
asset_id |
String | No |
Specifies the Getty video id to use in the search. |
facet_max_count |
Integer | No |
Specifies the maximum number of facets to return per type. Default is 300. Default value: 300 |
How to start integrating
- Add HTTP Task to your workflow definition.
- Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
- Click Test request to test run your request to the API and see the API's response.