openapi: 3.2.0 info: title: Getty Images AI Generator API version: '3' security: - Api-Key: [] - OAuth2: [] tags: - name: AiGenerator paths: /v3/ai/image-generations: post: tags: - AiGenerator summary: Generates images from a prompt description: '# 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.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ImageGenerationsRequest' text/json: schema: $ref: '#/components/schemas/ImageGenerationsRequest' application/*+json: schema: $ref: '#/components/schemas/ImageGenerationsRequest' responses: '202': description: Returns the request ID content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '400': description: The request was invalid '403': description: Product quota exceeded '409': description: ConcurrencyConflict '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerations x-operation-id-source: derived /v3/ai/image-generations/{generationRequestId}: get: tags: - AiGenerator summary: Get generated images from a previous generation request description: '# AI Generator - Get Generated Images Gets a previously generated set of images. This endpoint is used after a call to `POST v3/ai/image-generations`, passing the `id` value from the result of that call. ## Fulfilled and Pending Results Like the `POST v3/ai/image-generations` endpoint, the result of calling this endpoint will be either: - `HTTP 200 OK` with the generated images'' URLs and a generation request `id` value - `HTTP 202 Accepted` with the payload only containing a generation request `id` value `HTTP 202 Accepted` is returned in the case where the generation of images 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. ## 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 schema: type: string responses: '202': description: Returns the request ID for a pending request content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '200': description: Returns the result of a request to generate images content: application/json: schema: $ref: '#/components/schemas/ImageGenerationsResponse' '404': description: The request ID was not found '409': description: ConcurrencyConflict '400': description: InvalidProduct '403': description: NoProducts '429': description: TooManyConcurrentGenerations '410': description: GenerationRequestGone operationId: getV3AiImageGenerationsByGenerationRequestId x-operation-id-source: derived /v3/ai/image-generations/{generationRequestId}/images/{index}/variations: post: tags: - AiGenerator 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 schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true 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: '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: The request was invalid '403': description: Product quota exceeded '404': description: Either the generation id does not exist, the index is incorrect, or the generation is still pending '409': description: ConcurrencyConflict '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsByGenerationRequestIdImagesByIndexVariations x-operation-id-source: derived /v3/ai/file-registrations: post: tags: - AiGenerator summary: Register a client provided file for use with AIGenerator endpoints description: '# 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.' requestBody: content: application/json: schema: $ref: '#/components/schemas/FileRegistrationRequest' text/json: schema: $ref: '#/components/schemas/FileRegistrationRequest' application/*+json: schema: $ref: '#/components/schemas/FileRegistrationRequest' responses: '200': description: Returns the response content: application/json: schema: $ref: '#/components/schemas/FileRegistrationResponse' '400': description: The request was invalid '403': description: Not authorized operationId: postV3AiFileRegistrations x-operation-id-source: derived get: tags: - AiGenerator parameters: - name: page in: query description: The page number of results. Default is 1. schema: type: integer format: int32 - name: page_size in: query description: The page size of results. Default is 30. schema: type: integer format: int32 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetFileRegistrationsResponse' '403': description: NotAuthorized summary: Get ai file registrations x-summary-source: derived operationId: getV3AiFileRegistrations x-operation-id-source: derived /v3/ai/file-registrations/{fileRegistrationId}: get: tags: - AiGenerator summary: Get details on a registered file description: '# Get Registered File Details Gets details for a registered file. This endpoint is used after a call to `POST beta/ai/file-registrations`, passing the `id` value from the result of that call.' parameters: - name: fileRegistrationId in: path description: The id from a previous request to register a file required: true schema: type: string responses: '200': description: Returns the response content: application/json: schema: $ref: '#/components/schemas/GetFileRegistrationResponse' '400': description: The request was invalid '403': description: Not authorized '404': description: FileRegistrationIdNotFound operationId: getV3AiFileRegistrationsByFileRegistrationId x-operation-id-source: derived delete: tags: - AiGenerator summary: Archives a registered file parameters: - name: fileRegistrationId in: path description: '' required: true schema: type: string responses: '200': description: OK '204': description: The file was successfully archived '404': description: The file registration id does not exist '403': description: Not authorized operationId: deleteV3AiFileRegistrationsByFileRegistrationId x-operation-id-source: derived /v3/ai/image-generations/refine: post: tags: - AiGenerator summary: Refine an image description: '# 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.' requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/RefineRequest' text/json: schema: $ref: '#/components/schemas/RefineRequest' application/*+json: schema: $ref: '#/components/schemas/RefineRequest' responses: '202': description: Returns the request ID for a pending request to refine an image content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '403': description: Product quota exceeded '404': description: Image not found '409': description: ConcurrencyConflict '400': description: InvalidProduct '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsRefine x-operation-id-source: derived /v3/ai/image-generations/extend: post: tags: - AiGenerator summary: Extend an image description: '# 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.' requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/ExtendRequest' text/json: schema: $ref: '#/components/schemas/ExtendRequest' application/*+json: schema: $ref: '#/components/schemas/ExtendRequest' responses: '202': description: Returns the request ID for a pending request to extend an image content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '403': description: Product quota exceeded '404': description: Image not found '409': description: ConcurrencyConflict '400': description: InvalidProduct '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsExtend x-operation-id-source: derived /v3/ai/image-generations/background-removal: post: tags: - AiGenerator summary: Remove a background description: '# 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.' requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/BackgroundRemovalRequest' text/json: schema: $ref: '#/components/schemas/BackgroundRemovalRequest' application/*+json: schema: $ref: '#/components/schemas/BackgroundRemovalRequest' responses: '202': description: Returns the request ID for a pending request to extend an image content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '400': description: The request was invalid '403': description: Product quota exceeded '404': description: Image not found '409': description: ConcurrencyConflict '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsBackgroundRemoval x-operation-id-source: derived /v3/ai/image-generations/object-removal: post: tags: - AiGenerator summary: Remove object(s) description: '# AI Generator - Object Removal Use a mask image to remove object content in a previously generated image or a previously licensed image from the Getty Images creative library. 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 Remove Object Request The `RemoveObjectRequest` payload accepts the following parameters. One, and only one, of either `reference_asset_id` or `reference_generation` must be used. Omitting or including both are invalid. | Parameter | Purpose | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_asset_id` | Creative image id to modify. | | `reference_generation` | Generation details of image to modify. | | | `mask_url` | **Required**: Specifies the location of the mask. | | `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` | This is for use by Getty Images customers only (not iStock). If your Getty Images Generative AI product requires project codes, use of this parameter is **required**. Otherwise, this parameter **must be excluded** from the request. The products endpoint (`GET /v3/products`) provides this information. | ## Uploading mask image Before calling the endpoint, a mask 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 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 object removal 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.' requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/RemoveObjectRequest' text/json: schema: $ref: '#/components/schemas/RemoveObjectRequest' application/*+json: schema: $ref: '#/components/schemas/RemoveObjectRequest' responses: '202': description: Returns the request ID for a pending request to refine images content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '403': description: Product quota exceeded '404': description: Either the generation id does not exist, the index is incorrect, or the generation is still pending '409': description: ConcurrencyConflict '400': description: InvalidProduct '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsObjectRemoval x-operation-id-source: derived /v3/ai/image-generations/background-replacement: post: tags: - AiGenerator summary: Replace the background of an existing image description: '# 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, _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. |' requestBody: content: application/json: schema: $ref: '#/components/schemas/ReplaceBackgroundRequest' text/json: schema: $ref: '#/components/schemas/ReplaceBackgroundRequest' application/*+json: schema: $ref: '#/components/schemas/ReplaceBackgroundRequest' responses: '202': description: Returns the request ID for a pending request to replace a background content: text/plain: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' text/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '409': description: ConcurrencyConflict '403': description: NotAuthorized '400': description: InvalidProduct '404': description: GenerationRequestIdNotFound '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsBackgroundReplacement x-operation-id-source: derived /v3/ai/image-generations/influence-color-by-image: post: tags: - AiGenerator summary: Influence the color of generated images using a reference image description: '# 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.' requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/InfluenceColorByImageRequest' text/json: schema: $ref: '#/components/schemas/InfluenceColorByImageRequest' application/*+json: schema: $ref: '#/components/schemas/InfluenceColorByImageRequest' responses: '202': description: Returns the request ID for a pending request to extend an image content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '400': description: The request was invalid '403': description: Product quota exceeded '404': description: Image not found '409': description: ConcurrencyConflict '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsInfluenceColorByImage x-operation-id-source: derived /v3/ai/image-generations/influence-composition-by-image: post: tags: - AiGenerator summary: Influence the composition of generated images using a reference image description: '# 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.' requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/InfluenceCompositionByImageRequest' text/json: schema: $ref: '#/components/schemas/InfluenceCompositionByImageRequest' application/*+json: schema: $ref: '#/components/schemas/InfluenceCompositionByImageRequest' responses: '202': description: Returns the request ID for a pending request to extend an image content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '403': description: Product quota exceeded '404': description: Image not found '409': description: ConcurrencyConflict '400': description: InvalidProduct '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsInfluenceCompositionByImage x-operation-id-source: derived /v3/ai/image-generations/background-generations: post: tags: - AiGenerator summary: Add a background to a reference image description: '# 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.' requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/BackgroundGenerationRequest' text/json: schema: $ref: '#/components/schemas/BackgroundGenerationRequest' application/*+json: schema: $ref: '#/components/schemas/BackgroundGenerationRequest' responses: '202': description: Returns the request ID for a pending request content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '403': description: Product quota exceeded '404': description: Image not found '409': description: ConcurrencyConflict '400': description: InvalidProduct '429': description: TooManyConcurrentGenerations operationId: postV3AiImageGenerationsBackgroundGenerations x-operation-id-source: derived /v3/ai/generation-history: get: tags: - AiGenerator summary: Retrieve history of AI generations description: '# AI Generator - Generation History Get the history of AI generation requests.' parameters: - name: date_start in: query description: "If included, limits the results to those generation requests made on or after date_start. Both dates and datetimes are supported. \nDates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. \nDatetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ." schema: type: string format: date-time - name: date_end in: query description: "If included, limits the results to those generation requests made on or before date_end. Both dates and datetimes are supported. \nDates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. \nDatetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ." schema: type: string format: date-time - name: media_type in: query description: If included, limits the results to those generation requests made for the given media type. schema: $ref: '#/components/schemas/MediaType' - name: page_size in: query description: The page size of results. Default is 30. schema: maximum: 1000 minimum: 1 type: integer format: int32 - name: page in: query description: The page number of results. Default is 1. schema: maximum: 2147483647 minimum: 1 type: integer format: int32 - name: product_ids in: query description: If included, limits the results to only those requests made against the indicated products. schema: type: array items: type: integer format: int32 - name: company_generations in: query description: "If `true`, returns the list of previously downloaded images for all users in\n your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for\n more information. Default is `false`." schema: type: boolean default: false responses: '200': description: Returns the history of AI generations content: text/plain: schema: $ref: '#/components/schemas/GenerationHistoryResponse' application/json: schema: $ref: '#/components/schemas/GenerationHistoryResponse' text/json: schema: $ref: '#/components/schemas/GenerationHistoryResponse' '403': description: Company generations were requested but your account is not configured for access. '409': description: ConcurrencyConflict operationId: getV3AiGenerationHistory x-operation-id-source: derived /v3/ai/generation-history/{generationRequestId}: get: tags: - AiGenerator summary: Retrieve history item for an individual generation request parameters: - name: generationRequestId in: path description: The ID from a previous request to generate images required: true schema: type: string responses: '200': description: Returns the history item for the request content: text/plain: schema: $ref: '#/components/schemas/GenerationHistoryItemResponse' application/json: schema: $ref: '#/components/schemas/GenerationHistoryItemResponse' text/json: schema: $ref: '#/components/schemas/GenerationHistoryItemResponse' '404': description: The request ID was not found '409': description: ConcurrencyConflict '403': description: NotAuthorized operationId: getV3AiGenerationHistoryByGenerationRequestId x-operation-id-source: derived /v3/ai/image-generations/{generationRequestId}/images/{index}/download-sizes: get: tags: - AiGenerator 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 schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true schema: type: integer format: int32 responses: '200': description: Returns the result of a request content: application/json: schema: $ref: '#/components/schemas/DownloadSizesResponse' '404': description: Either the generation id does not exist, the index is incorrect, or the generation is still pending '409': description: ConcurrencyConflict '403': description: NotAuthorized '400': description: InvalidProduct '410': description: GenerationRequestGone '429': description: DailyRequestLimitExceeded operationId: getV3AiImageGenerationsByGenerationRequestIdImagesByIndexDownloadSizes x-operation-id-source: derived /v3/ai/image-generations/{generationRequestId}/images/{index}/download: put: tags: - AiGenerator 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. | | `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.' parameters: - name: generationRequestId in: path description: The ID from a previous request to generate images required: true schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true 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: '202': description: Download request was successful but is pending '409': description: A download is already in progress for the given `generationRequestId` and `index`. '403': description: NotAuthorized '400': description: InvalidProduct '410': description: GenerationRequestGone '404': description: GenerationRequestIdNotFound '429': description: DailyRequestLimitExceeded operationId: putV3AiImageGenerationsByGenerationRequestIdImagesByIndexDownload x-operation-id-source: derived get: tags: - AiGenerator summary: Once the download process has started, this endpoint can be used to check the… 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 schema: type: string - name: index in: path description: The index of the image from the specific images generation required: true schema: type: integer format: int32 responses: '202': description: Download request was successful put is pending '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' '409': description: ConcurrencyConflict '403': description: NotAuthorized '400': description: InvalidProduct '410': description: GenerationRequestGone '404': description: GenerationRequestIdNotFound '429': description: DailyRequestLimitExceeded operationId: getV3AiImageGenerationsByGenerationRequestIdImagesByIndexDownload x-operation-id-source: derived /v3/ai/redownloads: post: tags: - AiGenerator summary: Re-download a previously downloaded item description: '# 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. |' requestBody: content: application/json: schema: $ref: '#/components/schemas/ReDownloadRequest' text/json: schema: $ref: '#/components/schemas/ReDownloadRequest' application/*+json: schema: $ref: '#/components/schemas/ReDownloadRequest' responses: '200': description: Returns the re-download response content: application/json: schema: $ref: '#/components/schemas/DownloadResponse' '400': description: The request was invalid '404': description: Could not find source generated_asset_id '403': description: Product is not active or quota exceeded '409': description: ConcurrencyConflict '410': description: GenerationRequestGone '429': description: DailyRequestLimitExceeded operationId: postV3AiRedownloads x-operation-id-source: derived /v3/ai/enhance-prompt: post: tags: - AiGenerator summary: Expands and enriches a short prompt to produce a more detailed and descriptive… requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/PromptEnhancementRequest' text/json: schema: $ref: '#/components/schemas/PromptEnhancementRequest' application/*+json: schema: $ref: '#/components/schemas/PromptEnhancementRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PromptEnhancementResponse' '400': description: PromptEnhancementFailed operationId: postV3AiEnhancePrompt x-operation-id-source: derived components: schemas: PreviewUrl: type: object properties: preview_size: type: - string - 'null' image_url: type: - string - 'null' width: type: integer format: int32 height: type: integer format: int32 additionalProperties: false ReferenceGeneration: type: object properties: generation_request_id: type: - string - 'null' description: The id from a previous request to generate images. index: type: integer description: The index of the image from the specific images generation. format: int32 additionalProperties: false ImageDownloadRequest: type: object properties: notes: type: - string - 'null' description: The notes to use for the download request. Some products require this value. project_code: type: - string - 'null' description: The project code to use for the download request. Some products require this value. size_name: type: - string - 'null' description: The size name. Valid values are 1k or 4k. product_id: type: - integer - 'null' description: The product id to download against. Only required when the customer has more than one agreement. format: int32 additionalProperties: false description: Parameters for requesting an AI generation image download Category: enum: - ImageReference - CustomerProduct type: string ImageVariationRequest: type: object properties: product_id: type: - integer - 'null' description: If you have multiple Getty products, indicate which one you would like to use for this generation request format: int32 project_code: type: - string - 'null' description: The project code to use for the generation request. Some products require this value. notes: type: - string - 'null' description: The notes to use for the generation request. Some products require this value. additionalProperties: false description: Payload with all images variation parameters GetFileRegistrationResponse: type: object properties: id: type: - string - 'null' preview_urls: type: - array - 'null' items: $ref: '#/components/schemas/PreviewUrl' additionalProperties: false FileRegistration: required: - id - preview_urls type: object properties: id: type: - string - 'null' date_created: type: string format: date-time preview_urls: type: - array - 'null' items: $ref: '#/components/schemas/PreviewUrl' additionalProperties: false PromptEnhancementResponse: required: - enhanced_prompt type: object properties: enhanced_prompt: type: - string - 'null' additionalProperties: false ExtendRequest: type: object properties: reference_asset_id: type: - string - 'null' reference_generation: $ref: '#/components/schemas/ReferenceGeneration' prompt: type: - string - 'null' product_id: type: - integer - 'null' format: int32 project_code: type: - string - 'null' notes: type: - string - 'null' left_percentage: type: number format: float right_percentage: type: number format: float top_percentage: type: number format: float bottom_percentage: type: number format: float additionalProperties: false ImageGenerationsRequest: type: object properties: prompt: type: - string - 'null' description: The only required parameter, this is the primary text used for the generation of the images. aspect_ratio: type: - string - 'null' description: Aspect ratio of the result images. Must be one of 1:1, 3:4, 4:3, 9:16, or 16:9 media_type: $ref: '#/components/schemas/MediaType' mood: $ref: '#/components/schemas/Mood' product_id: type: - integer - 'null' description: If you have multiple Getty products, indicate which one you would like to use for this generation request format: int32 project_code: type: - string - 'null' description: The project code to use for the generation request. Some products require this value. notes: type: - string - 'null' description: The notes to use for the generation request. Some products require this value. additionalProperties: false description: Payload with all generation request parameters FileRegistrationResponse: type: object properties: id: type: - string - 'null' additionalProperties: false SourceGenerationRequest: type: object properties: source_generation_request_id: type: - string - 'null' source_generation_result_index: type: integer format: int32 additionalProperties: false BackgroundRemovalRequest: type: object properties: reference_asset_id: type: - string - 'null' description: Asset Id to modify. reference_generation: $ref: '#/components/schemas/ReferenceGeneration' product_id: type: - integer - 'null' description: If you have multiple Getty products, indicate which one you would like to use for this refine request format: int32 project_code: type: - string - 'null' description: The project code to use for the request. Some products require this value. notes: type: - string - 'null' description: The notes to use for the request. Some products require this value. additionalProperties: false description: Remove a background DownloadSizeResponse: type: object properties: size_name: type: - string - 'null' height: type: integer format: int32 width: type: integer format: int32 additionalProperties: false GenerationHistoryResponse: type: object properties: generations: type: - array - 'null' items: $ref: '#/components/schemas/GenerationHistoryItemResponse' description: Current page of generations result_count: type: integer description: The total count of results, ignoring paging format: int32 additionalProperties: false description: Full generation history response ReplaceBackgroundRequest: type: object properties: prompt: type: - string - 'null' reference_asset_id: type: - string - 'null' reference_generation: $ref: '#/components/schemas/ReferenceGeneration' product_id: type: - integer - 'null' format: int32 media_type: $ref: '#/components/schemas/MediaType' negative_prompt: type: - string - 'null' background_color: type: - string - 'null' project_code: type: - string - 'null' notes: type: - string - 'null' additionalProperties: false FileRegistrationRequest: type: object properties: url: type: - string - 'null' description: The location of the file. rights_claimed: type: - boolean - 'null' description: Acknowledgment of ownership or licensing of file. category: $ref: '#/components/schemas/Category' additionalProperties: false description: Parameters for registering a file InfluenceCompositionByImageRequest: type: object properties: reference_asset_id: type: - string - 'null' description: Asset Id to modify. reference_generation: $ref: '#/components/schemas/ReferenceGeneration' reference_file_registration_id: type: - string - 'null' description: File Id to modify. prompt: type: - string - 'null' description: This is the primary text used for refining the images. media_type: $ref: '#/components/schemas/MediaType' mood: $ref: '#/components/schemas/Mood' product_id: type: - integer - 'null' description: If you have multiple Getty products, indicate which one you would like to use for this refine request format: int32 project_code: type: - string - 'null' description: The project code to use for the request. Some products require this value. notes: type: - string - 'null' description: The notes to use for the request. Some products require this value. aspect_ratio: type: - string - 'null' description: Aspect ratio of the result images. Must be one of 1:1, 3:4, 4:3, 9:16, or 16:9 additionalProperties: false description: Payload with all influence composition by image parameters ImageGenerationsResponse: type: object properties: generation_request_id: type: - string - 'null' seed: type: - integer - 'null' format: int32 results: type: - array - 'null' items: $ref: '#/components/schemas/ImageDataResponse' original_asset: $ref: '#/components/schemas/AssetDetail' additionalProperties: false ReferenceAdherence: enum: - flexible - strong type: string ReDownloadRequest: type: object properties: generated_asset_id: type: - string - 'null' description: The identifier of the previously-downloaded generated asset. product_id: type: integer description: The product ID to use for the download. format: int32 size_name: type: - string - 'null' description: The size name. Valid values are 1k or 4k. project_code: type: - string - 'null' description: The project code to use for the download request. Some products require this value. notes: type: - string - 'null' description: The notes to use for the download request. Some products require this value. additionalProperties: false description: Parameters for requesting an AI generation re-download RefineRequest: required: - prompt type: object properties: reference_asset_id: type: - string - 'null' reference_generation: $ref: '#/components/schemas/ReferenceGeneration' prompt: minLength: 1 type: string product_id: type: - integer - 'null' format: int32 project_code: type: - string - 'null' notes: type: - string - 'null' mask_url: type: - string - 'null' additionalProperties: false DownloadResponse: type: object properties: url: type: - string - 'null' generated_asset_id: type: - string - 'null' additionalProperties: false ImageDataResponse: required: - url type: object properties: index: type: integer format: int32 is_blocked: type: boolean preview_urls: type: - array - 'null' items: $ref: '#/components/schemas/PreviewUrl' description: The preview URLs for the result url: type: - string - 'null' additionalProperties: false GenerationType: enum: - text_to_image - variation - extend - refine - background_removal - influence_color_by_image - influence_composition_by_image - object_removal - influence_outline_by_image - background_generation type: string RemoveObjectRequest: type: object properties: reference_asset_id: type: - string - 'null' description: Asset Id to modify. reference_generation: $ref: '#/components/schemas/ReferenceGeneration' product_id: type: - integer - 'null' description: If you have multiple Getty products, indicate which one you would like to use for this refine request format: int32 project_code: type: - string - 'null' description: The project code to use for the request. Some products require this value. notes: type: - string - 'null' description: The notes to use for the request. Some products require this value. mask_url: type: - string - 'null' description: The location of the mask. additionalProperties: false description: Payload with all parameters for removing objects from an image GenerationHistoryItemResponse: type: object properties: generation_request_id: type: - string - 'null' description: The identifier for the request seed: type: - integer - 'null' format: int32 generation_date: type: string description: '' format: date-time product_revoked_date: type: - string - 'null' description: If the the product against which the generation was made has been revoked, this is the date of that revocation. format: date-time prompt: type: - string - 'null' description: The prompt that was used for the request negative_prompt: type: - string - 'null' description: The negative prompt (if any) that was used for the request product_id: type: integer description: '' format: int32 notes: type: - string - 'null' description: '' project_code: type: - string - 'null' description: '' generation_type: $ref: '#/components/schemas/GenerationType' generation_options: $ref: '#/components/schemas/GenerationOptions' source_generation_request: $ref: '#/components/schemas/SourceGenerationRequest' original_asset: $ref: '#/components/schemas/AssetDetail' results: type: - array - 'null' items: $ref: '#/components/schemas/GenerationHistoryResult' description: '' user: $ref: '#/components/schemas/User' additionalProperties: false description: Detail on a specific historical generation User: type: object properties: username: type: - string - 'null' first_name: type: - string - 'null' middle_name: type: - string - 'null' last_name: type: - string - 'null' additionalProperties: false AssetDetail: type: object properties: id: type: - string - 'null' additionalProperties: false MediaType: enum: - photography - illustration type: string DownloadSizesResponse: type: object properties: download_sizes: type: - array - 'null' items: $ref: '#/components/schemas/DownloadSizeResponse' additionalProperties: false GenerationHistoryResult: type: object properties: index: type: integer description: The index of the result from the original generation format: int32 is_blocked: type: boolean description: If `true` the result was blocked due to AI generation policy preview_urls: type: - array - 'null' items: $ref: '#/components/schemas/PreviewUrl' description: The preview URLs for the result additionalProperties: false description: Individual generated result from a given generation request/response PendingImageGenerationResponse: type: object properties: generation_request_id: type: - string - 'null' additionalProperties: false InfluenceColorByImageRequest: type: object properties: reference_asset_id: type: - string - 'null' description: Asset Id to modify. reference_generation: $ref: '#/components/schemas/ReferenceGeneration' reference_file_registration_id: type: - string - 'null' description: File Id to modify. prompt: type: - string - 'null' description: This is the primary text used for refining the images. media_type: $ref: '#/components/schemas/MediaType' product_id: type: - integer - 'null' description: If you have multiple Getty products, indicate which one you would like to use for this refine request format: int32 project_code: type: - string - 'null' description: The project code to use for the request. Some products require this value. notes: type: - string - 'null' description: The notes to use for the request. Some products require this value. aspect_ratio: type: - string - 'null' description: Aspect ratio of the result images. Must be one of 1:1, 3:4, 4:3, 9:16, or 16:9 additionalProperties: false description: Payload with all influence color by image parameters PromptEnhancementRequest: required: - prompt type: object properties: prompt: minLength: 1 type: string additionalProperties: false GenerationOptions: type: object properties: media_type: $ref: '#/components/schemas/MediaType' aspect_ratio: type: - string - 'null' mood: $ref: '#/components/schemas/Mood' additionalProperties: false Mood: enum: - black_and_white - warm - cool - natural - vivid - dramatic - bold type: string BackgroundGenerationRequest: type: object properties: reference_file_registration_id: type: - string - 'null' prompt: type: - string - 'null' product_id: type: - integer - 'null' format: int32 project_code: type: - string - 'null' notes: type: - string - 'null' left_percentage: type: - number - 'null' format: float right_percentage: type: - number - 'null' format: float top_percentage: type: - number - 'null' format: float bottom_percentage: type: - number - 'null' format: float background_file_registration_id: type: - string - 'null' background_asset_id: type: - string - 'null' background_reference_generation: $ref: '#/components/schemas/ReferenceGeneration' background_reference_adherence: $ref: '#/components/schemas/ReferenceAdherence' additionalProperties: false GetFileRegistrationsResponse: required: - file_registrations type: object properties: result_count: type: integer format: int32 file_registrations: type: - array - 'null' items: $ref: '#/components/schemas/FileRegistration' additionalProperties: false securitySchemes: Api-Key: type: apiKey name: Api-Key in: header OAuth2: type: oauth2 flows: password: tokenUrl: https://authentication.gettyimages.com/oauth2/token refreshUrl: https://authentication.gettyimages.com/oauth2/token scopes: {} clientCredentials: tokenUrl: https://authentication.gettyimages.com/oauth2/token scopes: {} authorizationCode: authorizationUrl: https://authentication.gettyimages.com/oauth2/auth tokenUrl: https://authentication.gettyimages.com/oauth2/token refreshUrl: https://authentication.gettyimages.com/oauth2/token scopes: {}