Sign in
auto-model

Generate or transform images, letting the server pick the best model

Generate one or more images without choosing a model. The server selects the model best suited to the request and may route different requests to different models.

Supplying source images turns the request into a transform: the server picks a model that can edit, and the prompt describes the change to apply. Provide the sources either as image_asset_identifiers references (images already stored with Ideogram) or as raw images bytes (multipart requests only) — if both are supplied, the references win and the bytes are ignored. negative_prompt and style_reference_asset_identifiers only apply without source images; combining them with sources is rejected with a 422 rather than silently ignored.

By default the request blocks until the images are ready and returns them in data. Set async to true to return immediately after the request is accepted, then poll for completion and results with GET /v1/generations/{generation_id} using the returned generation_id.

post/v2/image/generate/auto

Query parameters

dry_runboolean

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.

Request body

promptstring required

The prompt to generate images from, or the instruction describing how to transform the source images when sources are supplied.

imagesstring[]

The source images to transform (max 10, max size 25MB per image), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Multipart requests only; ignored if image_asset_identifiers is also supplied.

negative_promptstring

Description of what to exclude from the images. Descriptions in the prompt take precedence over descriptions in the negative prompt. Not every model consults it. Cannot be combined with source images.

aspect_ratiostring

The output aspect ratio. auto (the default) picks the most suitable ratio from the request. Without source images the value must be one of the supported ratio buckets (for example "16x9" or "1x1"); with source images any "WIDTHxHEIGHT" shape hint is accepted and the selected model serves the closest shape it supports. Omit resolution when supplying a non-auto value.

resolutionstring

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'1k' | '2k' | '4k'

The output resolution tier. Influences which model serves the request; not every model offers every tier. When omitted the server uses the selected model's default tier.

magic_prompt'auto' | 'on' | 'off'

Determine if MagicPrompt should be used in generating the request or not.

num_imagesinteger

The number of images to generate.

seedinteger

Random seed. Set for reproducible generation.

privateboolean

Whether the generated images should be kept private. When omitted, the default follows the caller's plan; some plans always generate privately.

target_collection_idstring

A collection you can write to, by its URL-safe base64 collection id. The output images are added to it when the request completes.

category_idstring

The internal generation category to attribute to the output, as a URL-safe base64 UUID without padding. Only applies when source images are supplied.

asyncboolean

When false (the default), the request blocks until the images are ready and returns them in data. When true, the request returns as soon as it is accepted; poll for completion and results with GET /v1/generations/{generation_id} using the returned generation_id.

Example request

{
  "image_asset_identifiers": [
    {
      "asset_type": "RESPONSE",
      "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
    }
  ],
  "style_reference_asset_identifiers": [
    {
      "asset_type": "RESPONSE",
      "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
    }
  ],
  "magic_prompt": "on",
  "seed": 12345
}

Response

The generated images (synchronous requests), or an acknowledgement to poll with GET /v1/generations/{generation_id} (async requests).

generation_idstring required

URL-safe base64 ID of the accepted generation. Accepted by the GET /v1/generations/{generation_id} polling endpoint.

seedinteger required

Random seed. Set for reproducible generation.

Example response

{
  "data": [
    {
      "seed": 12345,
      "prompt": "prompt",
      "resolution": "1024x1024",
      "url": "https://openapi-generator.tech",
      "is_image_safe": true
    },
    {
      "seed": 12345,
      "prompt": "prompt",
      "resolution": "1024x1024",
      "url": "https://openapi-generator.tech",
      "is_image_safe": true
    }
  ],
  "seed": 12345,
  "generation_id": "generation_id"
}

Changes

Changed in 3 of the 33 revisions of this API.8415

  • 987f73fc82de4See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 4e95197be44a8410See the full diff
    • ▲

      added to the request property allOf list (media type: multipart/form-data)

      request-property-all-of-added

    • ▲

      added to the request property allOf list (media type: application/json)

      request-property-all-of-added

    • ▲

      removed the enum value 1K of the request property (media type: multipart/form-data)

      request-property-enum-value-removed

    • ▲

      removed the enum value 1K of the request property (media type: application/json)

      request-property-enum-value-removed

    • ▲

      removed the enum value 2K of the request property (media type: multipart/form-data)

      request-property-enum-value-removed

    • ▲

      removed the enum value 2K of the request property (media type: application/json)

      request-property-enum-value-removed

    • ▲

      removed the enum value 4K of the request property (media type: multipart/form-data)

      request-property-enum-value-removed

    • ▲

      removed the enum value 4K of the request property (media type: application/json)

      request-property-enum-value-removed

    • ●

      removed from the request property allOf list (media type: multipart/form-data)

      request-property-all-of-removed

    • ●

      removed from the request property allOf list (media type: application/json)

      request-property-all-of-removed

    • ●

      changed the pattern of the request property from ^(AUTO|[1-9][0-9]{0,4}x[1-9][0-9]{0,4})$ to ^(auto|[1-9][0-9]{0,4}x[1-9][0-9]{0,4})$ (media type: multipart/form-data)

      request-property-pattern-changed

    • ●

      changed the pattern of the request property from ^(AUTO|[1-9][0-9]{0,4}x[1-9][0-9]{0,4})$ to ^(auto|[1-9][0-9]{0,4}x[1-9][0-9]{0,4})$ (media type: application/json)

      request-property-pattern-changed

    • ○

      the request property default value changed from AUTO to auto (media type: multipart/form-data)

      request-property-default-value-changed

    • ○

      the request property default value changed from AUTO to auto (media type: application/json)

      request-property-default-value-changed

    • ○

      the request property default value changed from AUTO to auto (media type: multipart/form-data)

      request-property-default-value-changed

    • ○

      the request property default value changed from AUTO to auto (media type: application/json)

      request-property-default-value-changed

    • ○

      added the new 1k enum value to the request property (media type: multipart/form-data)

      request-property-enum-value-added

    • ○

      added the new 1k enum value to the request property (media type: application/json)

      request-property-enum-value-added

    • ○

      added the new 2k enum value to the request property (media type: multipart/form-data)

      request-property-enum-value-added

    • ○

      added the new 2k enum value to the request property (media type: application/json)

      request-property-enum-value-added

    • ○

      added the new 4k enum value to the request property (media type: multipart/form-data)

      request-property-enum-value-added

    • ○

      added the new 4k enum value to the request property (media type: application/json)

      request-property-enum-value-added

    This revision also has 13 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • a235a15c02351See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 13 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog