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.

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

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

$	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"
>	}'

1	{
2	"json_prompt": {
3	"high_level_description": "A photorealistic ginger cat perched on a vintage wooden chair by a sunlit window.",
4	"compositional_deconstruction": {
5	"background": "A dim room with a bright window casting warm light.",
6	"elements": [
7	{
8	"type": "obj",
9	"desc": "ginger cat with green eyes sitting upright on a vintage wooden chair"
10	}
11	]
12	},
13	"style_description": {
14	"aesthetics": "warm, cozy, nostalgic",
15	"lighting": "soft natural window light",
16	"medium": "photograph"
17	}
18	},
19	"aspect_ratio": "1x1"
20	}