openapi: 3.0.1 info: title: Getty Images Background 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: Background paths: /v3/ai/image-generations/background-removal: post: tags: - Background summary: Remove a background description: "# AI Generator - Background Removal\nUse 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.\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 Background Removal Request\n\nThe `BackgroundRemovalRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following optional\nparameters:\n\n| Parameter\t\t\t | Purpose |\n|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id`| Creative image id to modify. |\n| `reference_generation`| Generation details of image to modify. | |\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` | 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. | |\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`\nresult 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\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained 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/BackgroundRemovalRequest' text/json: schema: $ref: '#/components/schemas/BackgroundRemovalRequest' application/*+json: schema: $ref: '#/components/schemas/BackgroundRemovalRequest' 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: The request was invalid '403': description: Product quota exceeded '404': description: Image not found '410': description: GenerationRequestGone '429': description: TooManyConcurrentGenerations /beta/ai/image-generations/background-generations: post: tags: - Background summary: Add a background to a reference image description: "# AI Generator - Background Generation\n\nBackground Generation allows the client application to provide a `reference_file_registration_id` as a reference for creating new AI-generated product photos. Our technology will generate new background content behind the image based on the prompt and other parameters submitted with the request. The padding values are used to position the product on the canvas.\n\nUse of this endpoint may result in the deduction of a credit depending on the terms of your license.\n\n## The Background Generation Request\n\nThe `BackgroundGenerationRequest` payload requires a reference image (`reference_file_registration_id`) and `prompt` and accepts the following parameters:\n\n| Parameter\t\t\t\t\t\t\t | Purpose |\n|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_file_registration_id` _Required_\t| Registered file id of the image being used as a reference. The `CustomerProduct` category **must** be used when registering the file. |\n| `prompt`\t_Required_\t\t\t\t| The primary text used for refined portion of the images. |\n| `negative_prompt`\t\t\t\t\t| Concepts to _exclude_ from the refined portion. |\n| `product_id`\t\t\t\t\t\t| 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`\t\t\t\t\t\t\t| 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`\t\t\t\t\t| 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. | \n| `left_percentage`\t\t\t\t\t| Percentage of padding to add to the left side of the item in the image. Default is 0. |\n| `right_percentage`\t\t\t\t| Percentage of padding to add to the right side of the item in the image. Default is 0. |\n| `top_percentage`\t\t\t\t\t| Percentage of padding to add to the top side of the item in the image. Default is 0. |\n| `bottom_percentage`\t\t\t\t| Percentage of padding to add to the bottom side of the item in the image. Default is 0. |\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`\nresult 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\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained 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." requestBody: description: Request parameters content: application/json: schema: $ref: '#/components/schemas/BackgroundGenerationRequest' text/json: schema: $ref: '#/components/schemas/BackgroundGenerationRequest' application/*+json: schema: $ref: '#/components/schemas/BackgroundGenerationRequest' responses: '200': description: Returns the result of a request content: application/json: schema: $ref: '#/components/schemas/ImageGenerationsResponse' '202': description: Returns the request ID for a pending request content: application/json: schema: $ref: '#/components/schemas/PendingImageGenerationResponse' '400': description: InvalidProduct '403': description: Product quota exceeded '404': description: Image not found '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 BackgroundGenerationRequest: type: object properties: reference_file_registration_id: type: string nullable: true 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 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 BackgroundRemovalRequest: 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 additionalProperties: false description: Remove a background 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: {}