Getty Images Extend API
The Extend API from Getty Images — 1 operation(s) for extend.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Extend API
version: '3'
description: '
Developer resources for the Getty Images API including SDK, documentation,
release notes, status, notifications and sample code.'
security:
- Api-Key: []
- OAuth2: []
tags:
- name: Extend
paths:
/v3/ai/image-generations/extend:
post:
tags:
- Extend
summary: Extend a creative image
description: '# AI Generator - Image Extension
Use text prompts and numerical values to extend the content beyond the borders of a image from the Getty Images creative library (excluding illustrations and vectors).
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. |
| `negative_prompt` | Concepts to _exclude_ from the extended portion. |
| `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.
'
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:
'200':
description: Returns the result of a request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
components:
schemas:
ImageDataResponse:
type: object
properties:
index:
type: integer
format: int32
is_blocked:
type: boolean
preview_urls:
type: array
items:
$ref: '#/components/schemas/PreviewUrl'
description: The preview URLs for the result
nullable: true
url:
type: string
nullable: true
additionalProperties: false
PendingImageGenerationResponse:
type: object
properties:
generation_request_id:
type: string
nullable: true
additionalProperties: false
PreviewUrl:
type: object
properties:
preview_size:
type: string
nullable: true
image_url:
type: string
nullable: true
width:
type: integer
format: int32
height:
type: integer
format: int32
additionalProperties: false
ImageGenerationsResponse:
type: object
properties:
generation_request_id:
type: string
nullable: true
seed:
type: integer
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/ImageDataResponse'
nullable: true
original_asset:
$ref: '#/components/schemas/AssetDetail'
additionalProperties: false
ReferenceGeneration:
type: object
properties:
generation_request_id:
type: string
description: The id from a previous request to generate images.
nullable: true
index:
type: integer
description: The index of the image from the specific images generation.
format: int32
additionalProperties: false
AssetDetail:
type: object
properties:
id:
type: string
nullable: true
additionalProperties: false
ExtendRequest:
type: object
properties:
reference_asset_id:
type: string
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
prompt:
type: string
nullable: true
negative_prompt:
type: string
nullable: true
product_id:
type: integer
format: int32
nullable: true
project_code:
type: string
nullable: true
notes:
type: string
nullable: true
left_percentage:
type: number
format: float
nullable: true
right_percentage:
type: number
format: float
nullable: true
top_percentage:
type: number
format: float
nullable: true
bottom_percentage:
type: number
format: float
nullable: true
additionalProperties: false
securitySchemes:
Api-Key:
type: apiKey
name: Api-Key
in: header
OAuth2:
type: oauth2
flows:
password:
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
refreshUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}
clientCredentials:
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}
authorizationCode:
authorizationUrl: https://api.gettyimages.com/v4/oauth2/auth
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
refreshUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}