Getty Images Objects API
The Objects API from Getty Images — 1 operation(s) for objects.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Objects 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: Objects
paths:
/v3/ai/image-generations/object-removal:
post:
tags:
- Objects
summary: Remove object(s)
description: "# AI Generator - Object Removal\n\nUse 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.\n\nWhen 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.\n\n## The Remove Object Request\n\nThe `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.\n\n| Parameter | Purpose |\n|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id` | Creative image id to modify. |\n| `reference_generation` | Generation details of image to modify. | |\n| `mask_url` | **Required**: Specifies the location of the mask. |\n| `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`). |\n| `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. |\n| `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. |\n\n## Uploading mask image\n\nBefore calling the endpoint, a mask in JPEG format must be uploaded\nto `https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}`, where the client defines\nthe `{CLIENT_IMAGE.jpg}` portion of the URL.\n\nFor example, using cURL:\n\n``` sh\ncurl -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\"\n```\n\nOnce the mask has been uploaded, use the full URL as the `mask_url`.\n\n- Uploaded files must be 10MB or smaller.\n- Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness\n appropriately.\n- Uploads expire after 24 hours.\n- Uploads and object removal must be performed using the same API Key.\n\n## Fulfilled and Pending Results\n\nIn 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.\n\nHowever 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.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
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:
'200':
description: Returns the result of a request to refine images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to refine images
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Either the generation id does not exist, the index is incorrect, or the generation is still pending
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
components:
schemas:
RemoveObjectRequest:
type: object
properties:
reference_asset_id:
type: string
description: Asset Id to modify.
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
product_id:
type: integer
description: If you have multiple Getty products, indicate which one you would like to use for this refine request
format: int32
nullable: true
project_code:
type: string
description: The project code to use for the request. Some products require this value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
mask_url:
type: string
description: The location of the mask.
nullable: true
additionalProperties: false
description: Payload with all parameters for removing objects from an image
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
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: {}