Ideogram Image Describe API

openapi: 3.2.0
info:
  title: Ideogram API v2 Image Describe API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: image-describe
paths:
  /v2/image/describe/ideogram-4:
    post:
      operationId: imageDescribe_post_describe_image_ideogram_v4
      summary: Describe with Ideogram 4.0
      description: 'Describe an image as a structured `V4JsonPrompt` with Ideogram''s 4.0

        image captioner (a fine-tune of the Qwen3-VL vision-language model).

        Upload the image as `image` using `multipart/form-data`; the

        `json_prompt` is returned directly and can be passed to the

        `/v1/ideogram-v4/generate` endpoints.'
      tags:
      - image-describe
      responses:
        '200':
          description: Structured prompt generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeImageIdeogramV4Response'
        '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: The source image was not found.
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Image failed the safety check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageSafetyError'
        '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 describe one image. Send it as `multipart/form-data` with the `image` to describe.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The image to describe (max 10MB). JPEG, PNG, and WebP are supported. Multipart requests only.
                include_bbox:
                  type: boolean
                  default: true
                  description: Whether to include bounding boxes for the subjects and text in the returned `json_prompt`. Defaults to true, so the prompt preserves the layout of the described image.
                include_style_descriptions:
                  type: boolean
                  default: false
                  description: Whether to include a free-form style description in the returned `json_prompt`. Defaults to false.
                include_tags:
                  type: boolean
                  default: false
                  description: Whether to include free-form tags in the returned `json_prompt`. Defaults to false.
              required:
              - image
      security:
      - ApiKeyAuth: []
  /v2/image/describe/ideogram-3:
    post:
      operationId: imageDescribe_post_describe_image_ideogram_v3
      summary: Describe with Ideogram 3.0
      description: 'Generate a natural-language description of an image with Ideogram''s 3.0

        image captioner (a fine-tune of the Qwen2-VL vision-language model).

        Upload the image as `image` using `multipart/form-data`; the description

        is returned directly.'
      tags:
      - image-describe
      responses:
        '200':
          description: Description(s) generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeImageIdeogramV3Response'
        '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: The source image was not found.
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Image failed the safety check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageSafetyError'
        '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 describe one image. Send it as `multipart/form-data` with the `image` to describe.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The image to describe (max 10MB). JPEG, PNG, and WebP are supported. Multipart requests only.
              required:
              - image
      security:
      - ApiKeyAuth: []
components:
  schemas:
    ImageSafetyError:
      type: object
      properties:
        error:
          type: string
      required:
      - error
      title: ImageSafetyError
    V4TextPromptElementType:
      type: string
      enum:
      - text
      description: Discriminator. Must be `text`.
      title: V4TextPromptElementType
    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
    DescribeImageIdeogramV4Response:
      type: object
      properties:
        description_id:
          type: string
          description: URL-safe base64 ID of the description that was created.
        created:
          type: string
          format: date-time
          description: The time the request was created.
        json_prompt:
          $ref: '#/components/schemas/V4JsonPrompt'
      required:
      - description_id
      - created
      - json_prompt
      description: 'Response returned by `POST /v2/image/describe/ideogram-4`.

        The `json_prompt` field is a structured `V4JsonPrompt` that can be

        passed back as `json_prompt` to the `/v1/ideogram-v4/generate` family

        of endpoints.

        '
      title: DescribeImageIdeogramV4Response
    V4ObjPromptElementType:
      type: string
      enum:
      - obj
      description: Discriminator. Must be `obj`.
      title: V4ObjPromptElementType
    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
    V4PromptElement:
      oneOf:
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/V4ObjPromptElementType'
            description: Discriminator. Must be `obj`.
          bbox:
            type: array
            items:
              type: integer
              minimum: 0
              maximum: 1000
            description: 'Bounding box for an element, expressed as four integers in `[0, 1000]`

              with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are

              normalized so the canvas is `1000 x 1000` regardless of the final

              resolution.

              '
          desc:
            type: string
            description: Description of the object element.
          color_palette:
            type: array
            items:
              type: string
              pattern: ^#[0-9a-fA-F]{6}$
            description: 'Optional list of hex color strings (e.g. "#FFD700") that bias the

              Ideogram 4.0 output toward this palette. Applied as a soft color bias,

              not an exact per-pixel lock.

              '
        required:
        - type
        - desc
        description: A non-text element (object, character, background detail) in the V4 prompt layout.
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/V4TextPromptElementType'
            description: Discriminator. Must be `text`.
          bbox:
            type: array
            items:
              type: integer
              minimum: 0
              maximum: 1000
            description: 'Bounding box for an element, expressed as four integers in `[0, 1000]`

              with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are

              normalized so the canvas is `1000 x 1000` regardless of the final

              resolution.

              '
          text:
            type: string
            description: The literal text to render in the image.
          desc:
            type: string
            description: Description of the text element (style, role, placement notes).
          color_palette:
            type: array
            items:
              type: string
              pattern: ^#[0-9a-fA-F]{6}$
            description: 'Optional list of hex color strings (e.g. "#FFD700") that bias the

              Ideogram 4.0 output toward this palette. Applied as a soft color bias,

              not an exact per-pixel lock.

              '
        required:
        - type
        - text
        - desc
        description: A text element to render in the V4 prompt layout.
      discriminator:
        propertyName: type
      description: 'A single element in the V4 prompt''s compositional deconstruction.

        Discriminated by the `type` field.

        '
      title: V4PromptElement
    DescribeImageIdeogramV3Response:
      type: object
      properties:
        description_id:
          type: string
          description: URL-safe base64 ID of the description that was created.
        created:
          type: string
          format: date-time
          description: The time the request was created.
        descriptions:
          type: array
          items:
            $ref: '#/components/schemas/GeneratedDescription'
          description: The generated description(s) for the provided image.
      required:
      - description_id
      - created
      - descriptions
      description: Response returned by `POST /v2/image/describe/ideogram-3`.
      title: DescribeImageIdeogramV3Response
    V4JsonPrompt:
      type: object
      properties:
        high_level_description:
          type: string
          description: One- or two-sentence overall description of the desired image.
        style_description:
          $ref: '#/components/schemas/V4StyleDescription'
        compositional_deconstruction:
          $ref: '#/components/schemas/V4CompositionalDeconstruction'
      required:
      - high_level_description
      - compositional_deconstruction
      description: 'Structured prompt for Ideogram 4.0 generation. When `json_prompt` is

        supplied, magic-prompt is disabled and the diffusion model consumes

        the JSON contract directly. Mutually exclusive with `text_prompt`

        and the legacy `prompt` field.

        '
      title: V4JsonPrompt
    GenerationErrorResponseTaskCompletionSpeed:
      type: string
      enum:
      - fast
      - slow
      description: 'The queue this request resolved to. Present when `reject_reason`

        is `inflight_limit`.

        '
      title: GenerationErrorResponseTaskCompletionSpeed
    V4CompositionalDeconstruction:
      type: object
      properties:
        background:
          type: string
          description: Description of the background of the scene.
        elements:
          type: array
          items:
            $ref: '#/components/schemas/V4PromptElement'
          description: Ordered list of elements (objects and text) composing the scene.
      required:
      - background
      - elements
      description: The compositional breakdown of a V4 prompt — background plus an ordered list of elements.
      title: V4CompositionalDeconstruction
    GeneratedDescription:
      type: object
      properties:
        text:
          type: string
          description: The generated description for the provided image.
      required:
      - text
      title: GeneratedDescription
    V4StyleDescription:
      type: object
      properties:
        aesthetics:
          type: string
          description: Aesthetic notes (mood, vibe, references).
        art_style:
          type: string
          description: Optional art-style hint (e.g., illustration, oil painting).
        lighting:
          type: string
          description: Lighting description.
        medium:
          type: string
          description: Medium description (e.g., photograph, digital art).
        photo:
          type: string
          description: Optional photographic style notes (e.g., lens, film stock).
        color_palette:
          type: array
          items:
            type: string
            pattern: ^#[0-9a-fA-F]{6}$
          description: 'Optional list of hex color strings (e.g. "#FFD700") that bias the

            Ideogram 4.0 output toward this palette. Applied as a soft color bias,

            not an exact per-pixel lock.

            '
      description: Optional style description supplied alongside a V4 JSON prompt.
      title: V4StyleDescription
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"