Ideogram Auto Model API

openapi: 3.2.0
info:
  title: Ideogram API v2 Auto Model API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: auto-model
paths:
  /v2/image/generate/auto:
    post:
      operationId: autoModel_post_generate_image_v2_auto
      summary: Generate with automatic model selection
      description: 'Generate images with the model Ideogram picks as best suited to each

        request. Optionally upload source images as `images` using

        `multipart/form-data` to edit them with the prompt. Returns results

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

        `GET /v2/generations/{generation_id}`.'
      tags:
      - auto-model
      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 generated images (synchronous requests), or an acknowledgement to poll with `GET /v2/generations/{generation_id}` (`async` requests).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateImageV2AutoResponse'
        '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 source image was not found.
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: The prompt did not pass safety checks, or the request combined source images with text-to-image-only fields.
          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 generate images with an automatically selected model. Send it as `application/json`, or as `multipart/form-data` to include source `images`.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 10000
                  description: The prompt to generate images from or, when source images are supplied, the change to make to them.
                images:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Optional source images to edit (max 10, max 25MB each; JPEG, PNG, or WEBP). Multipart requests only.
                negative_prompt:
                  type: string
                  maxLength: 10000
                  description: Description of what to exclude from the images. The prompt takes precedence over the negative prompt. Not every model uses it. Cannot be combined with source images.
                aspect_ratio:
                  type: string
                  pattern: ^(auto|[1-9][0-9]{0,4}x[1-9][0-9]{0,4})$
                  default: auto
                  description: The output aspect ratio. `auto` (the default) picks the most suitable ratio for the request. Without source images the value must be a supported ratio (for example "16x9" or "1x1"); with source images any "WIDTHxHEIGHT" value is accepted and the output uses the closest supported shape. Omit `resolution` when supplying a non-`auto` value.
                resolution:
                  type: string
                  pattern: ^[1-9][0-9]{1,4}x[1-9][0-9]{1,4}$
                  description: The requested output resolution, formatted as "WIDTHxHEIGHT" (for example "1280x800"). The output is served at the closest resolution the selected model supports. Omit `aspect_ratio` (or leave it `auto`) when supplying a resolution.
                resolution_tier:
                  $ref: '#/components/schemas/V2ImageGenerateAutoPostRequestBodyContentMultipartFormDataSchemaResolutionTier'
                  description: The output resolution tier. Affects which model serves the request, since not every model offers every tier. When omitted, the selected model's default tier is used.
                magic_prompt:
                  $ref: '#/components/schemas/MagicPromptMode'
                  default: auto
                  description: Controls magic prompt (automatic prompt rewriting). Defaults to `auto`.
                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.
                private:
                  type: boolean
                  description: Whether the generated images should be kept private. When omitted, the default follows the caller's plan; some plans always generate privately.
                async:
                  type: boolean
                  default: false
                  description: When false (the default), the request waits until the images are ready and returns them 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.
              required:
              - prompt
      security:
      - ApiKeyAuth: []
  /v2/image/remix/auto:
    post:
      operationId: autoModel_post_tool_remix
      summary: Remix with automatic model selection
      description: 'Remix an image guided by a text prompt, with Ideogram choosing the

        model. Upload the source 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:
      - auto-model
      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 remixed images (synchronous requests), or an acknowledgement to poll with `GET /v2/generations/{generation_id}` (`async` requests).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolRemixResponse'
        '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
        '422':
          description: The prompt did not pass safety checks.
          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 remix one image with an automatically selected model. Send it as `multipart/form-data` with the source `image`.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 10000
                  description: The prompt that guides the remix.
                image:
                  type: string
                  format: binary
                  description: The image to remix (max 50MB; JPEG, PNG, or WEBP). Multipart requests only. The image is used only for this request and is not saved to your account.
                image_weight:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: Optional. How closely the result should follow the source image, from 1 to 100. When omitted the selected model chooses its usual strength. Combining a weight with a `resolution` or `aspect_ratio` that changes the source's aspect ratio crops the source to the new shape; this is only available at the 1K tier and is rejected at 2K.
                negative_prompt:
                  type: string
                  maxLength: 10000
                  description: Description of what to exclude from the images. The prompt takes precedence over the negative prompt. Not every model uses it.
                resolution:
                  type: string
                  pattern: ^[1-9][0-9]{1,4}x[1-9][0-9]{1,4}$
                  description: The requested output resolution, formatted as "WIDTHxHEIGHT" (for example "1280x800"). The output uses the closest supported resolution in the matching 1K or 2K tier. Omit `aspect_ratio` when supplying a resolution. If `resolution_tier` is also supplied, it must match the tier these dimensions fall in. Combining a shape-changing value with `image_weight` requires the 1K tier.
                aspect_ratio:
                  $ref: '#/components/schemas/IdeogramV4AspectRatio'
                  description: The requested output aspect ratio. Omit it to keep the source image's shape. `auto` also keeps the source shape. Omit `resolution` when supplying a concrete value. Combining a shape-changing value with `image_weight` requires the 1K tier.
                resolution_tier:
                  $ref: '#/components/schemas/V2ImageRemixAutoPostRequestBodyContentMultipartFormDataSchemaResolutionTier'
                  description: The output resolution tier. When omitted, the tier is inferred from `resolution`, or defaults to 1k. A color palette, style codes, style preset, or non-`auto` style type are only supported at 1k.
                magic_prompt:
                  $ref: '#/components/schemas/MagicPromptMode'
                  default: auto
                  description: Controls magic prompt (automatic prompt rewriting). Defaults to `auto`. The selected model decides how to interpret it.
                seed:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Optional. Only honored when the request uses a model that supports reproducible remixes; results from the default model are not reproducible. The response reports the seed used.
                style_preset:
                  $ref: '#/components/schemas/IdeogramV3StylePreset'
                  description: A predefined style preset to apply. Limits the request to a model that supports it and requires the 1K resolution tier. Cannot be combined with style codes.
                color_palette:
                  $ref: '#/components/schemas/IdeogramColorPalette'
                  description: A color palette to apply. Limits the request to a model that supports palettes and requires the 1K resolution tier.
                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_type:
                  $ref: '#/components/schemas/IdeogramV3StyleType'
                  description: The style type to generate with. A value other than `auto` limits the request to a model that supports it and requires the 1K resolution tier.
                num_images:
                  type: integer
                  minimum: 1
                  maximum: 8
                  default: 1
                  description: The number of images to generate.
                enable_copyright_detection:
                  type:
                  - boolean
                  - 'null'
                  description: 'Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with `is_image_safe: false`.'
                async:
                  type: boolean
                  default: false
                  description: When false (the default), the request waits until the images are ready and returns them 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:
              - prompt
              - image
      security:
      - ApiKeyAuth: []
components:
  schemas:
    Seed:
      type: integer
      minimum: 0
      maximum: 2147483647
      description: Random seed. Set for reproducible generation.
      title: Seed
    IdeogramColorPalettePresetName:
      type: string
      enum:
      - ember
      - fresh
      - jungle
      - magic
      - melon
      - mosaic
      - pastel
      - ultramarine
      description: A color palette preset value.
      title: IdeogramColorPalettePresetName
    MagicPromptMode:
      type: string
      enum:
      - auto
      - 'on'
      - 'off'
      description: Determine if MagicPrompt should be used in generating the request or not.
      title: MagicPromptMode
    GenerateImageV2AutoResponse:
      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/GeneratedImageObject'
          description: The generated 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: 'Response returned by `POST /v2/image/generate/auto`. Synchronous

        requests (the default) include the generated images 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: GenerateImageV2AutoResponse
    ToolRemixResponse:
      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/GeneratedImageObject'
          description: The remixed images, in generation order. Present only for synchronous requests (`async` omitted or false).
        seed:
          $ref: '#/components/schemas/Seed'
          description: The seed attached to the request. Reusing it does not guarantee a reproducible result, because the selected model may not honor seeds.
      required:
      - generation_id
      - seed
      description: 'Response returned by `POST /v2/image/remix/auto`. Synchronous

        requests (the default) include the remixed images in `data`.

        Asynchronous requests omit `data`; poll

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

        `generation_id`.

        '
      title: ToolRemixResponse
    IdeogramV3StyleType:
      type: string
      enum:
      - auto
      - general
      - realistic
      - design
      - custom
      - fiction
      - stylized
      default: general
      description: The style type to generate with.
      title: IdeogramV3StyleType
    IdeogramV4AspectRatio:
      type: string
      enum:
      - auto
      - 1x4
      - 1x3
      - 1x2
      - 9x16
      - 10x16
      - 2x3
      - 3x4
      - 4x5
      - 1x1
      - 5x4
      - 4x3
      - 3x2
      - 16x10
      - 16x9
      - 2x1
      - 3x1
      - 4x1
      default: auto
      description: 'Supported output aspect ratios. The operation defines whether `auto`

        preserves the source shape or selects a shape from the prompt.

        '
      title: IdeogramV4AspectRatio
    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
    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
    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
    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
    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
    V2ImageRemixAutoPostRequestBodyContentMultipartFormDataSchemaResolutionTier:
      type: string
      enum:
      - 1k
      - 2k
      description: The output resolution tier. When omitted, the tier is inferred from `resolution`, or defaults to 1k. A color palette, style codes, style preset, or non-`auto` style type are only supported at 1k.
      title: V2ImageRemixAutoPostRequestBodyContentMultipartFormDataSchemaResolutionTier
    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
    StyleCode:
      type: string
      pattern: ^[0-9a-fA-F]{8}$
      description: The 8 character hexadecimal representation of the style code.
      title: StyleCode
    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
    V2ImageGenerateAutoPostRequestBodyContentMultipartFormDataSchemaResolutionTier:
      type: string
      enum:
      - 1k
      - 2k
      - 4k
      description: The output resolution tier. Affects which model serves the request, since not every model offers every tier. When omitted, the selected model's default tier is used.
      title: V2ImageGenerateAutoPostRequestBodyContentMultipartFormDataSchemaResolutionTier
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"