Ideogram Design API

openapi: 3.2.0
info:
  title: Ideogram API v2 Design API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: design
paths:
  /v2/design/layerize/ideogram-3:
    post:
      operationId: design_post_layerize_design_ideogram_v3
      summary: Layerize text with Ideogram 3.0
      description: 'Turn a flat image into an editable design: detected text is returned as

        positioned text blocks with matched fonts, sizes, and colors, alongside

        a text-free base image. Upload the image as `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:
      - design
      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 layerized design (synchronous requests), or an acknowledgement to poll with `GET /v2/generations/{generation_id}` (`async` requests).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayerizeDesignIdeogramV3Response'
        '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'
        '403':
          description: Not authorized to layerize 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 layerize the text in one image. Send it as `multipart/form-data` with the source `image`.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The source image to layerize (max 50MB). Common image formats such as JPEG, PNG, and WEBP are supported. Multipart requests only.
                prompt:
                  type:
                  - string
                  - 'null'
                  maxLength: 10000
                  description: A description of the image, used to guide text detection. When omitted, detection runs on the image alone.
                seed:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Random seed. Set for reproducible generation.
                font_candidate_files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Candidate font files to make available for text style matching. Supported formats .ttf, .otf, .woff, .woff2 (max 5MB each, maximum 5 files). Multipart requests only.
                async:
                  type: boolean
                  default: false
                  description: When false (the default), the request waits until layerization is complete and returns the result in `data`. When true, the request returns as soon as it is accepted; poll `GET /v2/generations/{generation_id}` with the returned `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:
    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
    LayerizeDesignIdeogramV3Response:
      type: object
      properties:
        generation_id:
          type: string
          description: 'URL-safe base64 ID of the generation. Use it to poll

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

            '
        data:
          type: array
          items:
            $ref: '#/components/schemas/LayerizedImageObject'
          description: The layerized design. 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: 'Response returned by `POST /v2/design/layerize/ideogram-3`.

        Synchronous requests (the default) include the layerized design in

        `data`. Asynchronous requests omit `data`; poll

        `GET /v2/generations/{generation_id}` with the returned

        `generation_id`. `seed` is the seed that was used, including when you

        did not set one.

        '
      title: LayerizeDesignIdeogramV3Response
    DetectedTextBlockAlignment:
      type: string
      enum:
      - left
      - center
      - right
      description: Detected text alignment.
      title: DetectedTextBlockAlignment
    LayerizedImageObject:
      type: object
      properties:
        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:
      - 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.

        '
      title: LayerizedImageObject
    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
    GenerationErrorResponseTaskCompletionSpeed:
      type: string
      enum:
      - fast
      - slow
      description: 'The queue this request resolved to. Present when `reject_reason`

        is `inflight_limit`.

        '
      title: GenerationErrorResponseTaskCompletionSpeed
    DetectedTextBlockFormattingItems:
      type: string
      enum:
      - bold
      - italic
      - underline
      - strikethrough
      - all_caps
      - small_caps
      - superscript
      - subscript
      title: DetectedTextBlockFormattingItems
    DetectedTextBlockRole:
      type: string
      enum:
      - heading
      - subheading
      - body
      - caption
      description: Inferred typographic role of this text block.
      title: DetectedTextBlockRole
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"