Getty Images

Expands and enriches a short prompt to produce a more detailed and descriptive prompt which can then be used to generate images.

Register a client provided file for use with AIGenerator endpoints # File Registration Provide the URL for a previously uploaded file to receive an ID that can be used as the `reference_file_registration_id` in subsequent image generation requests. ## The File Registration Request The `FileRegistrationRequest` payload accepts the following parameters: | Parameter | Purpose | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `url` | Required. Specifies the location of the file. | | | `rights_claimed`| Required. Acknowledgment that client owns or has a license for this file. | | | `category` | Optional. Accepted values: `CustomerProduct`, `ImageReference`. Images to be used in `POST /beta/ai/image-generations/background-generations` must have the category set to `CustomerProduct`. | | ## Uploading the file Before calling this endpoint, a file 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 file has been uploaded, use the full URL as the `url`. - 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 file registration must be performed using the _same_ API Key.

Generates images from a prompt # AI Generator - Generate Images Use a text prompt to generate images. Use of this endpoint is restricted to clients with an AI Generation license product. ## The Image Generations Request The `ImageGenerationsRequest` payload to be posted contains the required `prompt` as well as some other optional parameters: | Parameter | Purpose | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `prompt` _Required_ | The primary text used for the generation of the images. | | `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. | | `aspect_ratio` | The "width:height" aspect ratio of the resultant images. Must be one of: `1:1`, `3:4`, `4:3`, `9:16`, or `16:9` | | `media_type` | Media type of the results: `photography` or `illustration` | | `mood` | Can be `black_and_white`, `warm`, `cool`, `natural`, `vivid`, `dramatic`, or `bold` | ## 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.

Add a background to a reference image # AI Generator - Background Generation Background Generation allows the client application to provide a `reference_file_registration_id` as a reference for creating new AI-generated product photos. Our technology will generate new background content behind the image based on the prompt and other parameters submitted with the request. The padding values are used to position the product on the canvas. Use of this endpoint may result in the deduction of a credit depending on the terms of your license. ## The Background Generation Request The `BackgroundGenerationRequest` payload requires a reference image (`reference_file_registration_id`) and `prompt` and accepts the following parameters: | Parameter | Purpose | |---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_file_registration_id` _Required_ | Registered file id of the image being used as a reference. The `CustomerProduct` category **must** be used when registering the file. | | `prompt` | The primary text used for refined portion of the images. | | `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. | | `left_percentage` | Percentage of padding to add to the left side of the item in the image. Default is 0. | | `right_percentage` | Percentage of padding to add to the right side of the item in the image. Default is 0. | | `top_percentage` | Percentage of padding to add to the top side of the item in the image. Default is 0. | | `bottom_percentage` | Percentage of padding to add to the bottom side of the item in the image. Default is 0. | | `background_file_registration_id` | Optional registered file id for use in influencing the generation of the background. The `ImageReference` category **must** be used when registering the file. | | `background_asset_id` | Optional asset id for use in influencing the generation of the background. | | `background_reference_generation` | Optional reference to a previously generated image for use in influencing the background generation. | | `background_reference_adherence` | Optional value to control how closely the AI follows your reference image. Accepted values are `flexible` and `strong`. Use flexible to focus on visual balance, or strong to preserve more of the reference image's details. | ## 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.

Remove a background # AI Generator - Background Removal Use of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. When downloading an image generated using a `reference_asset_id`, a traditional license product, such as Premium Access, that provides download access to the original creative image is required. Downloading an image generated using a `reference_asset_id` also requires the client to first download the original image. ## The Background Removal Request The `BackgroundRemovalRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following optional parameters: | Parameter | Purpose | |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_asset_id`| Creative image id to modify. | | `reference_generation`| Generation details of image to modify. | | | `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.

Replace the background of an existing image # AI Generator - Background Replacement Background Replacement allows the client application to change the background of an existing Getty Images creative image or an existing generated image through the use of prompt text or color information. Four images will be generated when prompt text is submitted, while one image will be generated when color information is submitted. Use of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. When generating new images using a reference_asset_id, the reference image must first be licensed (downloaded) through a traditional license product such as Premium Access before the generated image can be downloaded.. ## The Background Replacement Request The BackgroundReplacement Request payload requires one, and only one, reference image (reference_asset_id or reference_generation) and accepts the following optional parameters: | Parameter | Purpose | |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_asset_id` | Creative image ID of the image being used as a reference. | | `reference_generation` | Generation details of the image being used as a reference. | | `prompt` | The primary text used for the generation of the images. | | `negative_prompt` | Concepts to _exclude_ from the result. | | `background_color` | Color information to use for the background replacement. The format is hexadecimal [web colors](https://en.wikipedia.org/wiki/Web_colors), _e.g. #0099CC_. | | `media_type` | Media type of the results: `photography` or `illustration` | | `negative_prompt` | Concepts to _exclude_ from the result. | | `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`). | | `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. | | `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. |

Extend an image # AI Generator - Image Extension Use text prompts and numerical values to extend the content beyond the borders of an image from the Getty Images creative library (excluding certain vectors) or a previously generated image. Use of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. To download an extended image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required. Lastly, downloading an extended image requires the client to first download the original image. Extension involves adding content to one or more sides of an image by specifying a percentage by which you want the image extended. This means that the aspect ratio of the generated images will differ from the original unless the same value is specified for all four sides. Additionally, the pixel dimensions on the longest side will remain the same - 612px for the images provided in this endpoint's response, 1024px and 4096px on the images retrieved through the download process. ## The Extend Request The `ExtendRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`) and requires at least one percentage to be greater than zero (`left_percentage`, `right_percentage`, `top_percentage`, or `bottom_percentage`) and accepts the following optional parameters: | Parameter | Purpose | |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_asset_id`| Creative image id to modify. | | `reference_generation`| Generation details of image to modify. | | `prompt` | The primary text used for the extended portion of the images. | | `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. | | `left_percentage` | Percentage to add to the left side of the image. This must be a float that is equal to or greater than 0. Default is 0. | | `right_percentage` | Percentage to add to the right side of the image. This must be a float that is equal to or greater than 0. Default is 0. | | `top_percentage` | Percentage to add to the top side of the image. This must be a float that is equal to or greater than 0. Default is 0. | | `bottom_percentage` | Percentage to add to the bottom side of the image. This must be a float that is equal to or greater than 0. Default is 0. | ## 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.

Get variations on a generated image # 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.

Influence the color of generated images using a reference image # AI Generator - Influence Color By Image Influence Color By Image allows the client application to provide an existing Getty Images creative image or an existing generated image, along with prompt text, as a reference for generating new images. The generated images are influenced by the color palette, tone and location of colors within the reference image. Use of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. When generating new images using using a `reference_asset_id`, the reference image must first be licensed (downloaded) through a traditional license product such as Premium Access before the generated image can be downloaded.. ## The Influence Color By Image Request The `InfluenceColorByImageRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`, or `reference_file_registration_id`) and accepts the following optional parameters: | Parameter | Purpose | | -------------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_asset_id` | Creative image ID of the image being used as a reference. | | `reference_generation` | Generation details of the image being used as a reference. | | `reference_file_registration_id` | Registered file id of the image being used as a reference. The `ImageReference` category **must** be used when registering the file. | | `prompt` _Required_ | The primary text used for the generation of the images. | | `aspect_ratio` | The "width:height" aspect ratio of the resultant images. Must be one of: `1:1`, `3:4`, `4:3`, `9:16`, or `16:9` | | `media_type` | Media type of the results: `photography` or `illustration` | | `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.

Influence the composition of generated images using a reference image # AI Generator - Influence Composition By Image Influence Composition By Image allows the client application to provide an existing Getty Images creative image or an existing generated image, along with prompt text, as a reference for generating new images. The generated images are influenced by the compositional elements like pose, object location and object depth within the reference image. Use of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. When generating new images using using a `reference_asset_id`, the reference image must first be licensed (downloaded) through a traditional license product such as Premium Access before the generated image can be downloaded.. ## The Influence Composition By Image Request The `InfluenceCompositionByImageRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`, or `reference_file_registration_id`) and accepts the following optional parameters: | Parameter | Purpose | | -------------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_asset_id` | Creative image ID of the image being used as a reference. | | `reference_generation` | Generation details of the image being used as a reference. | | `reference_file_registration_id` | Registered file id of the image being used as a reference. The `ImageReference` category **must** be used when registering the file. | | `prompt` _Required_ | The primary text used for the generation of the images. | | `aspect_ratio` | The "width:height" aspect ratio of the resultant images. Must be one of: `1:1`, `3:4`, `4:3`, `9:16`, or `16:9` | | `media_type` | Media type of the results: `photography` or `illustration` | | `mood` | Can be `black_and_white`, `warm`, `cool`, `natural`, `vivid`, `dramatic`, or `bold` | | `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.

Refine an image # AI Generator - Image Refining Use a mask image and text prompts to modify content in an image from the Getty Images creative library (excluding certain vectors) or a previously generated image. Use of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. To download a refined image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required. Lastly, downloading a refined image requires the client to first download the original image. ## The Refine Request The `RefineRequest` payload one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following parameters: | Parameter | Purpose | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_asset_id`| Creative image id to modify. | | `reference_generation`| Generation details of image to modify. | | `prompt` | Required. The primary text used for refined portion of the images. | | `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. | | `mask_url` | Specifies the location of the mask. | | ## Uploading mask image When including a mask_url in the request, a mask in JPEG format must first 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 mask has been uploaded, use the full URL as the `mask_url`. - 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 refining must be performed using the _same_ API Key. ## 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.

Re-download a previously downloaded item # Re-download AI Generated media Re-download previously downloaded AI generated media. ## `ReDownloadRequest` details | Parameter | Purpose | |---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | `generated_asset_id` _Required_ | The generated asset identifier to re-download. Can be retrieved from previously downloaded assets (`GET /v3/downloads`) | | `product_id` _Required_ | The product to use to re-download. Can be retrieved from products (`GET /v3/products`) | | `size_name` _Required_ | The size to re-download. Valid values are `1k` and `4k` | | `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. |

Endpoint for acquiring extended licenses with iStock credits for an asset.

Create a new board

Add a comment to an asset on the specified board.

Add a comment to a board

Download an image Use this endpoint to generate download URLs and related data for images you are authorized to download. Most 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. The download limit for a given download period is covered in your product agreement established with Getty Images. You'll need an API key and an access token generated through the [Client Credentials grant](https://developers.gettyimages.com/docs/authorization/#client-credentials-grant) or [Authorization Code grant](https://developers.gettyimages.com/docs/authorization/#authorization-code-grant) to use this resource. ## Auto Downloads The `auto_download` request query parameter specifies whether to automatically download the image. If 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). Client Request: ``` https://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=true ``` Server Response: Your 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). ``` HTTP/1.1 303 See Other Location: https://delivery.gettyimages.com/... ``` If 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. Client Request: ``` https://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=false ``` Server Response: ``` HTTP/1.1 200 OK { "uri": "https://delivery.gettyimages.com/..." } ``` ## Downloading Via the Returned URI Your 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). The URI returned by this call should be considered opaque and the format could change at any time. In order to get the filename, length or file type, the response headers must be inspected. An example response follows: ``` content-length: 33959979 content-type: image/jpeg content-disposition: attachment; filename=GettyImages-1167612765.jpg ``` The `content-disposition` header must be parsed to get a usable filename. ## Download URI expiration Download URIs are _**only valid for 24 hours**_, starting from the moment they are returned from this call.

Download a video Use this endpoint to generate download URLs and related data for videos you are authorized to download. Most 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. The download limit for a given download period is covered in your product agreement established with Getty Images. You'll need an API key and an access token generated through the [Client Credentials grant](https://developers.gettyimages.com/docs/authorization/#client-credentials-grant) or [Authorization Code grant](https://developers.gettyimages.com/docs/authorization/#authorization-code-grant) to use this resource. ## Auto Downloads The `auto_download` request query parameter specifies whether to automatically download the video. If 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). Client Request: ``` https://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=true ``` Server Response: Your 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). ``` HTTP/1.1 303 See Other Location: https://delivery.gettyimages.com/... ``` If 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 video. Client Request: ``` https://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=false ``` Server Response: ``` HTTP/1.1 200 OK { "uri": "https://delivery.gettyimages.com/..." } ``` ## Downloading Via the Returned URI Your 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). The URI returned by this call should be considered opaque and the format could change at any time. In order to get the filename, length or file type, the response headers must be inspected. An example response follows: ``` content-length: 283925783 content-type: video/quicktime content-disposition: attachment; filename=GettyImages-690773579.mov ``` The `content-disposition` header must be parsed to get a usable filename. ## Download URI expiration Download URIs are _**only valid for 24 hours**_, starting from the moment they are returned from this call.

Begin the download process # 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. | | `product_id` | The product id to download against. Only required when the customer has more than one agreement. | ## 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.

Get asset change notifications. # Asset Changes Get notifications about new, updated or deleted assets for a specific channel. ## Quickstart You'll need an API key and an access token to use this resource. Maximum batch size is 2200. Change-sets must be confirmed before a new batch of notifications can be retrieved from this endpoint. Use the DELETE asset-changes/change-sets/{change-set-id} endpoint to confirm reciept of these notifications. Values returned for asset_type include Image, Film, and null. Values returned for asset_lifecycle include New, Update, and Delete. Delete notifications may be provided for asset ids that have not previously been received as New or Update notifications. Delete notifications may return null for the asset_type. Delete notifications for videos and images are often duplicated across each other's channels. For example, a delete notification for a video may be duplicated in a channel for image messages. If there are no notifications in the channel an empty response body will be returned. Notifications older than 14 days will be removed from partner channels.

Update a board

Add assets to a board

Add an asset to a board

Upload image for use by the search creative images/videos operations

Report usage of assets via a batch format. # Report Usage Use this endpoint to report the usages of a set of assets. The count of assets submitted in a single batch to this endpoint is limited to 1000. Note that all asset Ids specified must be valid or the operation will fail causing no usages to be recorded. In this case, you will need to remove the invalid asset Ids from the query request and re-submit the query. ## Quickstart You'll need an API key and an access token to use this resource. _Note_: Date of use can be in any unambiguous date format.