---
title: "Search for creative videos based on url"
method: GET
path: "/v3/search/videos/creative/by-image"
tags: ["Search"]
---

# Search for creative videos based on url

`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:

``` 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 videos.

## Query parameters

- `asset_id` string
- `collection_codes` string[]
- `collections_filter_type` 'include' | 'exclude'
- `exclude_editorial_use_only` boolean
- `facet_fields` GettyImagesServicesConnectPublicControllersSearchFacetsCreateVideoSearchFacetsFields[]
- `facet_max_count` integer
- `fields` GettyImagesServicesConnectPublicControllersSearchModelCreativeVideosFieldValues[]
- `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

- GettyImagesServicesConnectPublicModelsSearchSearchByImageResourceVideoResults
  - `related_searches` GettyImagesServicesConnectPublicDomainServicesAssetRelatedSearch[], nullable
    - `phrase` string, nullable
    - `url` string, nullable
  - `videos` GettyImagesServicesConnectPublicModelsSearchNewModelsVideoVideo[], nullable
    - `id` string, 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
    - `aspect_ratio` string, nullable
    - `asset_family` string, nullable
    - `asset_type` string, nullable
    - `call_for_image` boolean, nullable
    - `caption` string, nullable
    - `clip_length` string, nullable
    - `collection_id` integer, nullable
    - `collection_code` string, nullable
    - `collection_name` string, nullable
    - `color_type` string, nullable
    - `copyright` string, nullable
    - `date_camera_shot` string, date-time, nullable
    - `date_created` string, date-time, nullable
    - `date_submitted` string, date-time, nullable
    - `display_sizes` GettyImagesServicesConnectPublicModelsSearchVideoSearchItemDisplaySize[], nullable
      - `is_watermarked` boolean
      - `name` string, nullable
      - `uri` string, nullable
      - `aspect_ratio` string, nullable
    - `download_product` string, nullable
    - `download_sizes` GettyImagesServicesConnectPublicModelsVideosVideoDownloadSize[], nullable
      - `bit_depth` string, nullable
      - `broadcast_video_standard` string, nullable
      - `compression` string, nullable
      - `content_type` string, nullable
      - `description` string, nullable
      - `downloads` GettyImagesServicesConnectPublicModelsVideosVideoDownloadAuthorization[], nullable
        - `product_id` string, nullable
        - `product_type` string, nullable
        - `uri` string, nullable
        - `agreement_name` string, nullable
      - `format` string, nullable
      - `frame_rate` number, double, nullable
      - `frame_size` string, nullable
      - `height` number, double, nullable
      - `interlaced` boolean
      - `bytes` integer
      - `name` string, nullable
      - `width` integer
    - `istock_collection` string, nullable
    - `istock_exclusive` boolean, 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
    - `mastered_to` string, nullable
    - `max_dimensions` GettyImagesServicesConnectPublicModelsMaxDimensions
      - `height` integer
      - `width` integer
    - `orientation` string, nullable
    - `originally_shot_on` string, nullable
    - `product_types` string[], nullable
    - `quality_rank` integer, nullable
    - `referral_destinations` GettyImagesServicesConnectPublicModelsReferralDestination[], nullable
      - `site_name` string, nullable
      - `uri` string, nullable
    - `shot_speed` string, nullable
    - `title` string, nullable
    - `istock_licenses` GettyImagesServicesConnectPublicModelsIStockLicense[], nullable
      - `license_type` 'Standard' | 'Multiseat' | 'Unlimited' | 'Resale' | 'Indemnification'
      - `credits` integer
    - `object_name` string, 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
  - `result_count` integer
  - `auto_corrections` GettyImagesServicesConnectPublicModelsSearchAutoCorrections
    - `phrase` string, nullable

## Other responses

- `400` — InvalidParameterValue
- `401` — AuthorizationTokenRequired
- `403` — UnauthorizedDisplaySize
- `404` — AssetNotFound
- `500` — InvalidIStockCollection

---

[API](https://skmtc.net/gettyimages/apis/getty-images-api.md) · [All operations](https://skmtc.net/gettyimages/apis/getty-images-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gettyimages/getty-images-api/revisions/29f239eeae86/schema)