openapi: 3.0.1 info: title: Getty Images 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: Images paths: /v3/affiliates/search/images: get: tags: - Images summary: '' 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: phrase in: query description: Search images using a search phrase. schema: type: string description: Search images using a search phrase. nullable: true - name: style in: query description: Filter based on graphical style of the image. schema: $ref: '#/components/schemas/AffiliateSearchStyle' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AffiliateImageSearchResponse' /v3/ai/image-generations/{generationRequestId}/images/{index}/variations: post: tags: - Images summary: Get variations on a generated image description: '# AI Generator - Generate Variations Generate image variations from a previously-generated image. ## The Image Variation Request The `ImageVariationRequest` payload to be posted contains the optional parameters: | Parameter | Purpose | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `product_id` | If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this generation request. If you have multiple products, this property is _required_. Can be retrieved from products (`GET /v3/products`). | | `notes` | This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. | | `project_code` | If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. | ## Fulfilled and Pending Results In many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK` result and a payload including URLs to the result images and a generation request `id` value. However some generations may take more time than can be accommodated in the initial call. In these cases the result of this call is `HTTP 202 Accepted` and the payload will only contain a generation request `id` value. This value must be retained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint. ## Lifetime of Generated Images Generated images will be retained for 6 months after generation. ' parameters: - name: generationRequestId in: path description: The ID from a previous request to generate images required: true style: simple schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true style: simple schema: type: integer format: int32 requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/ImageVariationRequest' text/json: schema: $ref: '#/components/schemas/ImageVariationRequest' application/*+json: schema: $ref: '#/components/schemas/ImageVariationRequest' responses: '200': description: Returns the result of a request to generate a variation of images content: application/json: schema: $ref: '#/components/schemas/ImageGenerationsResponse' '202': description: Returns the request ID for a pending request to generate a variation of images content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '400': description: InvalidProduct '403': description: Product quota exceeded '404': description: Either the generation id does not exist, the index is incorrect, or the generation is still pending '429': description: TooManyConcurrentGenerations /v3/ai/image-generations/{generationRequestId}/images/{index}/download-sizes: get: tags: - Images summary: Get download sizes for a generated image description: '# AI Generator - Get Download Sizes Given a fulfilled generation request `id` and the `index` of a generated image, gets a list of download sizes for the image. ' parameters: - name: generationRequestId in: path description: The ID from a previous request to generate images required: true style: simple schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true style: simple schema: type: integer format: int32 responses: '200': description: Returns the result of a request content: application/json: schema: $ref: '#/components/schemas/DownloadSizesResponse' '400': description: InvalidProduct '404': description: Either the generation id does not exist, the index is incorrect, or the generation is still pending '410': description: GenerationRequestGone /v3/ai/image-generations/{generationRequestId}/images/{index}/download: put: tags: - Images summary: Begin the download process description: '# AI Generator - Download Image Download a generated image. Initiating the download process for a 4K file may incur a cost depending on the terms of your agreement. ## Download Image Request body details The `ImageDownloadRequest` payload to be posted contains the required `size` as well as some other optional parameters: | Parameter | Purpose | |-------------------|----------------------------------------------------------------------------------------------| | `size_name` _Required_ | Must be one of the valid download sizes retrieved through the "Get Download Sizes" endpoint | | `notes` | This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. | | `project_code` | If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. | ## Fulfilled and Pending Results In many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK` result and a payload including a URL for the download. However some generations may take more time than can be accommodated in the initial call. In these cases the result of this call is `HTTP 202 Accepted` with no payload. This client should then poll `GET v3/ai/image-generations/{generationRequestId}/images/{index}/download` periodically to get the final download. ' parameters: - name: generationRequestId in: path description: The ID from a previous request to generate images required: true style: simple schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true style: simple schema: type: integer format: int32 requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/ImageDownloadRequest' text/json: schema: $ref: '#/components/schemas/ImageDownloadRequest' application/*+json: schema: $ref: '#/components/schemas/ImageDownloadRequest' responses: '200': description: Download request was successful and is complete content: text/plain: schema: $ref: '#/components/schemas/DownloadResponse' application/json: schema: $ref: '#/components/schemas/DownloadResponse' text/json: schema: $ref: '#/components/schemas/DownloadResponse' '202': description: Download request was successful put is pending '400': description: InvalidProduct '403': description: ProductQuotaExceeded '404': description: GenerationRequestIdNotFound '409': description: A download is already in progress for the given `generationRequestId` and `index`. '410': description: GenerationRequestGone get: tags: - Images summary: "Once the download process has started, this endpoint can be used to check the status of the download and get the\r\ndownload URL once it is completed." description: '# AI Generator - Get Download Image Get the download for a generated image ## Fulfilled and Pending Results In many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK` result and a payload including a URL for the download. However some generations may take more time than can be accommodated in the initial call. In these cases the result of this call is `HTTP 202 Accepted` with no payload. This client should then poll `GET v3/ai/image-generations/{generationRequestId}/images/{index}/download` periodically to get the final download. Like the `PUT v3/ai/image-generations/{generationRequestId}/images/{index}/download` endpoint, the result of calling this endpoint will be either: - `HTTP 200 OK` with the download URL - `HTTP 202 Accepted` with no payload `HTTP 202 Accepted` is returned in the case where the download preparation has not yet completed. In this case it is expected that the client will occasionally poll this endpoint until a `HTTP 200 OK` result with a full payload is returned. ' parameters: - name: generationRequestId in: path description: The ID from a previous request to generate images required: true style: simple schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true style: simple schema: type: integer format: int32 responses: '200': description: Download request was successful and is complete content: text/plain: schema: $ref: '#/components/schemas/DownloadResponse' application/json: schema: $ref: '#/components/schemas/DownloadResponse' text/json: schema: $ref: '#/components/schemas/DownloadResponse' '202': description: Download request was successful put is pending '400': description: InvalidProduct '404': description: GenerationRequestIdNotFound '410': description: GenerationRequestGone /v3/artists/images: get: tags: - Images summary: Search for images by a photographer 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: artist_name in: query description: Name of artist for desired images schema: type: string description: Name of artist for desired images nullable: true - name: fields in: query description: Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned. style: form explode: false schema: type: array items: $ref: '#/components/schemas/ArtistsImageSearchFieldValues' description: Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned. nullable: true - name: page in: query description: Identifies page to return. Default page is 1. schema: type: integer description: Identifies page to return. Default page is 1. format: int32 default: 1 - name: page_size in: query description: Specifies page size. Default page_size is 10, maximum page_size is 100. schema: type: integer description: Specifies page size. Default page_size is 10, maximum page_size is 100. format: int32 default: 10 responses: '200': description: OK '400': description: InvalidParameterValue '401': description: Unauthorized /v3/downloads/images/{id}: post: tags: - Images summary: Download an image description: "Use this endpoint to generate download URLs and related data for images you are authorized to download.\n\nMost product offerings have enforced periodic download limits such as monthly, weekly, and daily. When this operation executes, the count of allowed downloads is decremented by one for the product offering. Once the download limit is reached for a given product offering, no further downloads may be requested for that product offering until the next download period.\n\nThe download limit for a given download period is covered in your product agreement established with Getty Images.\n\nYou'll need an API key and a [Resource Owner Grant or Implicit Grant](http://developers.gettyimages.com/en/authorization-faq.html) access token to use this resource.\n\n## Auto Downloads\nThe `auto_download` request query parameter specifies whether to automatically download the image.\n\nIf the `auto_download` request query parameter is set to _true_, the API will return an HTTP status code 303 *See Other*.Your client code will need to process this response and redirect to the URI specified in the *Location* header to enable you to automatically download the file. The redirection workflow follows the [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4.4).\n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=true\n```\n\nServer Response:\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response Location header. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\n```\nHTTP/1.1 303 See Other\nLocation: https://delivery.gettyimages.com/...\n```\n\nIf the `auto_download` request query parameter is set to false, the API will return a HTTP status code 200, along with the URI in the response body which can be used to download the image. \n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=false\n```\n\nServer Response:\n\n```\nHTTP/1.1 200 OK\n{\n\t\"uri\": \"https://delivery.gettyimages.com/...\"\n}\n```\n## Downloading Via the Returned URI\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\nThe URI returned by this call should be considered opaque and the format could change at any time.\nIn order to get the filename, length or file type, the response headers must be inspected. An example\nresponse follows:\n\n```\ncontent-length: 33959979\ncontent-type: image/jpeg\ncontent-disposition: attachment; filename=GettyImages-1167612765.jpg\n```\n\nThe `content-disposition` header must be parsed to get a usable filename.\n\n## Download URI expiration\n\nDownload URIs are _**only valid for 24 hours**_, starting from the moment they are returned from this call.\n" 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: id in: path description: "\r\n Id of image to download.\r\n " required: true schema: type: string description: "\r\n Id of image to download.\r\n " nullable: true - name: auto_download in: query description: "\r\n Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the image.\r\n If false is specified, the download URI will be returned in the response message. Default is true.\r\n " schema: type: boolean description: "\r\n Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the image.\r\n If false is specified, the download URI will be returned in the response message. Default is true.\r\n " default: true - name: file_type in: query description: "\r\n File Type expressed with three character file extension.\r\n " schema: $ref: '#/components/schemas/DownloadFileType' - name: height in: query description: "\r\n Specifies the pixel height of the particular image to download.\r\n Available heights can be found in the images/{ids} response for the specific image.\r\n If left blank, it will return the largest available size.\r\n " schema: type: string description: "\r\n Specifies the pixel height of the particular image to download.\r\n Available heights can be found in the images/{ids} response for the specific image.\r\n If left blank, it will return the largest available size.\r\n " nullable: true - name: product_id in: query description: "\r\n Identifier of the instance for the selected product offering type.\r\n " schema: type: integer description: "\r\n Identifier of the instance for the selected product offering type.\r\n " format: int32 nullable: true - name: product_type in: query description: "\r\n Product types easyaccess, editorialsubscription, imagepack, and premiumaccess are for GettyImages API keys. Product types royaltyfreesubscription and creditpack are for iStock API keys. Default product type for iStock API keys is creditpack.\r\n " schema: $ref: '#/components/schemas/ProductTypeForDownloads' - name: use_team_credits in: query description: Specifies whether to download the image with iStock Team Credits. Only applicable to iStock API keys authenticated with a user that has Team Credits. Blank is the same as False. schema: type: boolean description: Specifies whether to download the image with iStock Team Credits. Only applicable to iStock API keys authenticated with a user that has Team Credits. Blank is the same as False. default: false nullable: true requestBody: description: "\r\n Additional information required from specific customers when downloading. \r\n Only users who have been set up with a project code by Getty Images Sales need to use this field.\r\n " content: application/json: schema: $ref: '#/components/schemas/PremiumAccessDownloadData' responses: '200': description: OK '303': description: See Other '400': description: MissingRequiredQueryParameters '401': description: AuthorizationTokenRequired '403': description: OverageLimitReached '404': description: ImageNotFound /v3/images: get: tags: - Images summary: Get metadata for multiple images by supplying multiple image ids description: "This endpoint returns the detailed image metadata for all specified images.\n\nYou'll need an API key and access token to use this resource.\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 \nsearch 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 \"artist\",\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\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 build a \ndetailed 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 \"artist_title\", \n \"asset_family\",\n \"call_for_image\",\n \"caption\", \n \"city\",\n \"collection_code\",\n \"collection_id\", \n \"collection_name\",\n \"color_type\", \n \"copyright\", \n \"country\", \n \"credit_line\", \n \"date_created\", \n \"date_submitted\",\n \"download_sizes\", \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 \"state_province\", \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## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\n" 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: ids in: query description: Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids. style: form explode: false schema: type: array items: type: string description: Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids. nullable: true - 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/ImageDetailFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' nullable: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ImagesDetailResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: ImageNotFound '500': description: InvalidIStockCollection /v3/images/{id}: get: tags: - Images summary: Get metadata for a single image by supplying one image id description: "This endpoint returns the detailed image metadata for a specified image.\n\nYou'll need an API key and access token to use this resource. \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\nare often used to build search response results. The following fields are provided for every image in your\nresult set when you include **summary_set** in your request.\n\n```\n{\n \"images\":\n [\n \"artist\",\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\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 \noften used to build a detailed view of images. The following fields are provided for every image in your \nresult set when you include **detail_set** in your request.\n\n```\n{\n \"images\":\n [\n \"allowed_use\",\n \"artist\", \n \"artist_title\", \n \"asset_family\",\n \"call_for_image\",\n \"caption\", \n \"city\",\n \"collection_code\",\n \"collection_id\", \n \"collection_name\",\n \"color_type\", \n \"copyright\", \n \"country\", \n \"credit_line\", \n \"date_created\", \n \"date_submitted\",\n \"download_sizes\", \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 \"state_province\", \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\nresolution files that are most frequently used to build a UI displaying search results. The following fields are provided\nfor every image in 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## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\n\n\n\n \"name\": \"string\",\n \"uri\": \"string\"" 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: id in: path description: An image id. For more than one image please use the /v3/images endpoint. required: true schema: type: string description: An image id. For more than one image please use the /v3/images endpoint. nullable: true - 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/ImageDetailFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' nullable: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ImagesDetailResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: ImageNotFound '500': description: InvalidIStockCollection /v3/images/{id}/downloadhistory: get: tags: - Images summary: Returns information about a customer's download history for a specific asset description: '' 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: id in: path description: An image id. required: true schema: type: string description: An image id. nullable: true - name: company_downloads in: query description: "If specified, returns the list of previously downloaded images for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false." schema: type: boolean description: "If specified, returns the list of previously downloaded images for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false." responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AssetDownloadHistoryResults' '400': description: Bad request '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: ImageNotFound '500': description: InvalidIStockCollection /v3/images/{id}/same-series: get: tags: - Images summary: Retrieve creative images from the same series description: "This endpoint will provide the list of images, if any exist, from the same series as the specified creative asset id. These images are typically from the same photo shoot. This functionality will not work for editorial assets.\n\nYou'll need an API key and access token to use this resource.\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\nsearch 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 build a \ndetailed 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 files \nthat are most frequently used to build a UI displaying search results. The following fields are provided for every image 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 \"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" 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: id in: path description: Identifies an existing image required: true schema: type: string description: Identifies an existing image nullable: true - 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/ImagesFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' 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 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ImageSearchItemSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: ImageNotFound '500': description: InvalidIStockCollection /v3/images/{id}/similar: get: tags: - Images summary: Retrieve similar images description: "This endpoint will provide a list of images that are similar to the specified asset id.\n\nYou'll need an API key and access token to use this resource.\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\nsearch 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 build a \ndetailed 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 files \nthat are most frequently used to build a UI displaying search results. The following fields are provided for every image in your result\nset when you include **display_set** in your request.\n\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" 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: id in: path description: Identifies an existing image required: true schema: type: string description: Identifies an existing image nullable: true - 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/ImagesFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.' 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 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ImageSearchItemSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: ImageNotFound '500': description: InvalidIStockCollection /v3/search/images/creative: get: tags: - Images 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: - Images 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/images/editorial: get: tags: - Images summary: Search for editorial images only description: "Use this endpoint to search our editorial stock photos, illustrations and archival images. Editorial images represent newsworthy events or illustrate matters of general interest, such as news, sport and entertainment and are generally intended for editorial use.\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.\nTo include your API token in the search request, add it to the headers as a Bearer token (example in curl):\n\n\t-H \"Authorization: Bearer \"\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 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 build 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 files that are most frequently used to build a UI displaying search results. The following fields are provided for every image in 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```" 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 collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type. style: form explode: false schema: type: array items: type: string description: Filter by collections (comma-separated list of collection codes). 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: 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: date_from in: query description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31). schema: type: string description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31). format: date-time nullable: true - name: date_to in: query description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31). schema: type: string description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31). format: date-time 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: editorial_segments in: query description: Return only events with a matching editorial segment. style: form explode: false schema: type: array items: $ref: '#/components/schemas/EditorialSegmentContract' description: Return only events with a matching editorial segment. 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: 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: event_ids in: query description: Filter based on specific events style: form explode: false schema: type: array items: type: integer format: int32 description: Filter based on specific events 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: 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/EditorialImagesFieldValues' 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/EditorialGraphicalStyle' 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_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: 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. nullable: true - name: sort_order in: query description: Select sort order of results. The default is best_match schema: $ref: '#/components/schemas/SortOrder' - name: specific_people in: query description: Return only images associated with specific people (using a comma-delimited list). style: form explode: false schema: type: array items: type: string description: Return only images associated with specific people (using a comma-delimited list). nullable: true - name: minimum_quality_rank in: query description: Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best. schema: type: integer description: Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best. format: int32 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/EditorialImageSearchFacetsFields' 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: 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: 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 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EditorialImageSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize /v3/search/images: get: tags: - Images summary: Search for both creative and editorial images - *** DEPRECATED *** description: "## _This endpoint draws from such a large diversity of content, the results will not be as relevant as when the more specific Creative or Editorial endpoints are used. Additionally, the response time for this endpoint is slower compared to that for Creative and Editorial-specific endpoints. For these reasons,_ _**it is highly recommended that those endpoints are used instead of this blended endpoint.**_\n\n\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.
\nTo include your API token in the search request, add it to the headers as a Bearer token (example in curl):\n\n\t-H \"Authorization: Bearer \"\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 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 build a detailed view of images. \nThe 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 files that are most \nfrequently used to build a UI displaying search results. The following fields are provided for every image in your result set when you include **display_set**\nin 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## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\n" 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: Provides searching based on specified collection(s). 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 hexidecimal format (e.g., #002244). Note: when specified, results will not contain editorial images.' schema: type: string description: 'Filter based on predominant color in an image. Use 6 character hexidecimal format (e.g., #002244). Note: when specified, results will not contain editorial images.' 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: event_ids in: query description: Filter based on specific events style: form explode: false schema: type: array items: type: integer format: int32 description: Filter based on specific events 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_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: fields in: query description: Specifies fields to return. Defaults to 'summary_set'. style: form explode: false schema: type: array items: $ref: '#/components/schemas/ImagesFieldValues' description: Specifies fields to return. Defaults to 'summary_set'. 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_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: 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. nullable: true - name: sort_order in: query description: Select sort order of results. The default is best_match schema: $ref: '#/components/schemas/BlendedImageSortOrder' - name: specific_people in: query description: Return only images associated with specific people (using a comma-delimited list). style: form explode: false schema: type: array items: type: string description: Return only images associated with specific people (using a comma-delimited list). nullable: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ImageSearchItemSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize 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 AffiliateSearchStyle: enum: - photography - vector type: string description: Specifies the graphical style of images desired. FacetEvent: type: object properties: id: type: integer format: int32 name: type: string nullable: true date: type: string format: date-time additionalProperties: false ImageDataResponse: type: object properties: index: type: integer format: int32 is_blocked: type: boolean preview_urls: type: array items: $ref: '#/components/schemas/PreviewUrl' description: The preview URLs for the result nullable: true url: type: string nullable: true additionalProperties: false CreativeImageSortOrder: enum: - best_match - most_popular - newest - random type: string PendingImageGenerationResponse: type: object properties: generation_request_id: type: string nullable: true additionalProperties: false 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 DownloadResponse: type: object properties: url: type: string nullable: true generated_asset_id: type: string nullable: true additionalProperties: false EditorialImageSearchResults: type: object properties: result_count: type: integer format: int32 images: type: array items: $ref: '#/components/schemas/ImageSearchItemEditorial' nullable: true related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' nullable: true additionalProperties: false EditorialSegmentContract: enum: - archival - entertainment - news - publicity - royalty - sport type: string ReferralDestination: type: object properties: site_name: type: string nullable: true uri: type: string nullable: true additionalProperties: false ImageSearchItemDisplaySize: type: object properties: is_watermarked: type: boolean name: type: string nullable: true uri: type: string nullable: true additionalProperties: false AffiliateImageSearchResponse: type: object properties: images: type: array items: $ref: '#/components/schemas/AffiliateImage' nullable: true auto_corrections: $ref: '#/components/schemas/AutoCorrections' additionalProperties: false BlendedImageSortOrder: enum: - best_match - most_popular - newest - random type: string MaxDimensions: type: object properties: height: type: integer format: int32 width: type: integer format: int32 additionalProperties: false DownloadSizeResponse: type: object properties: size_name: type: string nullable: true height: type: integer format: int32 width: type: integer format: int32 additionalProperties: false ImageDownloadRequest: type: object properties: notes: type: string description: The notes to use for the download request. Some products require this value. nullable: true project_code: type: string description: The project code to use for the download request. Some products require this value. nullable: true size_name: type: string description: The size name. Valid values are 1k or 4k. nullable: true additionalProperties: false description: Parameters for requesting an AI generation image download ImagesFieldValues: enum: - accessrestriction - 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 - editorial_segments - editorial_source - entity_details - event_ids - graphical_style - id - istock_collection - keywords - largest_downloads - license_model - max_dimensions - orientation - people - preview - product_types - quality_rank - referral_destinations - summary_set - thumb - title - uri_oembed type: string AffiliateImage: type: object properties: id: type: string nullable: true title: type: string nullable: true caption: type: string nullable: true preview_urls: $ref: '#/components/schemas/AffiliateImageUrls' destination_url: type: string nullable: true additionalProperties: false ArtistsImageSearchFieldValues: enum: - id - allowed_use - alternative_ids - artist - asset_family - asset_type - call_for_image - caption - collection_id - collection_code - collection_name - comp - comp_webp - copyright - date_created - date_submitted - detail_set - display_set - editorial_segments - event_ids - graphical_style - high_res_comp_webp - keywords - license_model - max_dimensions - mid_res_comp_webp - orientation - preview - product_types - quality_rank - referral_destinations - summary_set - thumb - title type: string CollectionsFilterType: enum: - include - exclude type: string RelatedSearch: type: object properties: phrase: type: string nullable: true url: type: string nullable: true additionalProperties: false EditorialSource: type: object properties: id: type: integer format: int32 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 AssetDownloadHistoryResults: type: object properties: id: type: string nullable: true downloads: nullable: true additionalProperties: false AssetDetail: type: object properties: id: type: string nullable: true additionalProperties: false EditorialImagesFieldValues: 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 - editorial_segments - editorial_source - event_ids - graphical_style - id - keywords - largest_downloads - license_model - max_dimensions - orientation - people - preview - product_types - quality_rank - referral_destinations - summary_set - thumb - title - uri_oembed type: string GraphicalStylesFilterType: enum: - include - exclude type: string DownloadSizesResponse: type: object properties: download_sizes: type: array items: $ref: '#/components/schemas/DownloadSizeResponse' nullable: true additionalProperties: false PremiumAccessDownloadData: type: object properties: download_notes: type: string nullable: true project_code: type: string nullable: true additionalProperties: false 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 ImageGenerationsResponse: type: object properties: generation_request_id: type: string nullable: true seed: type: integer format: int32 nullable: true results: type: array items: $ref: '#/components/schemas/ImageDataResponse' nullable: true original_asset: $ref: '#/components/schemas/AssetDetail' 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 EditorialImageSearchFacetsFields: enum: - artists - events - locations - specific_people 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 ImageSearchItemSearchResults: type: object properties: result_count: type: integer format: int32 images: type: array items: $ref: '#/components/schemas/ImageSearchItem' nullable: true related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' nullable: true additionalProperties: false ImageVariationRequest: type: object properties: product_id: type: integer description: If you have multiple Getty products, indicate which one you would like to use for this generation request format: int32 nullable: true project_code: type: string description: The project code to use for the generation request. Some products require this value. nullable: true notes: type: string description: The notes to use for the generation request. Some products require this value. nullable: true additionalProperties: false description: Payload with all images variation parameters AutoCorrections: type: object properties: phrase: type: string nullable: true additionalProperties: false DownloadFileType: enum: - eps - jpg type: string 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 PreviewUrl: type: object properties: preview_size: type: string nullable: true image_url: type: string nullable: true width: type: integer format: int32 height: type: integer format: int32 additionalProperties: false ImageSearchItem: 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 editorial_segments: type: array items: type: string nullable: true event_ids: type: array items: type: integer format: int32 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 people: type: array items: type: string nullable: true product_types: type: array items: 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 istock_licenses: type: array items: $ref: '#/components/schemas/IStockLicense' nullable: true additionalProperties: false SpecificPeople: type: object properties: id: type: integer format: int32 name: type: string nullable: true additionalProperties: false AffiliateImageUrls: type: object properties: small: type: string nullable: true small_height: type: integer format: int32 small_width: type: integer format: int32 medium: type: string nullable: true medium_height: type: integer format: int32 medium_width: type: integer format: int32 large: type: string nullable: true large_height: type: integer format: int32 large_width: type: integer format: int32 additionalProperties: false EditorialGraphicalStyle: enum: - photography - illustration - vector type: string ImageSearchItemEditorial: 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 editorial_segments: type: array items: type: string nullable: true editorial_source: $ref: '#/components/schemas/EditorialSource' event_ids: type: array items: type: integer format: int32 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 people: type: array items: type: string nullable: true product_types: type: array items: 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 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 ProductTypeForDownloads: enum: - easyaccess - editorialsubscription - imagepack - premiumaccess - royaltyfreesubscription - creditpack - aigen 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 ImagesDetailResults: type: object properties: images: nullable: true images_not_found: type: array items: type: string nullable: true additionalProperties: false ImageDetailFieldValues: enum: - allowed_use - alternative_ids - artist - artist_title - asset_family - call_for_image - caption - city - collection_code - collection_id - collection_name - color_type - comp - comp_webp - copyright - country - credit_line - date_camera_shot - date_created - date_submitted - detail_set - display_set - download_sizes - download_product - downloads - editorial_segments - editorial_source - entity_details - event_ids - graphical_style - id - is_ai_editable - istock_collection - istock_licenses - keywords - largest_downloads - license_model - links - max_dimensions - object_name - orientation - people - preview - product_types - quality_rank - referral_destinations - state_province - summary_set - thumb - title - uri_oembed type: string SortOrder: enum: - best_match - most_popular - newest - oldest - random 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: {}