openapi: 3.0.1
info:
  title: Getty Images Index 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: Index
paths:
  /v3/ai/image-generations/{generationRequestId}/images/{index}/variations:
    post:
      tags:
      - Index
      summary: Get variations on a generated image
      description: '# AI Generator - Generate Variations


        Generate image variations from a previously-generated image.


        ## The Image Variation Request


        The `ImageVariationRequest` payload to be posted contains the optional

        parameters:


        | Parameter           | Purpose                                                                                                                                                                                      |

        |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

        | `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.                                                                                                                  |


        ## 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.

        '
      parameters:
      - name: generationRequestId
        in: path
        description: The ID from a previous request to generate images
        required: true
        style: simple
        schema:
          type: string
      - name: index
        in: path
        description: The index of the image from the specific images generation
        required: true
        style: simple
        schema:
          type: integer
          format: int32
      requestBody:
        description: Request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageVariationRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ImageVariationRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ImageVariationRequest'
      responses:
        '200':
          description: Returns the result of a request to generate a variation of images
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationsResponse'
        '202':
          description: Returns the request ID for a pending request to generate a variation of 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
        '429':
          description: TooManyConcurrentGenerations
  /v3/ai/image-generations/{generationRequestId}/images/{index}/download-sizes:
    get:
      tags:
      - Index
      summary: Get download sizes for a generated image
      description: '# AI Generator - Get Download Sizes


        Given a fulfilled generation request `id` and the `index` of a generated image, gets a list of download sizes for the image.

        '
      parameters:
      - name: generationRequestId
        in: path
        description: The ID from a previous request to generate images
        required: true
        style: simple
        schema:
          type: string
      - name: index
        in: path
        description: The index of the image from the specific images generation
        required: true
        style: simple
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Returns the result of a request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadSizesResponse'
        '400':
          description: InvalidProduct
        '404':
          description: Either the generation id does not exist, the index is incorrect, or the generation is still pending
        '410':
          description: GenerationRequestGone
  /v3/ai/image-generations/{generationRequestId}/images/{index}/download:
    put:
      tags:
      - Index
      summary: Begin the download process
      description: '# AI Generator - Download Image


        Download a generated image. Initiating the download process for a 4K file may incur a cost depending on the terms of your agreement.


        ## Download Image Request body details


        The `ImageDownloadRequest` payload to be posted contains the required `size` as well as some other optional

        parameters:


        | Parameter         | Purpose                                                                                      |

        |-------------------|----------------------------------------------------------------------------------------------|

        | `size_name` _Required_ | Must be one of the valid download sizes retrieved through the "Get Download Sizes" endpoint |

        | `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.                                                                                                                  |


        ## 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 a URL for the download.


        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` with no payload. This client should then

        poll `GET v3/ai/image-generations/{generationRequestId}/images/{index}/download` periodically to get the final

        download.

        '
      parameters:
      - name: generationRequestId
        in: path
        description: The ID from a previous request to generate images
        required: true
        style: simple
        schema:
          type: string
      - name: index
        in: path
        description: The index of the image from the specific images generation
        required: true
        style: simple
        schema:
          type: integer
          format: int32
      requestBody:
        description: Request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageDownloadRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ImageDownloadRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ImageDownloadRequest'
      responses:
        '200':
          description: Download request was successful and is complete
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
        '202':
          description: Download request was successful put is pending
        '400':
          description: InvalidProduct
        '403':
          description: ProductQuotaExceeded
        '404':
          description: GenerationRequestIdNotFound
        '409':
          description: A download is already in progress for the given `generationRequestId` and `index`.
        '410':
          description: GenerationRequestGone
    get:
      tags:
      - Index
      summary: "Once the download process has started, this endpoint can be used to check the status of the download and get the\r\ndownload URL once it is completed."
      description: '# AI Generator - Get Download Image


        Get the download for a generated image


        ## 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 a URL for the download.


        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` with no payload. This client should then

        poll `GET v3/ai/image-generations/{generationRequestId}/images/{index}/download` periodically to get the final

        download.


        Like the `PUT v3/ai/image-generations/{generationRequestId}/images/{index}/download` endpoint, the result of calling

        this endpoint will be either:


        - `HTTP 200 OK` with the download URL

        - `HTTP 202 Accepted` with no payload


        `HTTP 202 Accepted` is returned in the case where the download preparation has not yet completed. In this case it is

        expected that the client will occasionally poll this endpoint until a `HTTP 200 OK` result with a full payload is

        returned.

        '
      parameters:
      - name: generationRequestId
        in: path
        description: The ID from a previous request to generate images
        required: true
        style: simple
        schema:
          type: string
      - name: index
        in: path
        description: The index of the image from the specific images generation
        required: true
        style: simple
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Download request was successful and is complete
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
        '202':
          description: Download request was successful put is pending
        '400':
          description: InvalidProduct
        '404':
          description: GenerationRequestIdNotFound
        '410':
          description: GenerationRequestGone
components:
  schemas:
    ImageDownloadRequest:
      type: object
      properties:
        notes:
          type: string
          description: The notes to use for the download request.  Some products require this value.
          nullable: true
        project_code:
          type: string
          description: The project code to use for the download request.  Some products require this value.
          nullable: true
        size_name:
          type: string
          description: The size name.  Valid values are 1k or 4k.
          nullable: true
      additionalProperties: false
      description: Parameters for requesting an AI generation image download
    DownloadSizeResponse:
      type: object
      properties:
        size_name:
          type: string
          nullable: true
        height:
          type: integer
          format: int32
        width:
          type: integer
          format: int32
      additionalProperties: false
    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
    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
    PendingImageGenerationResponse:
      type: object
      properties:
        generation_request_id:
          type: string
          nullable: true
      additionalProperties: false
    DownloadResponse:
      type: object
      properties:
        url:
          type: string
          nullable: true
        generated_asset_id:
          type: string
          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
    AssetDetail:
      type: object
      properties:
        id:
          type: string
          nullable: true
      additionalProperties: false
    DownloadSizesResponse:
      type: object
      properties:
        download_sizes:
          type: array
          items:
            $ref: '#/components/schemas/DownloadSizeResponse'
          nullable: true
      additionalProperties: false
    ImageVariationRequest:
      type: object
      properties:
        product_id:
          type: integer
          description: If you have multiple Getty products, indicate which one you would like to use for this generation request
          format: int32
          nullable: true
        project_code:
          type: string
          description: The project code to use for the generation request.  Some products require this value.
          nullable: true
        notes:
          type: string
          description: The notes to use for the generation request.  Some products require this value.
          nullable: true
      additionalProperties: false
      description: Payload with all images variation parameters
  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: {}