Generative AI by Getty Images
Experience Generative AI by Getty Images, an AI model trained exclusively on licensed visuals, including our creative library and data, allowing you to rest assured that the images you generate and license are commercially safe and covered by our robust legal protections. Our product compensates our world-class content creators for the use of their work in the model, allowing them to continue to create more of the high-quality pre-shot imagery you depend on. From ideation to execution, Generative AI combines perfectly with the pre-shot Getty Images content libraries and solutions to elevate your entire creative process.
Access to the image generation functionality is restricted to Getty Images customers and partners with an AI Generation license agreement.
Refer to Swagger for full AI Generation API technical documentation.
Getting Started with Generative AI using the Getty Images API
Polling Pattern
Due to the nature of image generation, there may be a period of time (up to 60 seconds) before the generated images are available. Because of this, polling will need to be built in to the client’s process. An initial POST
to generate an image (or PUT
in the case of AI downloads), an HTTP 202
will be returned, indicating that the request was accepted but further processing is occurring. Then, the client needs poll the GET /v3/ai/image-generations/{generationRequestId}
endpoint and handle either HTTP status code 200 or 202. HTTP 202
indicates that the generation (or download) is still pending, whereas HTTP 200
indicates that the operation is complete and the pertinent information is returned in the payload. Specific details are documented in Swagger for each endpoint.
This sequence diagram illustrates the general pattern:
Polling Pattern - AI Download Endpoint
Although the overall pattern is the same as the above, it’s worth noting that the AI Download endpoint (/v3/ai/image-generations/{generationRequestId}/images/{index}/download
) differs from the AI generation endpoints as follows:
- The initial call is
PUT
, notPOST
like the other endpoints - The client must call with a
generationRequestId
value from a previous AI generation - The successul result from
PUT /v3/ai/image-generations/{generationRequestId}/images/{index}/download
is aHTTP 202
but is empty as all the pertinent information to poll theGET
endpoint is already in-hand.
Example 200 and 202 responses
When polling the GET /v3/ai/image-generations/{generationRequestId}
endpoint, the response is either HTTP 202
(process is still pending) or HTTP 200
(process is done and the final result is ready).
HTTP status code 202 - Process is still pending and polling is required
If a HTTP status code 202 is returned, the client will need to delay and then poll the GET /v3/ai/image-generations/{generationRequestId}
again. The amount of time to delay is up to the client but should be no less than 1 second. Polling should repeat until HTTP 200
or an error is returned. An example HTTP 202
result:
{
"generation_request_id": "string"
}
HTTP status code 200 - Results are returned
When HTTP 200
is returned, the request has been processed successfuly and the result is ready. Further calls to GET /v3/ai/image-generations/{generationRequestId}
will continue to return HTTP 200
with the same payload. An example HTTP 200
result:
{
"generation_request_id": "string",
"seed": 0,
"results": [
{
"index": 0,
"is_blocked": true,
"preview_urls": [
{
"preview_size": "string",
"image_url": "string",
"width": 0,
"height": 0
}
],
"url": "string"
}
],
"original_asset": {
"id": "string"
}
}
General Recommendations
- When polling, wait 1 second between calls.
- Avoid long-lived connections on your server by polling from the user agent.
- Do not try to encapsulate all Getty Images API calls into a single call from the user agent as this will lead to timeouts.
Basic Image Generation Workflow Example
Get Access Token
In order to generate images you will need to use Client Credentials or Authorization Code to obtain an access token, and then include that token in all calls.
Generate images using a prompt
Use a prompt to generate images. Use our prompt guide to learn more about writing prompts.
Basic Image Generation Request Template
curl -X POST \
"https://api.gettyimages.com/v3/ai/image-generations" \
-H "accept: application/json" \
-H "Api-Key: <YOUR_API_KEY>" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d "{
'prompt': 'Prompt Text',
'aspect_ratio': '4:3'
}"
HTTP Status Codes
General guidelines on HTTP status codes can be found in this section.
429 - Too Many Requests
A 429 status code indicates the client has sent too many requests in a given amount of time. This may be due to the client’s rate limit (information in this section) or the number of concurrent pending generations. If the number of queries per second (QPS) sent by the client is less than the client’s rate limit and the 429 status code is returned on any of the ai/image-generations/*
endpoints it may be due to concurrent generations rather than rate limit. There are limits to how many concurrent generations can be pending. When the client goes over their alloted limit, the calls will return HTTP status code 429. We suggest handling a 429 status code by waiting for 1 second and calling again.
HTTP/2 429
content-type: application/json
content-length: 31
{"message":"Too Many Requests"}
The easiest way to handle 429 status responses is to use a fault-handling library such as Polly for .NET or Tenacity for Python. Libraries for other languages can be found on GitHub.