Sign in
auto-model

Remix an existing image, letting the server pick the best model

Transform an existing image with a server-selected model, guided by a text prompt. Supply the source as image bytes (multipart requests only). image_weight controls how closely the result follows the source; when omitted the selected model chooses its usual strength.

The server chooses a model that supports the requested remix controls: style references (ad hoc or saved), a color palette, style codes, a style preset, and a non-auto style type each restrict the request to a compatible model and to the 1K tier; remixes without those controls use the default model. Omit resolution and aspect_ratio to keep the source image's shape. Supplying image_weight together with a resolution or aspect_ratio that changes the source's aspect ratio routes the request to a model that crops the source to the new shape; that combination is served only at the 1K tier and is rejected at 2K. (The model-pinned remix endpoints such as /v2/image/remix/ideogram-4 reject the combination outright.) seed is honored only on the compatible model; the default model synthesizes an unseeded instruction prompt, so results are not reproducible there.

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.

Supplying a webhook_url makes the request asynchronous whatever async says: the response returns as soon as the request is accepted, and the finished result is POSTed to that URL.

post/v2/image/remix/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 that guides the remix.

imagestring binary

The image to transform (max size 50MB), as raw bytes; only JPEG, PNG and WEBP are supported. Multipart requests only. Supply this or image_asset_identifier, never both. The bytes are staged for this generation request and are not added to your account's image assets.

image_weightinteger

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 requires the 1K tier.

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.

resolutionstring

The requested output resolution, formatted as "WIDTHxHEIGHT" (for example "1280x800"). The output is served at the closest resolution the selected model supports in the corresponding 1K or 2K tier. Omit aspect_ratio when supplying a resolution. If resolution_tier is also supplied, it must match the tier implied by these dimensions. Combining a shape-changing value with image_weight requires the 1K tier.

aspect_ratio'auto' | '1x4' | '1x3' | '1x2' | '9x16' | '10x16' | '2x3' | '3x4' | '4x5' | '1x1' | '5x4' | '4x3' | '3x2' | '16x10' | '16x9' | '2x1' | '3x1' | '4x1'

The aspect ratio for an Ideogram 4.0 magic prompt. auto lets the model select the most suitable ratio from the prompt; any other value pins the ratio. The non-auto values are the buckets the 4.0 model supports.

resolution_tier'1k' | '2k'

The output resolution tier. Influences which model serves the request. When omitted, the tier is inferred from resolution, or defaults to 1k when no exact resolution is supplied. Inputs that restrict the server's model choice (style references, saved styles, a color palette, style codes, a style preset, or a non-auto style type) currently support only 1K AUTO remixes.

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

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

seedinteger

Optional. Honored when the server selects the model that supports deterministic remixes; the default model synthesizes its own prompt, so results are not reproducible there. The response reports the seed used.

style_reference_collection_idstring

A saved style to apply, by its URL-safe base64 collection id. Takes priority over style_reference_asset_identifiers. Restricts the server to a model that supports style references and requires the 1K resolution tier.

style_reference_collection_version_idstring

Optional URL-safe base64 version id pinning a specific version of the style_reference_collection_id collection. Ignored without it.

style_preset'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'

A predefined style preset that applies a specific artistic style to the generated image.

style_codesStyleCode[]

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'auto' | 'general' | 'realistic' | 'design' | 'custom' | 'fiction' | 'stylized'

The style type to generate with.

num_imagesinteger

The number of images to generate.

enable_copyright_detectionboolean nullable

Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.

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.

webhook_urlstring uri

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.

privateboolean nullable

Whether the generated images should be kept private. Omitted or true keeps them private. False publishes them unless the caller's plan always generates 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.

Example request

{
  "image_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  },
  "magic_prompt": "on",
  "seed": 12345,
  "style_reference_asset_identifiers": [
    {
      "asset_type": "RESPONSE",
      "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
    }
  ],
  "style_preset": "bright_art",
  "color_palette": {
    "name": "pastel"
  },
  "style_codes": [
    "AAFF5733",
    "0133FF57",
    "DE3357FF"
  ],
  "style_type": "general",
  "webhook_url": "https://api.example.com/webhooks/ideogram"
}

Response

The remixed 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": "",
  "generation_id": "generation_id"
}

Changes

Changed in 2 of the 33 revisions of this API.14107

  • 4e95197be44a14106See 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

    • ▲

      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

    • ▲

      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

    • ▲

      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

    • ▲

      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 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

    • ●

      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

    • ●

      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

    • ●

      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

    • ●

      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

    • ○

      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

    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