Ideogram Tools API

openapi: 3.2.0
info:
  title: Ideogram API v2 Tools API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: Tools
paths:
  /v2/image/upscale/auto:
    post:
      operationId: tools_post_upscale
      summary: Upscale with automatic model selection
      description: 'Upscale an image to 2x, 4x, or 8x its original resolution with a model

        Ideogram picks per request; the choice may change over time. Upload the

        source `image` using `multipart/form-data`.

        Returns results directly by default; set `async` or supply a

        `webhook_url` to get a `generation_id` and poll

        `GET /v2/generations/{generation_id}`.'
      tags:
      - Tools
      parameters:
      - name: dry_run
        in: query
        description: 'When true, the request is validated and priced but not run: nothing is

          generated, stored, or billed, and no safety review is performed. The

          response is a `PriceQuote` object instead of the usual response for this

          endpoint. Send exactly the request you would send to generate, so the

          quote reflects the same options.

          '
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The upscaled image (synchronous requests), or an acknowledgement to poll with `GET /v2/generations/{generation_id}` (`async` requests).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpscaleToolResponse'
        '400':
          description: Invalid input provided, or the output would exceed the 8K limit.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                description: Any type
        '402':
          description: Insufficient credits or quota.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationErrorResponse'
        '403':
          description: Not authorized to upscale images.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: The source image was not found.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                description: Any type
        '503':
          description: The endpoint is temporarily unavailable.
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: A request to upscale one image. Upload the source `image` using `multipart/form-data`.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The source image to upscale, in a common format such as JPEG, PNG, or WEBP, up to 50MB. Multipart requests only. The uploaded image is used for this request only and is not stored.
                upscale_factor:
                  $ref: '#/components/schemas/V2ImageUpscaleAutoPostRequestBodyContentMultipartFormDataSchemaUpscaleFactor'
                  default: x2
                  description: 'How much to enlarge the source image: 2x, 4x, or 8x its original width and height. Rejected when the output would exceed 8192px on either side.'
                seed:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Random seed. Set for reproducible generation.
                async:
                  type: boolean
                  default: false
                  description: When false (the default), the request blocks until the upscaled image is ready and returns it in `data`. When true, the request returns as soon as it is accepted; poll `GET /v2/generations/{generation_id}` for the result.
                webhook_url:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: 'HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a

                    JSON POST to this URL once all images for the request have finished

                    generating. The body mirrors the synchronous generate response:

                    `request_id`, `created`, and a `data` array

                    containing every generated image (`url`, `prompt`, `resolution`, `seed`,

                    `is_image_safe`). Each delivery is signed with Ed25519 and verifiable

                    against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS;

                    private and loopback hosts and the cloud metadata service are rejected.

                    '
              required:
              - image
      security:
      - ApiKeyAuth: []
components:
  schemas:
    UpscaleImageObject:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          format: uri
          description: The direct link to the upscaled image. Empty when the image did not pass safety checks.
        resolution:
          type: string
          description: The resolution of the upscaled image, formatted as "WIDTHxHEIGHT".
        is_image_safe:
          type: boolean
          description: Whether the image passed safety checks. If false, `url` is empty.
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Random seed. Set for reproducible generation.
      required:
      - resolution
      - is_image_safe
      - seed
      description: One upscaled output image.
      title: UpscaleImageObject
    GenerationErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A message describing why the generation request was rejected.
        reject_reason:
          $ref: '#/components/schemas/GenerationRejectReason'
        max_inflight_requests:
          type: integer
          minimum: 1
          description: 'How many generations the account may have in progress at once on

            the queue this request resolved to. Present when `reject_reason`

            is `inflight_limit`.

            '
        task_completion_speed:
          $ref: '#/components/schemas/GenerationErrorResponseTaskCompletionSpeed'
          description: 'The queue this request resolved to. Present when `reject_reason`

            is `inflight_limit`.

            '
      required:
      - error
      - reject_reason
      description: A generation request rejected by an account or usage limit.
      title: GenerationErrorResponse
    GenerationRejectReason:
      type: string
      enum:
      - insufficient_funds
      - subscription_required
      - daily_limit
      - priority_credit_required
      - inflight_limit
      - feature_limit
      description: The account or usage limit that rejected a generation request.
      title: GenerationRejectReason
    V2ImageUpscaleAutoPostRequestBodyContentMultipartFormDataSchemaUpscaleFactor:
      type: string
      enum:
      - x2
      - x4
      - x8
      default: x2
      description: 'How much to enlarge the source image: 2x, 4x, or 8x its original width and height. Rejected when the output would exceed 8192px on either side.'
      title: V2ImageUpscaleAutoPostRequestBodyContentMultipartFormDataSchemaUpscaleFactor
    GenerationErrorResponseTaskCompletionSpeed:
      type: string
      enum:
      - fast
      - slow
      description: 'The queue this request resolved to. Present when `reject_reason`

        is `inflight_limit`.

        '
      title: GenerationErrorResponseTaskCompletionSpeed
    UpscaleToolResponse:
      type: object
      properties:
        generation_id:
          type: string
          description: 'The generation ID to poll with `GET /v2/generations/{generation_id}`.

            '
        data:
          type: array
          items:
            $ref: '#/components/schemas/UpscaleImageObject'
          description: The upscaled image. Present only for synchronous requests (`async` omitted or false).
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Random seed. Set for reproducible generation.
        width:
          type: integer
          description: The output width in pixels.
        height:
          type: integer
          description: The output height in pixels.
      required:
      - generation_id
      - seed
      - width
      - height
      description: 'Synchronous requests (the default) include the upscaled image in `data`.

        Async requests omit `data`; poll `GET /v2/generations/{generation_id}`

        with the returned `generation_id`. `seed` is the seed actually used,

        and `width` and `height` are the output dimensions.

        '
      title: UpscaleToolResponse
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"