--- title: "Influence the composition of generated images using a reference image" method: POST path: "/v3/ai/image-generations/influence-composition-by-image" tags: ["AiGenerator"] --- # Influence the composition of generated images using a reference image `POST /v3/ai/image-generations/influence-composition-by-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. | | `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. ## Request body - InfluenceCompositionByImageRequest — Payload with all influence composition by image parameters - `reference_asset_id` string, nullable — Asset Id to modify. - `reference_generation` ReferenceGeneration - `generation_request_id` string, nullable — The id from a previous request to generate images. - `index` integer — The index of the image from the specific images generation. - `reference_file_registration_id` string, nullable — File Id to modify. - `prompt` string, nullable — This is the primary text used for refining the images. - `media_type` 'photography' | 'illustration' - `mood` 'black_and_white' | 'warm' | 'cool' | 'natural' | 'vivid' | 'dramatic' | 'bold' - `product_id` integer, nullable — If you have multiple Getty products, indicate which one you would like to use for this refine request - `project_code` string, nullable — The project code to use for the request. Some products require this value. - `notes` string, nullable — The notes to use for the request. Some products require this value. ## Response `202` Returns the request ID for a pending request to extend an image - PendingImageGenerationResponse - `generation_request_id` string, nullable ## Other responses - `400` — InvalidProduct - `403` — Product quota exceeded - `404` — Image not found - `409` — ConcurrencyConflict - `410` — GenerationRequestGone - `429` — TooManyConcurrentGenerations --- [API](https://skmtc.net/gettyimages/apis/getty-images-api.md) · [All operations](https://skmtc.net/gettyimages/apis/getty-images-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gettyimages/getty-images-api/revisions/29f239eeae86/schema)