Generate a Magic Prompt with Ideogram 4.0 | Ideogram

curl -X POST https://api.ideogram.ai/v1/ideogram-v4/magic-prompt \
     -H "Api-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "text_prompt": "A photo of a cat",
  "aspect_ratio": "AUTO"
}'

{
  "json_prompt": {
    "high_level_description": "A photorealistic ginger cat perched on a vintage wooden chair by a sunlit window.",
    "compositional_deconstruction": {
      "background": "A dim room with a bright window casting warm light.",
      "elements": [
        {
          "type": "obj",
          "desc": "ginger cat with green eyes sitting upright on a vintage wooden chair"
        }
      ]
    },
    "style_description": {
      "aesthetics": "warm, cozy, nostalgic",
      "lighting": "soft natural window light",
      "medium": "photograph"
    }
  },
  "aspect_ratio": "1x1"
}

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.

Authentication

Api-Keystring

API key for access control. Use in the header with the name “Api-Key”

Request

A request to generate an Ideogram 4.0 magic prompt.

text_promptstringRequired

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_ratioenumOptionalDefaults to AUTO

Target aspect ratio. Defaults to AUTO, which lets the model select the most suitable ratio and return it in the response.

Response

Magic prompt generated successfully.

json_promptobject

The enhanced prompt as an Ideogram 4.0 structured JSON prompt. This conforms to the same contract as json_prompt on /v1/ideogram-v4/generate, so it can be passed straight back to that endpoint.

aspect_ratioenumDefaults to AUTO

The resolved aspect ratio. When the request used AUTO, this is the ratio the model selected; otherwise it echoes the request.

Errors

400

Bad Request Error

401

Unauthorized Error

429

Too Many Requests Error

500

Internal Server Error