Ideogram Generations API

openapi: 3.2.0
info:
  title: Ideogram API v2 Generations API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: Generations
paths:
  /v2/generations/{generation_id}:
    get:
      operationId: generations_get_generation_v2
      summary: Poll a generation
      description: 'Retrieves the current status of an asynchronous generation, and its

        results once complete. Use the `generation_id` returned by any `/v2`

        endpoint that runs asynchronously: every video and tool endpoint, and

        any image endpoint called with `async` or a `webhook_url`.


        While the generation is `pending` or has `failed`, the response

        contains only `generation_id`, `status`, and `created` (plus

        `failure_reason` once failed). Once `status` is `completed`, the

        response includes `response_type` and `data`. Each `data` item carries

        an `object_type` that identifies its shape, so image and video results

        can be told apart. `usage_cost_usd_micros` reports the amount billed

        when the request uses variable usage-based pricing.


        Polling is rate limited per organization; a 429 response carries a

        `Retry-After` header with the number of seconds to wait.'
      tags:
      - Generations
      parameters:
      - name: generation_id
        in: path
        description: URL-safe base64 ID of the generation, as returned when the request was accepted.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Generation status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationResponse'
        '400':
          description: The generation ID is not a valid URL-safe base64 ID.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Not authorized.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Generation not found.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                description: Any type
      security:
      - ApiKeyAuth: []
components:
  schemas:
    GenerationResponseStatus:
      type: string
      enum:
      - pending
      - completed
      - failed
      description: 'Current status of the generation. `pending`: still in progress; the response contains only `generation_id`, `status`, and `created`. `completed`: finished successfully; the response includes `response_type` and `data`, and may include `usage_cost_usd_micros` when the request uses variable usage-based pricing. `failed`: generation did not succeed; the response contains only `generation_id`, `status`, and `created`.'
      title: GenerationResponseStatus
    LayerizedTextBlockAlignment:
      type: string
      enum:
      - left
      - center
      - right
      description: Detected text alignment.
      title: LayerizedTextBlockAlignment
    GenerationResponseResponseType:
      type: string
      enum:
      - url
      description: Present when `status` is `completed`; always "url" for this shape.
      title: GenerationResponseResponseType
    DetectedTextBlockRole:
      type: string
      enum:
      - heading
      - subheading
      - body
      - caption
      description: Inferred typographic role of this text block.
      title: DetectedTextBlockRole
    DetectedTextBlockAlignment:
      type: string
      enum:
      - left
      - center
      - right
      description: Detected text alignment.
      title: DetectedTextBlockAlignment
    LayerizedTextBlockFormattingItems:
      type: string
      enum:
      - bold
      - italic
      - underline
      - strikethrough
      - all_caps
      - small_caps
      - superscript
      - subscript
      title: LayerizedTextBlockFormattingItems
    LayerizedTextBlockRole:
      type: string
      enum:
      - heading
      - subheading
      - body
      - caption
      description: Inferred typographic role of this text block.
      title: LayerizedTextBlockRole
    GenerationResponseDataInnerDiscriminatorMappingSvgGenerationMimeType:
      type: string
      enum:
      - image/svg+xml
      title: GenerationResponseDataInnerDiscriminatorMappingSvgGenerationMimeType
    LayerizedTextBlock:
      type: object
      properties:
        x:
          type: integer
          description: X coordinate in pixels from the top-left corner.
        y:
          type: integer
          description: Y coordinate in pixels from the top-left corner.
        width:
          type: integer
          description: Width of the text region in pixels.
        height:
          type: integer
          description: Height of the text region in pixels.
        text:
          type: string
          description: The detected text content. Line breaks are represented as \n.
        alignment:
          $ref: '#/components/schemas/LayerizedTextBlockAlignment'
          description: Detected text alignment.
        angle:
          type: string
          title: float
          description: Rotation angle in degrees (clockwise). Defaults to 0.
          default: 0
        font_name:
          type:
          - string
          - 'null'
          description: Best-matching font name from the font library.
        font_alternatives:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Alternative font matches, ranked by similarity.
        font_size:
          type:
          - integer
          - 'null'
          description: Detected font size in points.
        line_height:
          type:
          - string
          - 'null'
          title: float
          description: Line height multiplier (e.g., 1.2).
        color:
          type:
          - string
          - 'null'
          pattern: ^#[0-9A-Fa-f]{6}$
          description: Detected text color in hex format.
        formatting:
          type: array
          items:
            $ref: '#/components/schemas/LayerizedTextBlockFormattingItems'
          description: Detected text formatting effects.
        role:
          oneOf:
          - $ref: '#/components/schemas/LayerizedTextBlockRole'
          - type: 'null'
          description: Inferred typographic role of this text block.
        layer_id:
          type: string
          description: Identifier of this block's layer in the page at `html_url`; pass it to the page's editing API.
        spans:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TextColorSpan'
          description: 'The block''s colour runs in reading order. Present, with at least one

            run, whenever `color` is set; concatenating the runs'' `text` reproduces

            the block''s `text`. `color` reports the dominant colour.

            '
      required:
      - x
      - y
      - width
      - height
      - text
      - alignment
      - formatting
      - layer_id
      description: A single detected text region with its position, content, font information, and styling.
      title: LayerizedTextBlock
    DetectedTextBlockFormattingItems:
      type: string
      enum:
      - bold
      - italic
      - underline
      - strikethrough
      - all_caps
      - small_caps
      - superscript
      - subscript
      title: DetectedTextBlockFormattingItems
    GenerationResponse_data_inner:
      oneOf:
      - type: object
        properties:
          object_type:
            type: string
            enum:
            - image.without-prompt-or-seed
            description: 'Discriminator value: image.without-prompt-or-seed'
          url:
            type:
            - string
            - 'null'
            format: uri
            description: The direct link to the reframed image.
          resolution:
            type: string
            description: The exact dimensions of the reframed image, formatted as "{width}x{height}".
          is_image_safe:
            type: boolean
            description: Whether this image passes safety checks. If false, the url field is empty.
        required:
        - object_type
        - resolution
        - is_image_safe
        description: An image result that does not expose its prompt or seed.
      - type: object
        properties:
          object_type:
            type: string
            enum:
            - svg.generation
            description: 'Discriminator value: svg.generation'
          asset_id:
            type: string
            description: URL-safe base64 SVG asset ID.
          url:
            type: string
            format: uri
            description: Signed download URL for the original SVG.
          mime_type:
            $ref: '#/components/schemas/GenerationResponseDataInnerDiscriminatorMappingSvgGenerationMimeType'
          width:
            type: integer
            minimum: 1
            description: Width of the output SVG canvas in pixels.
          height:
            type: integer
            minimum: 1
            description: Height of the output SVG canvas in pixels.
        required:
        - object_type
        - asset_id
        - url
        - mime_type
        - width
        - height
        description: SvgGenerationObject variant
      - type: object
        properties:
          object_type:
            type: string
            enum:
            - image.generation
            description: 'Discriminator value: image.generation'
          url:
            type:
            - string
            - 'null'
            format: uri
            description: The direct link to the image generated.
          prompt:
            type: string
            description: The prompt used for the generation. This may be different from the original prompt.
          resolution:
            type: string
            description: The resolution of the generated image, formatted as "{width}x{height}".
          is_image_safe:
            type: boolean
            description: Whether this image passes safety checks. If false, the url field will be empty.
          seed:
            type: integer
            minimum: 0
            maximum: 2147483647
            description: Random seed. Set for reproducible generation.
        required:
        - object_type
        - prompt
        - resolution
        - is_image_safe
        - seed
        description: A single generated image. Model-agnostic shape returned by the generation polling endpoint.
      - type: object
        properties:
          object_type:
            type: string
            enum:
            - video.generation
            description: 'Discriminator value: video.generation'
          asset_id:
            type: string
            description: The generated video's asset ID. Use it with asset_type RESPONSE in video_asset_identifier for a follow-up video edit. This is distinct from the generation ID used for polling.
          url:
            type:
            - string
            - 'null'
            format: uri
            description: The direct link to the generated video.
          prompt:
            type: string
            description: The prompt used for the generation.
          resolution:
            type: string
            description: The resolution tier of the generated video.
          aspect_ratio:
            type: string
            description: The actual aspect ratio of the produced video, formatted as "{width}:{height}".
          duration:
            type: integer
            description: The actual measured length of the produced video in seconds.
        required:
        - object_type
        - prompt
        - resolution
        - aspect_ratio
        - duration
        description: A single generated video returned by the generation polling endpoint.
      - type: object
        properties:
          object_type:
            type: string
            enum:
            - layerized_image
            description: 'Discriminator value: layerized_image'
          url:
            type:
            - string
            - 'null'
            format: uri
            description: The direct link to the design image with its text intact. Empty when the image did not pass safety checks.
          base_image_url:
            type:
            - string
            - 'null'
            format: uri
            description: The direct link to the base image with all detected text removed. Empty when the image did not pass safety checks.
          resolution:
            type: string
            description: The resolution of the design, formatted as "WIDTHxHEIGHT".
          is_image_safe:
            type: boolean
            description: Whether the image passed safety checks. If false, the image links are empty.
          seed:
            type: integer
            minimum: 0
            maximum: 2147483647
            description: Random seed. Set for reproducible generation.
          text_blocks:
            type: array
            items:
              $ref: '#/components/schemas/DetectedTextBlock'
            description: Flat list of detected text regions in the design.
        required:
        - object_type
        - resolution
        - is_image_safe
        - seed
        - text_blocks
        description: 'One layerized design. Image links are available for a limited period

          of time; if you would like to keep an image, you must download it.

          '
      - type: object
        properties:
          object_type:
            type: string
            enum:
            - layerized_design.generation
            description: 'Discriminator value: layerized_design.generation'
          url:
            type:
            - string
            - 'null'
            format: uri
            description: Signed link to the design image with its text intact. Empty when the image did not pass safety checks.
          base_image_url:
            type:
            - string
            - 'null'
            format: uri
            description: Signed link to the base image with all detected text removed. Empty when the image did not pass safety checks.
          resolution:
            type: string
            description: The resolution of the design, formatted as "WIDTHxHEIGHT".
          is_image_safe:
            type: boolean
            description: Whether the image passed safety checks. If false, the links are empty.
          seed:
            type: integer
            minimum: 0
            maximum: 2147483647
            description: Random seed. Set for reproducible generation.
          text_blocks:
            type: array
            items:
              $ref: '#/components/schemas/LayerizedTextBlock'
            description: Flat list of detected text regions in the design.
          html_url:
            type:
            - string
            - 'null'
            format: uri
            description: 'Signed link to a self-contained HTML page displaying the editable

              design, including curved text, gradients, outlines, and shadows. The

              renderer, images, and fonts are embedded in the page, so it keeps

              working offline once downloaded; the link itself expires after 24

              hours. Uploaded `font_candidate_files` are embedded as supplied, so

              redistributing the page is subject to those fonts'' licenses. Empty

              when the image did not pass safety checks or the page could not be

              built.


              The page exposes one editing API for every text layer, whether it

              is drawn as HTML or on a canvas. Each layer is addressed by its

              `text_blocks[].layer_id`. Scripts in the page can call

              `window.layerize` (`ready`, `getTextLayers()`, `setText(id, text)`,

              `update(id, patch)`, `toJSON()`, `toPNG()`); a parent page that

              embeds it in an iframe sends `postMessage` requests such as

              `{"type": "layerize:set-text", "id": "text-0", "text": "Hello"}`

              and receives `layerize:ready`, `layerize:updated`, and

              `layerize:error` replies. The page is served sandboxed with an

              opaque origin, so it cannot read cookies or storage of the site

              that embeds it.

              '
        required:
        - object_type
        - resolution
        - is_image_safe
        - seed
        - text_blocks
        description: 'One layerized design. Links are available for a limited period of time;

          if you would like to keep a file, you must download it.

          '
      discriminator:
        propertyName: object_type
      title: GenerationResponse_data_inner
    DetectedTextBlock:
      type: object
      properties:
        x:
          type: integer
          description: X coordinate in pixels from the top-left corner.
        y:
          type: integer
          description: Y coordinate in pixels from the top-left corner.
        width:
          type: integer
          description: Width of the text region in pixels.
        height:
          type: integer
          description: Height of the text region in pixels.
        text:
          type: string
          description: The detected text content. Line breaks are represented as \n.
        alignment:
          $ref: '#/components/schemas/DetectedTextBlockAlignment'
          description: Detected text alignment.
        angle:
          type: string
          title: float
          description: Rotation angle in degrees (clockwise). Defaults to 0.
          default: 0
        font_name:
          type:
          - string
          - 'null'
          description: Best-matching font name from the font library.
        font_alternatives:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Alternative font matches, ranked by similarity.
        font_size:
          type:
          - integer
          - 'null'
          description: Detected font size in points.
        line_height:
          type:
          - string
          - 'null'
          title: float
          description: Line height multiplier (e.g., 1.2).
        color:
          type:
          - string
          - 'null'
          pattern: ^#[0-9A-Fa-f]{6}$
          description: Detected text color in hex format.
        formatting:
          type: array
          items:
            $ref: '#/components/schemas/DetectedTextBlockFormattingItems'
          description: Detected text formatting effects.
        role:
          oneOf:
          - $ref: '#/components/schemas/DetectedTextBlockRole'
          - type: 'null'
          description: Inferred typographic role of this text block.
      required:
      - x
      - y
      - width
      - height
      - text
      - alignment
      - formatting
      description: A single detected text region with its position, content, font information, and styling.
      title: DetectedTextBlock
    GenerationResponse:
      type: object
      properties:
        generation_id:
          type: string
          description: URL-safe base64 ID of the generation.
        status:
          $ref: '#/components/schemas/GenerationResponseStatus'
          description: 'Current status of the generation. `pending`: still in progress; the response contains only `generation_id`, `status`, and `created`. `completed`: finished successfully; the response includes `response_type` and `data`, and may include `usage_cost_usd_micros` when the request uses variable usage-based pricing. `failed`: generation did not succeed; the response contains only `generation_id`, `status`, and `created`.'
        created:
          type: string
          format: date-time
          description: The time the generation was created.
        response_type:
          $ref: '#/components/schemas/GenerationResponseResponseType'
          description: Present when `status` is `completed`; always "url" for this shape.
        usage_cost_usd_micros:
          type: integer
          format: int64
          minimum: 0
          description: The total variable usage-based cost charged for the completed request, in millionths of a US dollar. Present only when `status` is `completed` and the request uses variable usage-based pricing; omitted otherwise.
        failure_reason:
          type: string
          description: 'A short machine-readable reason the generation failed, for example

            `content_policy_violation`. Present only when `status` is `failed`.

            '
        data:
          type: array
          items:
            $ref: '#/components/schemas/GenerationResponse_data_inner'
          description: 'A list of generated images or videos. Present when `status` is

            `completed`. Video entries carry an `object_type` of

            `video.generation`; layerized designs carry `layerized_image`;

            entries without an `object_type` are images.

            '
      required:
      - generation_id
      - status
      - created
      description: The current status and, when complete, result data for an asynchronous generation.
      title: GenerationResponse
    TextColorSpan:
      type: object
      properties:
        text:
          type: string
          description: The characters in this run.
        color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$
          description: Hex colour for this run.
      required:
      - text
      - color
      description: 'One run of characters within a text block that shares a single colour. A block

        whose letters are individually coloured returns one span per letter; a block in a

        single colour returns one span covering all of it. Concatenating `text` across a

        block''s spans in order reproduces the block''s full text.

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