openapi: 3.0.1 info: title: Getty Images Creative API version: '3' description: ' Developer resources for the Getty Images API including SDK, documentation, release notes, status, notifications and sample code.' security: - Api-Key: [] - OAuth2: [] tags: - name: Creative paths: /v3/search/images/creative: get: tags: - Creative summary: Search for creative images only description: "Use this endpoint to search our contemporary stock photos, illustrations and archival images.\n\nYou'll need an API key and access token to use this resource.\n \nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token.\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to \nbuild search response results. The following fields are provided for every image in your result set when you include **summary_set** in your request.\n\n```\n{\n \"images\": \n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"display_sizes\": \n [\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"max_dimensions\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **detail_set** query string parameter fields value represents a large batch of metadata fields that are often used to \nbuild a detailed view of images. The following fields are provided for every image in your result set when you include **detail_set** in your request.\n\n```\n{\n \"images\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n \"call_for_image\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\": \n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"editorial_segments\",\n \"event_ids\",\n \"graphical_style\",\n \"license_model\",\n \"max_dimensions\",\n \"orientation\",\n \"product_types\",\n \"quality_rank\",\n \"referral_destinations\",\n \"title\"\n ]\n]\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution\nfiles that are most frequently used to build a UI displaying search results. The following fields are provided for every image \nin your result set when you include **display_set** in your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"images\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```\n\n## Enhanced Search\n\nOur enhanced search uses machine-learning models to understand natural, conversational language. Meaning you can search for longer phrases and get more relevant results from our creative image and creative video libraries. Default is `true`. Set `enhanced_search` to `false` if you require a precise result set and not one expanded through enhanced search." parameters: - name: Accept-Language in: header 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).' schema: 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).' - name: GI-Country-Code in: header description: 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. schema: type: string description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more. - name: age_of_people in: query description: Filter based on the age of individuals in an image. style: form explode: false schema: type: array items: $ref: '#/components/schemas/AgeOfPeopleFilterType' description: Filter based on the age of individuals in an image. nullable: true - name: artists in: query description: Search for images by specific artists (free-text, comma-separated list of artists). schema: type: string description: Search for images by specific artists (free-text, comma-separated list of artists). nullable: true - name: collection_codes in: query description: Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type. style: form explode: false schema: type: array items: type: string description: Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type. nullable: true - name: collections_filter_type in: query description: Use to include or exclude collections from search. The default is include schema: $ref: '#/components/schemas/CollectionsFilterType' - name: color in: query description: 'Filter based on predominant color in an image. Use 6 character hexadecimal format (e.g., #002244).' schema: type: string description: 'Filter based on predominant color in an image. Use 6 character hexadecimal format (e.g., #002244).' nullable: true - name: compositions in: query description: Filter based on image composition. style: form explode: false schema: type: array items: $ref: '#/components/schemas/CompositionsFilterType' description: Filter based on image composition. nullable: true - name: download_product in: query description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, 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 download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response." schema: type: string description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, 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 download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response." nullable: true - name: embed_content_only in: query description: Restrict search results to embeddable images. The default is false. schema: type: boolean description: Restrict search results to embeddable images. The default is false. default: false - name: enhanced_search in: query description: If set to {false}, your search will not use enhanced search. Defaults to {true}. schema: type: boolean description: If set to {false}, your search will not use enhanced search. Defaults to {true}. default: true nullable: true - name: ethnicity in: query description: Filter search results based on the ethnicity of individuals in an image. style: form explode: false schema: type: array items: $ref: '#/components/schemas/EthnicityFilterType' description: Filter search results based on the ethnicity of individuals in an image. nullable: true - name: exclude_editorial_use_only in: query description: Exclude images that are only available for editorial (non-commercial) use. Default value is false. schema: type: boolean description: Exclude images that are only available for editorial (non-commercial) use. Default value is false. nullable: true - name: exclude_keyword_ids in: query description: Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned. style: form explode: false schema: type: array items: type: integer format: int32 description: Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned. nullable: true - name: exclude_nudity in: query description: Excludes images containing nudity. The default is false. schema: type: boolean description: Excludes images containing nudity. The default is false. default: false - name: facet_fields in: query 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." style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreateImageSearchFacetsFields' 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." nullable: true - name: facet_max_count in: query description: Specifies the maximum number of facets to return per type. Default is 300. schema: type: integer description: Specifies the maximum number of facets to return per type. Default is 300. format: int32 default: 300 - name: fields in: query description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreativeImagesFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' nullable: true - name: file_types in: query description: Return only images having a specific file type. style: form explode: false schema: type: array items: $ref: '#/components/schemas/SearchFileType' description: Return only images having a specific file type. nullable: true - name: graphical_styles in: query description: Filter based on graphical style of the image. style: form explode: false schema: type: array items: $ref: '#/components/schemas/GraphicalStyle' description: Filter based on graphical style of the image. nullable: true - name: graphical_styles_filter_type in: query description: Provides searching based on specified graphical style(s). The default is include. schema: $ref: '#/components/schemas/GraphicalStylesFilterType' - name: include_facets in: query description: Specifies whether or not to include facets in the result set. Default is "false". schema: type: boolean description: Specifies whether or not to include facets in the result set. Default is "false". nullable: true - name: include_related_searches in: query description: Specifies whether or not to include related searches in the response. The default is false. schema: type: boolean description: Specifies whether or not to include related searches in the response. The default is false. default: false - name: keyword_ids in: query description: Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned. style: form explode: false schema: type: array items: type: integer format: int32 description: Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned. nullable: true - name: minimum_size in: query description: Filter based on minimum size requested. The default is x-small. schema: $ref: '#/components/schemas/TeeShirtSize' - name: moods in: query description: Filter based on predominant mood in an image. style: form explode: false schema: type: array items: $ref: '#/components/schemas/MoodFilterType' description: Filter based on predominant mood in an image. nullable: true - name: number_of_people in: query description: Filter based on the number of people in the image. style: form explode: false schema: type: array items: $ref: '#/components/schemas/NumberOfPeopleFilterType' description: Filter based on the number of people in the image. nullable: true - name: orientations in: query description: Return only images with selected aspect ratios. style: form explode: false schema: type: array items: $ref: '#/components/schemas/ImageOrientationRequest' description: Return only images with selected aspect ratios. nullable: true - name: page in: query description: Request results starting at a page number (default is 1). schema: type: integer description: Request results starting at a page number (default is 1). format: int32 default: 1 - name: page_size in: query description: Request number of images to return in each page. Default is 30, maximum page_size is 100. schema: type: integer description: Request number of images to return in each page. Default is 30, maximum page_size is 100. format: int32 default: 30 - name: phrase in: query description: Search images using a search phrase. schema: type: string description: Search images using a search phrase. default: '' nullable: true - name: safe_search in: query description: Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative. schema: type: boolean description: Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative. default: false - name: sort_order in: query description: Select sort order of results. The default is best_match schema: $ref: '#/components/schemas/CreativeImageSortOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreativeImageSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '500': description: InvalidIStockCollection /v3/search/images/creative/by-image: get: tags: - Creative summary: Search for creative images based on url description: '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. ' parameters: - name: Accept-Language in: header 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).' schema: 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).' - name: GI-Country-Code in: header description: 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. schema: type: string description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more. - name: asset_id in: query description: Specifies the Getty image id to use in the search. schema: type: string description: Specifies the Getty image id to use in the search. nullable: true - name: exclude_editorial_use_only in: query description: Exclude images that are only available for editorial (non-commercial) use. Default value is false. schema: type: boolean description: Exclude images that are only available for editorial (non-commercial) use. Default value is false. nullable: true - name: facet_fields in: query 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." style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreateImageSearchFacetsFields' 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." nullable: true - name: facet_max_count in: query description: Specifies the maximum number of facets to return per type. Default is 300. schema: type: integer description: Specifies the maximum number of facets to return per type. Default is 300. format: int32 default: 300 - name: fields in: query description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreativeImagesFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' nullable: true - name: image_url in: query description: Specifies the location of the image to use in the search. schema: type: string description: Specifies the location of the image to use in the search. nullable: true - name: include_facets in: query description: Specifies whether or not to include facets in the result set. Default is "false". schema: type: boolean description: Specifies whether or not to include facets in the result set. Default is "false". nullable: true - name: page in: query description: Request results starting at a page number (default is 1). schema: type: integer description: Request results starting at a page number (default is 1). format: int32 default: 1 - name: page_size in: query description: Request number of images to return in each page. Default is 30, maximum page_size is 100. schema: type: integer description: Request number of images to return in each page. Default is 30, maximum page_size is 100. format: int32 default: 30 - name: phrase in: query description: Free-text search query. schema: type: string description: Free-text search query. default: '' nullable: true - name: product_types in: query 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." style: form explode: false schema: type: array items: type: string 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." nullable: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SearchByImageResourceResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: AssetNotFound '500': description: InvalidIStockCollection /v3/search/videos/creative: get: tags: - Creative summary: Search for creative videos description: "Use this endpoint to search premium stock video, from archival film to contemporary 4K and HD footage.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without\nbeing logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only \nassets that you have a license to use, you need to also include an authorization token in the header of your request.\nPlease consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens.\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to build search\nresponse results. The following fields are provided for every video in your result set when you include **summary_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"asset_family\", \n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **detail_set** query string parameter fields value represents a large batch of metadata fields that are often used to build a \ndetailed view of videos. The following fields are provided for every video in your result set when you include **detail_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\", \n\t\t\"call_for_image\",\n \"caption\", \n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\", \n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"era\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution files \nthat are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result \nset when you include **display_set** in your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```\n\n## Enhanced Search\n\nOur enhanced search uses machine-learning models to understand natural, conversational language. Meaning you can search for longer phrases and get more relevant results from our creative image and creative video libraries. Default is `true`. Set `enhanced_search` to `false` if you require a precise result set and not one expanded through enhanced search." parameters: - name: Accept-Language in: header 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).' schema: 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).' - name: GI-Country-Code in: header description: 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. schema: type: string description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more. - name: age_of_people in: query description: Provides filtering according to the age of individuals in a video. style: form explode: false schema: type: array items: $ref: '#/components/schemas/AgeOfPeopleFilterType' description: Provides filtering according to the age of individuals in a video. nullable: true - name: artists in: query description: Search for videos by specific artists (free-text, comma-separated list of artists). schema: type: string description: Search for videos by specific artists (free-text, comma-separated list of artists). nullable: true - name: aspect_ratios in: query description: Search for videos by specific aspect ratios. style: form explode: false schema: type: array items: $ref: '#/components/schemas/VideoAspectRatioFilterType' description: Search for videos by specific aspect ratios. nullable: true - name: collection_codes in: query description: Provides filtering by collection code. style: form explode: false schema: type: array items: type: string description: Provides filtering by collection code. nullable: true - name: collections_filter_type in: query description: Use to include or exclude collections from search. The default is include schema: $ref: '#/components/schemas/CollectionsFilterType' - name: compositions in: query description: Filter based on video composition. style: form explode: false schema: type: array items: $ref: '#/components/schemas/CompositionsFilterType' description: Filter based on video composition. nullable: true - name: download_product in: query description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, 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 download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response." schema: type: string description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, 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 download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response." nullable: true - name: enhanced_search in: query description: If set to {false}, your search will not use enhanced search. Defaults to {true}. schema: type: boolean description: If set to {false}, your search will not use enhanced search. Defaults to {true}. default: true nullable: true - name: ethnicity in: query description: Filter search results based on the ethnicity of individuals. style: form explode: false schema: type: array items: $ref: '#/components/schemas/EthnicityFilterType' description: Filter search results based on the ethnicity of individuals. nullable: true - name: exclude_editorial_use_only in: query description: Exclude videos that are only available for editorial (non-commercial) use. Default value is false. schema: type: boolean description: Exclude videos that are only available for editorial (non-commercial) use. Default value is false. nullable: true - name: exclude_keyword_ids in: query description: Return only videos not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also do not contain the requested keyword(s) are returned. style: form explode: false schema: type: array items: type: integer format: int32 description: Return only videos not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also do not contain the requested keyword(s) are returned. nullable: true - name: exclude_nudity in: query description: Excludes videos containing nudity. The default is false. schema: type: boolean description: Excludes videos containing nudity. The default is false. default: false - name: facet_fields in: query 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." style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreateVideoSearchFacetsFields' 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." nullable: true - name: facet_max_count in: query description: Specifies the maximum number of facets to return per type. Default is 300. schema: type: integer description: Specifies the maximum number of facets to return per type. Default is 300. format: int32 default: 300 - name: fields in: query description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreativeVideosFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' nullable: true - name: format_available in: query description: Filters according to the digital video format available on a film asset. schema: $ref: '#/components/schemas/VideoFormatsRequest' - name: frame_rates in: query description: Provides filtering by video frame rate (frames/second). style: form explode: false schema: type: array items: $ref: '#/components/schemas/VideoFrameRates' description: Provides filtering by video frame rate (frames/second). nullable: true - name: image_techniques in: query description: Filter based on image technique. style: form explode: false schema: type: array items: $ref: '#/components/schemas/ImageTechniquesFilterType' description: Filter based on image technique. nullable: true - name: include_facets in: query description: Specifies whether or not to include facets in the result set. Default is "false". schema: type: boolean description: Specifies whether or not to include facets in the result set. Default is "false". nullable: true - name: include_related_searches in: query description: Specifies whether or not to include related searches in the response. The default is false. schema: type: boolean description: Specifies whether or not to include related searches in the response. The default is false. default: false - name: keyword_ids in: query description: Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned. style: form explode: false schema: type: array items: type: integer format: int32 description: Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned. nullable: true - name: license_models in: query description: Specifies the video licensing model(s). style: form explode: false schema: type: array items: $ref: '#/components/schemas/LicenseModelVideoRequest' description: Specifies the video licensing model(s). nullable: true - name: min_clip_length in: query description: Provides filtering by minimum length of video clip, in seconds schema: type: integer description: Provides filtering by minimum length of video clip, in seconds format: int32 default: 0 - name: max_clip_length in: query description: Provides filtering by maximum length of video, in seconds schema: type: integer description: Provides filtering by maximum length of video, in seconds format: int32 default: 0 - name: number_of_people in: query description: Filter based on the number of people. style: form explode: false schema: type: array items: $ref: '#/components/schemas/NumberOfPeopleFilterType' description: Filter based on the number of people. nullable: true - name: orientations in: query description: Return only videos with selected orientations. style: form explode: false schema: type: array items: $ref: '#/components/schemas/VideoOrientationRequest' description: Return only videos with selected orientations. nullable: true - name: page in: query description: Identifies page to return. Default is 1. schema: type: integer description: Identifies page to return. Default is 1. format: int32 default: 1 - name: page_size in: query description: Specifies page size. Default is 30, maximum page_size is 100. schema: type: integer description: Specifies page size. Default is 30, maximum page_size is 100. format: int32 default: 30 - name: phrase in: query description: Free-text search query. schema: type: string description: Free-text search query. default: '' nullable: true - name: safe_search in: query description: Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative. schema: type: boolean description: Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative. default: false - name: sort_order in: query description: Select sort order of results. The default is best_match schema: $ref: '#/components/schemas/CreativeVideoSortOrder' - name: release_status in: query description: Allows filtering by type of model release. schema: $ref: '#/components/schemas/ReleaseStatus' - name: viewpoints in: query description: Filter based on viewpoint. style: form explode: false schema: type: array items: $ref: '#/components/schemas/ViewpointsFilterType' description: Filter based on viewpoint. nullable: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreativeVideoSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '500': description: InvalidIStockCollection /v3/search/videos/creative/by-image: get: tags: - Creative summary: Search for creative videos based on url description: '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. ' parameters: - name: Accept-Language in: header 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).' schema: 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).' - name: GI-Country-Code in: header description: 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. schema: type: string description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more. - name: asset_id in: query description: Specifies the Getty video id to use in the search. schema: type: string description: Specifies the Getty video id to use in the search. nullable: true - name: exclude_editorial_use_only in: query description: Exclude videos that are only available for editorial (non-commercial) use. Default value is false. schema: type: boolean description: Exclude videos that are only available for editorial (non-commercial) use. Default value is false. nullable: true - name: facet_fields in: query 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." style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreateVideoSearchFacetsFields' 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." nullable: true - name: facet_max_count in: query description: Specifies the maximum number of facets to return per type. Default is 300. schema: type: integer description: Specifies the maximum number of facets to return per type. Default is 300. format: int32 default: 300 - name: fields in: query description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' style: form explode: false schema: type: array items: $ref: '#/components/schemas/CreativeVideosFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' nullable: true - name: image_url in: query description: Specifies the location of the image to use in the search. schema: type: string description: Specifies the location of the image to use in the search. nullable: true - name: include_facets in: query description: Specifies whether or not to include facets in the result set. Default is "false". schema: type: boolean description: Specifies whether or not to include facets in the result set. Default is "false". nullable: true - name: page in: query description: Request results starting at a page number (default is 1). schema: type: integer description: Request results starting at a page number (default is 1). format: int32 default: 1 - name: page_size in: query description: Request number of images to return in each page. Default is 30, maximum page_size is 100. schema: type: integer description: Request number of images to return in each page. Default is 30, maximum page_size is 100. format: int32 default: 30 - name: phrase in: query description: Free-text search query. schema: type: string description: Free-text search query. default: '' nullable: true - name: product_types in: query 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." style: form explode: false schema: type: array items: type: string 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." nullable: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreativeVideoSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: AssetNotFound '500': description: InvalidIStockCollection components: schemas: SearchFacetsResponse: type: object properties: specific_people: type: array items: $ref: '#/components/schemas/SpecificPeople' nullable: true events: type: array items: $ref: '#/components/schemas/FacetEvent' nullable: true locations: type: array items: $ref: '#/components/schemas/Location' nullable: true artists: type: array items: $ref: '#/components/schemas/Artist' nullable: true entertainment: type: array items: $ref: '#/components/schemas/Entertainment' nullable: true additionalProperties: false ImageOrientationRequest: enum: - horizontal - vertical - square - panoramic_horizontal - panoramic_vertical type: string CreativeImagesFieldValues: enum: - allowed_use - alternative_ids - artist - asset_family - call_for_image - caption - collection_code - collection_id - collection_name - color_type - comp - comp_webp - copyright - date_camera_shot - date_created - date_submitted - detail_set - display_set - download_product - download_sizes - graphical_style - id - istock_collection - keywords - largest_downloads - license_model - max_dimensions - orientation - preview - product_types - quality_rank - referral_destinations - summary_set - thumb - title - uri_oembed type: string FacetEvent: type: object properties: id: type: integer format: int32 name: type: string nullable: true date: type: string format: date-time additionalProperties: false CreativeImageSortOrder: enum: - best_match - most_popular - newest - random type: string VideoFrameRates: enum: - '23.98' - '24' - '25' - '29.97' - '30' - '50' - '59.94' - '60' type: string MoodFilterType: enum: - black_and_white - bold - cool - dramatic - natural - vivid - warm type: string CompositionsFilterType: enum: - abstract - candid - close_up - copy_space - cut_out - full_frame - full_length - headshot - looking_at_camera - macro - medium_shot - part_of_a_series - portrait - sparse - still_life - three_quarter_length - waist_up - wide_shot type: string CreativeVideosFieldValues: 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 type: string ImageTechniquesFilterType: enum: - realtime - time_lapse - slow_motion - color - black_and_white - animation - selective_focus type: string ReferralDestination: type: object properties: site_name: type: string nullable: true uri: type: string nullable: true additionalProperties: false CreativeVideoSortOrder: enum: - best_match - most_popular - newest - random type: string ImageSearchItemDisplaySize: type: object properties: is_watermarked: type: boolean name: type: string nullable: true uri: type: string nullable: true additionalProperties: false VideoSearchItemDisplaySize: type: object properties: is_watermarked: type: boolean name: type: string nullable: true uri: type: string nullable: true aspect_ratio: type: string nullable: true additionalProperties: false ReleaseStatus: enum: - release_not_important - fully_released type: string MaxDimensions: type: object properties: height: type: integer format: int32 width: type: integer format: int32 additionalProperties: false VideoFormatsRequest: enum: - sd - hd - 4k - hd_web type: string CollectionsFilterType: enum: - include - exclude type: string RelatedSearch: type: object properties: phrase: type: string nullable: true url: type: string nullable: true additionalProperties: false CreativeVideoSearchItem: type: object properties: id: type: string nullable: true allowed_use: $ref: '#/components/schemas/AllowedUse' artist: type: string nullable: true asset_family: type: string nullable: true caption: type: string nullable: true clip_length: type: string nullable: true collection_id: type: integer format: int32 nullable: true collection_code: type: string nullable: true collection_name: type: string nullable: true color_type: type: string nullable: true copyright: type: string nullable: true date_created: type: string format: date-time nullable: true display_sizes: type: array items: $ref: '#/components/schemas/VideoSearchItemDisplaySize' nullable: true download_product: type: string nullable: true era: type: string nullable: true event_ids: type: array items: type: integer format: int32 nullable: true keywords: type: array items: $ref: '#/components/schemas/Keyword' nullable: true largest_downloads: type: array items: $ref: '#/components/schemas/Download' nullable: true license_model: type: string nullable: true mastered_to: type: string nullable: true originally_shot_on: type: string nullable: true product_types: type: array items: type: string nullable: true referral_destinations: type: array items: $ref: '#/components/schemas/ReferralDestination' nullable: true shot_speed: type: string nullable: true title: type: string nullable: true istock_licenses: type: array items: $ref: '#/components/schemas/IStockLicense' nullable: true additionalProperties: false AllowedUse: type: object properties: how_can_i_use_it: type: string description: Indicates how the asset can be used nullable: true release_info: type: string description: Indicates release status nullable: true usage_restrictions: type: array items: type: string description: Indicates asset usage restriction, if any nullable: true additionalProperties: false Location: type: object properties: id: type: integer format: int32 name: type: string nullable: true additionalProperties: false GraphicalStylesFilterType: enum: - include - exclude type: string VideoOrientationRequest: enum: - horizontal - vertical type: string VideoAspectRatioFilterType: enum: - '16:9' - '9:16' - '3:4' - '4:3' - '4:5' - '2:1' - '17:9' - '9:17' type: string CreateImageSearchFacetsFields: enum: - artists - locations type: string Entertainment: type: object properties: id: type: integer format: int32 name: type: string nullable: true additionalProperties: false Download: type: object properties: product_id: type: string nullable: true product_type: type: string nullable: true uri: type: string nullable: true agreement_name: type: string nullable: true additionalProperties: false IStockLicense: type: object properties: license_type: $ref: '#/components/schemas/AssetLicenseName' credits: type: integer format: int32 additionalProperties: false SearchByImageResourceResults: type: object properties: image_fingerprint: type: string nullable: true related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' nullable: true deprecated: true result_count: type: integer format: int32 images: nullable: true facets: $ref: '#/components/schemas/SearchFacetsResponse' auto_corrections: $ref: '#/components/schemas/AutoCorrections' additionalProperties: false CreativeImageSearchResults: type: object properties: result_count: type: integer format: int32 images: type: array items: $ref: '#/components/schemas/ImageSearchItemCreative' nullable: true auto_corrections: $ref: '#/components/schemas/AutoCorrections' related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' nullable: true additionalProperties: false CreateVideoSearchFacetsFields: enum: - artists - locations type: string LicenseModelVideoRequest: enum: - rightsready - royaltyfree type: string Keyword: type: object properties: keyword_id: type: string nullable: true text: type: string nullable: true type: type: string nullable: true relevance: type: integer format: int32 nullable: true entity_uris: type: array items: type: string nullable: true entity_types: type: array items: type: string nullable: true additionalProperties: false TeeShirtSize: enum: - x_small - small - medium - large - x_large - xx_large - vector type: string ViewpointsFilterType: enum: - lockdown - panning - tracking_shot - aerial_view - high_angle_view - low_angle_view - tilt - point_of_view type: string AutoCorrections: type: object properties: phrase: type: string nullable: true additionalProperties: false EthnicityFilterType: enum: - black - white - east_asian - hispanic_latinx - japanese - middle_eastern - multiracial_person - multiethnic_group - native_american_first_nations - pacific_islander - south_asian - southeast_asian type: string SpecificPeople: type: object properties: id: type: integer format: int32 name: type: string nullable: true additionalProperties: false CreativeVideoSearchResults: type: object properties: result_count: type: integer format: int32 videos: type: array items: $ref: '#/components/schemas/CreativeVideoSearchItem' nullable: true facets: $ref: '#/components/schemas/SearchFacetsResponse' auto_corrections: $ref: '#/components/schemas/AutoCorrections' related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' nullable: true additionalProperties: false AgeOfPeopleFilterType: enum: - newborn - baby - child - teenager - young_adult - adult - adults_only - mature_adult - senior_adult - 0-1_months - 2-5_months - 6-11_months - 12-17_months - 18-23_months - 2-3_years - 4-5_years - 6-7_years - 8-9_years - 10-11_years - 12-13_years - 14-15_years - 16-17_years - 18-19_years - 20-24_years - 20-29_years - 25-29_years - 30-34_years - 30-39_years - 35-39_years - 40-44_years - 40-49_years - 45-49_years - 50-54_years - 50-59_years - 55-59_years - 60-64_years - 60-69_years - 65-69_years - 70-79_years - 80-89_years - 90_plus_years - 100_over type: string GraphicalStyle: enum: - fine_art - illustration - photography - vector type: string SearchFileType: enum: - eps type: string Artist: type: object properties: name: type: string nullable: true additionalProperties: false ImageSearchItemCreative: type: object properties: allowed_use: $ref: '#/components/schemas/AllowedUse' alternative_ids: type: object additionalProperties: type: string nullable: true artist: type: string nullable: true asset_family: type: string nullable: true call_for_image: type: boolean caption: type: string nullable: true collection_code: type: string nullable: true collection_id: type: integer format: int32 nullable: true collection_name: type: string nullable: true color_type: type: string nullable: true copyright: type: string nullable: true date_camera_shot: type: string format: date-time nullable: true date_created: type: string format: date-time nullable: true display_sizes: type: array items: $ref: '#/components/schemas/ImageSearchItemDisplaySize' nullable: true download_product: type: string nullable: true graphical_style: type: string nullable: true id: type: string nullable: true keywords: type: array items: $ref: '#/components/schemas/Keyword' nullable: true largest_downloads: type: array items: $ref: '#/components/schemas/Download' nullable: true license_model: type: string nullable: true max_dimensions: $ref: '#/components/schemas/MaxDimensions' orientation: type: string nullable: true quality_rank: type: integer format: int32 referral_destinations: type: array items: $ref: '#/components/schemas/ReferralDestination' nullable: true title: type: string nullable: true uri_oembed: type: string nullable: true additionalProperties: false AssetLicenseName: enum: - Standard - Multiseat - Unlimited - Resale - Indemnification type: string NumberOfPeopleFilterType: enum: - none - one - two - group type: string securitySchemes: Api-Key: type: apiKey name: Api-Key in: header OAuth2: type: oauth2 flows: password: tokenUrl: https://api.gettyimages.com/v4/oauth2/token refreshUrl: https://api.gettyimages.com/v4/oauth2/token scopes: {} clientCredentials: tokenUrl: https://api.gettyimages.com/v4/oauth2/token scopes: {} authorizationCode: authorizationUrl: https://api.gettyimages.com/v4/oauth2/auth tokenUrl: https://api.gettyimages.com/v4/oauth2/token refreshUrl: https://api.gettyimages.com/v4/oauth2/token scopes: {}