---
title: "Generates images from a prompt"
method: POST
path: "/v3/ai/image-generations"
tags: ["AiGenerator"]
---

# Generates images from a prompt

`POST /v3/ai/image-generations`

# 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.

## Request body

- ImageGenerationsRequest — Payload with all generation request parameters
  - `prompt` string, nullable — The only required parameter, this is the primary text used for the generation of the images.
  - `aspect_ratio` string, nullable — Aspect ratio of the result images. Must be one of 1:1, 3:4, 4:3, 9:16, or 16:9
  - `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 generation request
  - `project_code` string, nullable — The project code to use for the generation request. Some products require this value.
  - `notes` string, nullable — The notes to use for the generation request. Some products require this value.

## Response `202`

Returns the request ID

- PendingImageGenerationResponse
  - `generation_request_id` string, nullable

## Other responses

- `400` — The request was invalid
- `403` — Product quota exceeded
- `409` — ConcurrencyConflict
- `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)