Getty Images Refine API

openapi: 3.0.1
info:
  title: Getty Images Refine 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: Refine
paths:
  /v3/ai/image-generations/refine:
    post:
      tags:
      - Refine
      summary: Refine a creative image
      description: "# AI Generator - Image Refining\n\nUse a mask image and text prompts to modify content in a image from the Getty Images creative library (excluding illustrations and vectors).\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. \nTo download a refined image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required.\nLastly, downloading a refined image requires the client to first download the original image.\n \n\n## The Refine Request\n\nThe `RefineRequest` payload one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following\nparameters:\n\n| Parameter           | Purpose                                                                                                                                                                                      |\n|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id`| Creative image id to modify.                                                                                                                                 |\n| `reference_generation`| Generation details of image to modify.                                                                                                                               |\n| `prompt`\t\t      | The primary text used for refined portion of the images.                                                                                                                                     |\n| `negative_prompt`   | Concepts to _exclude_ from the refined portion.                                                                                                                                              |\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| `mask_url`          | Required. Specifies the location of the mask.                                                                                                                                                |                                                                                 |\n\n## Uploading mask image\n\nBefore calling the refine endpoint, a mask in JPEG format must be uploaded to `https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}`, where the client defines the `{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 appropriately.\n- Uploads expire after 24 hours.\n- Uploads and refining 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`\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/RefineRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/RefineRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RefineRequest'
      responses:
        '200':
          description: Returns the result of a request to refine an image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationsResponse'
        '202':
          description: Returns the request ID for a pending request to refine 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
    RefineRequest:
      required:
      - mask_url
      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
        mask_url:
          minLength: 1
          type: string
      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: {}