Search for creative videos based on url

v1.0.0

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:

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.

Input

{
  "type": "object",
  "properties": {
    "Accept-Language": {
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more."
    },
    "asset_id": {
      "type": "string",
      "description": "Specifies the Getty video id to use in the search."
    },
    "exclude_editorial_use_only": {
      "type": "boolean",
      "description": "Exclude videos that are only available for editorial (non-commercial) use. Default value is false."
    },
    "facet_fields": {
      "type": "array",
      "description": "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n                    The include_facets parameter must be set to \"true\" for facets to be returned.",
      "items": {
        "type": "string",
        "enum": [
          "artists",
          "locations"
        ]
      }
    },
    "facet_max_count": {
      "type": "integer",
      "format": "int32",
      "description": "Specifies the maximum number of facets to return per type. Default is 300."
    },
    "fields": {
      "type": "array",
      "description": "Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.",
      "items": {
        "type": "string",
        "enum": [
          "allowed_use",
          "artist",
          "aspect_ratio",
          "asset_family",
          "call_for_image",
          "caption",
          "clip_length",
          "collection_code",
          "collection_id",
          "collection_name",
          "color_type",
          "comp",
          "copyright",
          "date_created",
          "date_submitted",
          "detail_set",
          "display_set",
          "download_product",
          "download_sizes",
          "era",
          "id",
          "istock_collection",
          "keywords",
          "largest_downloads",
          "license_model",
          "mastered_to",
          "object_name",
          "orientation",
          "originally_shot_on",
          "preview",
          "product_types",
          "quality_rank",
          "referral_destinations",
          "shot_speed",
          "summary_set",
          "thumb",
          "title"
        ]
      }
    },
    "image_url": {
      "type": "string",
      "description": "Specifies the location of the image to use in the search."
    },
    "include_facets": {
      "type": "boolean",
      "description": "Specifies whether or not to include facets in the result set. Default is \"false\"."
    },
    "page": {
      "type": "integer",
      "format": "int32",
      "description": "Request results starting at a page number (default is 1)."
    },
    "page_size": {
      "type": "integer",
      "format": "int32",
      "description": "Request number of images to return in each page. Default is 30, maximum page_size is 100."
    },
    "product_types": {
      "type": "array",
      "description": "Filter images to those from one of your product types. \r\n                    Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. \r\n                    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. \r\n                    For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. \r\n                    Product ID can be obtained from the GET /products response.",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "properties": {
    "auto_corrections": {
      "type": "object",
      "properties": {
        "phrase": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "facets": {
      "type": "object",
      "properties": {
        "artists": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "entertainment": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "format": "date-time"
              },
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "locations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "specific_people": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "related_searches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "phrase": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "result_count": {
      "type": "integer",
      "format": "int32"
    },
    "videos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "allowed_use": {
            "type": "object",
            "properties": {
              "how_can_i_use_it": {
                "type": "string",
                "description": "Indicates how the asset can be used"
              },
              "release_info": {
                "type": "string",
                "description": "Indicates release status"
              },
              "usage_restrictions": {
                "type": "array",
                "description": "Indicates asset usage restriction, if any",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          },
          "artist": {
            "type": "string"
          },
          "asset_family": {
            "type": "string"
          },
          "caption": {
            "type": "string"
          },
          "clip_length": {
            "type": "string"
          },
          "collection_code": {
            "type": "string"
          },
          "collection_id": {
            "type": "integer",
            "format": "int32"
          },
          "collection_name": {
            "type": "string"
          },
          "color_type": {
            "type": "string"
          },
          "copyright": {
            "type": "string"
          },
          "date_created": {
            "type": "string",
            "format": "date-time"
          },
          "display_sizes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "aspect_ratio": {
                  "type": "string"
                },
                "is_watermarked": {
                  "type": "boolean"
                },
                "name": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "download_product": {
            "type": "string"
          },
          "era": {
            "type": "string"
          },
          "event_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32"
            }
          },
          "id": {
            "type": "string"
          },
          "istock_licenses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "credits": {
                  "type": "integer",
                  "format": "int32"
                },
                "license_type": {
                  "type": "string",
                  "enum": [
                    "Standard",
                    "Multiseat",
                    "Unlimited",
                    "Resale",
                    "Indemnification"
                  ]
                }
              },
              "additionalProperties": false
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "entity_types": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "entity_uris": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "keyword_id": {
                  "type": "string"
                },
                "relevance": {
                  "type": "integer",
                  "format": "int32"
                },
                "text": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "largest_downloads": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "agreement_name": {
                  "type": "string"
                },
                "product_id": {
                  "type": "string"
                },
                "product_type": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "license_model": {
            "type": "string"
          },
          "mastered_to": {
            "type": "string"
          },
          "originally_shot_on": {
            "type": "string"
          },
          "product_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "referral_destinations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "site_name": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "shot_speed": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}