---
title: "Generate a Magic Prompt with Ideogram 4.0"
method: POST
path: "/v1/ideogram-v4/magic-prompt"
tags: ["prompt"]
---

# Generate a Magic Prompt with Ideogram 4.0

`POST /v1/ideogram-v4/magic-prompt`

Transforms a basic prompt into an enhanced Ideogram 4.0 magic prompt.
The magic prompt model version is fixed; callers cannot select it.
When `aspect_ratio` is `AUTO` (the default), the model selects the most
suitable aspect ratio for the prompt and returns it in the response.

## Request body

- MagicPromptV4Request — A request to generate an Ideogram 4.0 magic prompt.
  - `text_prompt` string, required — The natural-language prompt to enhance into an Ideogram 4.0 magic prompt. Named `text_prompt` to match the Ideogram 4.0 generate request surface.
  - `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.

## Response `200`

Magic prompt generated successfully.

- MagicPromptV4Response — The response containing the generated Ideogram 4.0 magic prompt.
  - `json_prompt` V4JsonPrompt, required — 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.
    - `high_level_description` string, required — One- or two-sentence overall description of the desired image.
    - `style_description` V4StyleDescription — Optional style description supplied alongside a V4 JSON prompt.
      - `aesthetics` string — Aesthetic notes (mood, vibe, references).
      - `art_style` string — Optional art-style hint (e.g., illustration, oil painting).
      - `lighting` string — Lighting description.
      - `medium` string — Medium description (e.g., photograph, digital art).
      - `photo` string — Optional photographic style notes (e.g., lens, film stock).
      - `color_palette` string[] — 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.
    - `compositional_deconstruction` V4CompositionalDeconstruction, required — The compositional breakdown of a V4 prompt — background plus an ordered list of elements.
      - `background` string, required — Description of the background of the scene.
      - `elements` V4PromptElement[], required — Ordered list of elements (objects and text) composing the scene.
        - union — A single element in the V4 prompt's compositional deconstruction. Discriminated by the `type` field.
          - object — A non-text element (object, character, background detail) in the V4 prompt layout.
            - `type` 'obj', required — Discriminator. Must be `obj`.
            - `bbox` integer[] — 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` string, required — Description of the object element.
            - `color_palette` string[] — 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.
          - object — A text element to render in the V4 prompt layout.
            - `type` 'text', required — Discriminator. Must be `text`.
            - `bbox` integer[] — 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` string, required — The literal text to render in the image.
            - `desc` string, required — Description of the text element (style, role, placement notes).
            - `color_palette` string[] — 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.
    - `tags` string[] — Round-trip metadata surfaced by the describe endpoint when `strip_tags=false`. Ignored by the v4 sampler on generate input.
  - `aspect_ratio` 'AUTO' | '1x4' | '1x3' | '1x2' | '9x16' | '10x16' | '2x3' | '3x4' | '4x5' | '1x1' | '5x4' | '4x3' | '3x2' | '16x10' | '16x9' | '2x1' | '3x1' | '4x1', required — 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.

## Other responses

- `400` — Invalid input provided.
- `401` — Not authorized to generate magic prompts.
- `429` — Too many requests.
- `500` — Internal server error.

---

[API](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/bd40f367a834/schema)