Ideogram Reframe API

openapi: 3.2.0
info:
  title: Ideogram API v2 Reframe API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: reframe
paths:
  /v2/image/reframe/ideogram-3:
    post:
      operationId: reframe_ideogramV3
      summary: Reframe with Ideogram 3.0
      description: 'Expand an image to a new Ideogram 3.0 resolution, keeping the source

        pixels in the center and filling the new area. Upload the source

        `image` using `multipart/form-data`. Returns results directly by

        default; set `async` to get a `generation_id` and poll

        `GET /v2/generations/{generation_id}`.'
      tags:
      - reframe
      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 reframed images, or an acknowledgement for an asynchronous request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReframeImageIdeogramV3Response'
        '400':
          description: Invalid input provided.
          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'
        '404':
          description: A referenced resource 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: Use `multipart/form-data` to upload the source `image` and any `style_reference_images`.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The JPEG, PNG, or WEBP image to reframe (max 25MB). Multipart requests only.
                resolution:
                  $ref: '#/components/schemas/ResolutionV3'
                num_images:
                  type: integer
                  minimum: 1
                  maximum: 8
                  default: 1
                  description: The number of images to generate.
                seed:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Random seed. Set for reproducible generation.
                rendering_speed:
                  $ref: '#/components/schemas/V2ImageReframeIdeogram3PostRequestBodyContentMultipartFormDataSchemaRenderingSpeed'
                  default: default
                style_preset:
                  $ref: '#/components/schemas/IdeogramV3StylePreset'
                color_palette:
                  $ref: '#/components/schemas/IdeogramColorPalette'
                style_codes:
                  type: array
                  items:
                    $ref: '#/components/schemas/StyleCode'
                  description: A list of 8-character hexadecimal codes representing the style of the image. Refer to each endpoint for supported combinations with style types, presets, and reference images.
                style_reference_images:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: JPEG, PNG, or WEBP style reference images (max 10, max 25MB each). Multipart requests only. Cannot be combined with `style_preset` or `style_codes`.
                async:
                  type: boolean
                  default: false
                  description: Return immediately instead of waiting for reframed images.
              required:
              - image
              - resolution
      security:
      - ApiKeyAuth: []
  /v2/image/reframe/nano-banana-2:
    post:
      operationId: reframe_nanoBanana2
      summary: Reframe with Nano Banana 2
      description: 'Expand an image to a new aspect ratio with Nano Banana 2. Upload the

        source `image` using `multipart/form-data`. Always asynchronous:

        returns a `generation_id`; poll `GET /v2/generations/{generation_id}`

        for results.'
      tags:
      - reframe
      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: An acknowledgement to poll with `GET /v2/generations/{generation_id}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReframeImageNanoBanana2Response'
        '400':
          description: Invalid input provided.
          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'
        '404':
          description: A referenced resource 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:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The JPEG, PNG, or WEBP image to reframe (max 50MB).
                aspect_ratio:
                  $ref: '#/components/schemas/NanoBanana2ReframeAspectRatio'
                private:
                  type: boolean
                  description: 'API-key requests are always private. For bearer-authenticated

                    requests, this controls whether the result is private; when

                    omitted, it follows the caller''s plan entitlement. Enterprise

                    generations are always private.

                    '
                num_images:
                  type: integer
                  minimum: 1
                  maximum: 4
                  default: 1
                  description: The number of output images to generate.
                seed:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Random seed. Set for reproducible generation.
              required:
              - image
              - aspect_ratio
      security:
      - ApiKeyAuth: []
components:
  schemas:
    GeneratedImageObject:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          format: uri
          description: The direct link to the generated image. Empty when the image did not pass safety checks.
        prompt:
          type: string
          description: The final prompt the image was generated from.
        resolution:
          type: string
          description: The resolution of the generated 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:
      - prompt
      - resolution
      - is_image_safe
      - seed
      description: One generated output image.
      title: GeneratedImageObject
    IdeogramColorPalette:
      oneOf:
      - $ref: '#/components/schemas/IdeogramColorPaletteWithPresetName'
      - $ref: '#/components/schemas/ColorPaletteWithMembers'
      description: A color palette for generation, must EITHER be specified via one of the presets (name) or explicitly via hexadecimal representations of the color with optional weights (members).
      title: IdeogramColorPalette
    IdeogramColorPaletteWithPresetName:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/IdeogramColorPalettePresetName'
      required:
      - name
      description: A color palette specified only via its name. Cannot be used in conjunction with members.
      title: IdeogramColorPaletteWithPresetName
    ReframeImageNanoBanana2Response:
      type: object
      properties:
        generation_id:
          type: string
          description: 'URL-safe base64 ID of the accepted generation. Accepted by the

            `GET /v2/generations/{generation_id}` polling endpoint.

            '
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Random seed. Set for reproducible generation.
        width:
          type: integer
          description: The resolved 1K output width in pixels.
        height:
          type: integer
          description: The resolved 1K output height in pixels.
      required:
      - generation_id
      - seed
      - width
      - height
      description: 'Acknowledges an accepted asynchronous Reframe request. Poll

        `GET /v2/generations/{generation_id}` for completion and output

        images. The seed, width, and height report the values the request

        resolved to when the caller left them unset.

        '
      title: ReframeImageNanoBanana2Response
    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
    V2ImageReframeIdeogram3PostRequestBodyContentMultipartFormDataSchemaRenderingSpeed:
      type: string
      enum:
      - turbo
      - default
      - quality
      default: default
      title: V2ImageReframeIdeogram3PostRequestBodyContentMultipartFormDataSchemaRenderingSpeed
    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
    IdeogramColorPalettePresetName:
      type: string
      enum:
      - ember
      - fresh
      - jungle
      - magic
      - melon
      - mosaic
      - pastel
      - ultramarine
      description: A color palette preset value.
      title: IdeogramColorPalettePresetName
    ReframeImageIdeogramV3Response:
      type: object
      properties:
        generation_id:
          type: string
          description: 'URL-safe base64 ID of the accepted generation. Accepted by the

            `GET /v2/generations/{generation_id}` polling endpoint.

            '
        data:
          type: array
          items:
            $ref: '#/components/schemas/GeneratedImageObject'
          description: The reframed images, in generation order. Present only for synchronous requests (`async` omitted or false).
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Random seed. Set for reproducible generation.
      required:
      - generation_id
      - seed
      description: 'Synchronous requests (the default) include the reframed images in

        `data`. Requests with `async` set to true omit `data`; poll for

        completion and results with `GET /v2/generations/{generation_id}`.

        The seed reports the value the request resolved to when the caller

        left it unset.

        '
      title: ReframeImageIdeogramV3Response
    ColorPaletteWithMembers:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/ColorPaletteMember'
          description: 'A list of ColorPaletteMembers that define the color palette. Each color palette member

            consists of a required color hex and an optional weight between 0.05 and 1.0 (inclusive).

            It is recommended that these weights descend from highest to lowest for the color hexes provided.

            '
      required:
      - members
      description: A color palette represented only via its members. Cannot be used in conjunction with preset name.
      title: ColorPaletteWithMembers
    GenerationErrorResponseTaskCompletionSpeed:
      type: string
      enum:
      - fast
      - slow
      description: 'The queue this request resolved to. Present when `reject_reason`

        is `inflight_limit`.

        '
      title: GenerationErrorResponseTaskCompletionSpeed
    ResolutionV3:
      type: string
      enum:
      - 512x1536
      - 576x1408
      - 576x1472
      - 576x1536
      - 640x1344
      - 640x1408
      - 640x1472
      - 640x1536
      - 704x1152
      - 704x1216
      - 704x1280
      - 704x1344
      - 704x1408
      - 704x1472
      - 736x1312
      - 768x1088
      - 768x1216
      - 768x1280
      - 768x1344
      - 800x1280
      - 832x960
      - 832x1024
      - 832x1088
      - 832x1152
      - 832x1216
      - 832x1248
      - 864x1152
      - 896x960
      - 896x1024
      - 896x1088
      - 896x1120
      - 896x1152
      - 960x832
      - 960x896
      - 960x1024
      - 960x1088
      - 1024x832
      - 1024x896
      - 1024x960
      - 1024x1024
      - 1088x768
      - 1088x832
      - 1088x896
      - 1088x960
      - 1120x896
      - 1152x704
      - 1152x832
      - 1152x864
      - 1152x896
      - 1216x704
      - 1216x768
      - 1216x832
      - 1248x832
      - 1280x704
      - 1280x768
      - 1280x800
      - 1312x736
      - 1344x640
      - 1344x704
      - 1344x768
      - 1408x576
      - 1408x640
      - 1408x704
      - 1472x576
      - 1472x640
      - 1472x704
      - 1536x512
      - 1536x576
      - 1536x640
      description: The resolutions supported for Ideogram 3.0.
      title: ResolutionV3
    NanoBanana2ReframeAspectRatio:
      type: string
      enum:
      - '1:1'
      - '3:2'
      - '2:3'
      - '4:3'
      - '3:4'
      - '5:4'
      - '4:5'
      - '16:9'
      - '9:16'
      - '21:9'
      - '4:1'
      - '1:4'
      - '8:1'
      - '1:8'
      description: Aspect ratios Nano Banana 2 can reframe an image to.
      title: NanoBanana2ReframeAspectRatio
    StyleCode:
      type: string
      pattern: ^[0-9a-fA-F]{8}$
      description: The 8 character hexadecimal representation of the style code.
      title: StyleCode
    ColorPaletteMember:
      type: object
      properties:
        color_hex:
          type: string
          pattern: ^#(?:[0-9a-fA-F]{3}){1,2}$
          description: The hexadecimal representation of the color with an optional chosen weight.
        color_weight:
          type: number
          format: double
          minimum: 0.05
          maximum: 1
          description: The weight of the color in the color palette.
      required:
      - color_hex
      description: A member of a color palette.
      title: ColorPaletteMember
    IdeogramV3StylePreset:
      type: string
      enum:
      - 80s_illustration
      - 90s_nostalgia
      - abstract_organic
      - analog_nostalgia
      - art_brut
      - art_deco
      - art_poster
      - aura
      - avant_garde
      - bauhaus
      - blueprint
      - blurry_motion
      - bright_art
      - c4d_cartoon
      - childrens_book
      - collage
      - coloring_book_i
      - coloring_book_ii
      - cubism
      - dark_aura
      - doodle
      - double_exposure
      - dramatic_cinema
      - editorial
      - emotional_minimal
      - ethereal_party
      - expired_film
      - flat_art
      - flat_vector
      - forest_reverie
      - geo_minimalist
      - glass_prism
      - golden_hour
      - graffiti_i
      - graffiti_ii
      - halftone_print
      - high_contrast
      - hippie_era
      - iconic
      - japandi_fusion
      - jazzy
      - long_exposure
      - magazine_editorial
      - minimal_illustration
      - mixed_media
      - monochrome
      - nightlife
      - oil_painting
      - old_cartoons
      - paint_gesture
      - pop_art
      - retro_etching
      - riviera_pop
      - spotlight_80s
      - stylized_red
      - surreal_collage
      - travel_poster
      - vintage_geo
      - vintage_poster
      - watercolor
      - weird
      - woodblock_print
      description: A predefined style preset that applies a specific artistic style to the generated image.
      title: IdeogramV3StylePreset
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"