ComfyUI-AliAn-Ideogram-Magic-Prompt

ComfyUI Ideogram Magic Prompt

A ComfyUI custom node that calls Ideogram's hosted magic-prompt API to turn a plain-text prompt into the structured JSON caption that Ideogram 4 expects.

It uses Ideogram's free hosted service — no model download, no GPU usage. Typical round-trip: 2-5 seconds.

Preview

┌─────────────────────────────────────┐
│  prompt: "a ginger cat wearing a   │
│   tiny wizard hat reading a        │
│   spellbook"                       │
│  api_key: ••••••                   │
│  aspect_ratio: [1x1 ▾]             │
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│  json_caption:                      │
│  {                                  │
│   "high_level_description": "...",  │
│   "style_description": { ... },     │
│   "compositional_deconstruction": { │
│     "background": "...",            │
│     "elements": [                   │
│       { "type": "obj", "bbox": ... }│
│     ]                               │
│   }                                 │
│  }                                  │
└─────────────────────────────────────┘

Install

Option A — ComfyUI Manager (recommended)

1. Open ComfyUI Manager.
2. Search for "Ideogram Magic Prompt" (or the repo name ComfyUI-AliAn-Ideogram-Magic-Prompt).
3. Click Install. The Manager reads pyproject.toml for the version, PublisherId, and DisplayName automatically.
4. Restart ComfyUI.

Option B — Manual install

1. Drop the entire comfyui_ideogram_magic_prompt/ folder into <your-comfyui>/custom_nodes/.
2. Restart ComfyUI.
3. The node "Ideogram Magic Prompt" will appear under the Add Node → Ideogram category.

No pip install needed — the node uses only urllib from the Python standard library plus the comfy_api module shipped with ComfyUI.

Inputs

| Name | Type | Description | | --- | --- | --- | | prompt | multiline string | The plain-text prompt to expand. | | api_key | string (password) | Your IDEOGRAM_API_KEY from ideogram.ai/api/learn/. | | aspect_ratio | combo | One of the 18 ratios accepted by Ideogram's magic-prompt API, plus AUTO. Pick the closest match to your target image. | | suppress_artifacts | bool (default True) | If on, appends the positive-constraint snippet ("no noise, no grain, no blur, no jpeg...") to the generated caption. See the "Artifact suppression" section below. |

Supported aspect ratios

AUTO, 1x4, 1x3, 1x2, 9x16, 10x16, 2x3, 3x4, 4x5, 1x1, 5x4, 4x3, 3x2, 16x10, 16x9, 2x1, 3x1, 4x1

Output

| Name | Type | Description | | --- | --- | --- | | json_caption | string (JsonPreview) | Stringified JSON caption ready to feed into any Ideogram 4 generation node. |

The output is automatically parsed and displayed as a JSON tree in the node (ComfyUI's built-in JsonPreview tool). You can also connect it as a string to downstream text-handling nodes.

The output caption is cleaned of aspect_ratio echoes and any bbox fields, so it's a clean drop-in for Ideogram4Pipeline.__call__(prompt=...) or any equivalent.

Artifact suppression (closest to a "negative prompt")

Ideogram 4's caption schema has no dedicated negative_prompts field (unlike SD/A1111). Instead, the model suppresses noise / blur / artifacts when the positive constraint is stated explicitly:

• Instead of "no noise" → "clean signal, no grain"
• Instead of "no blur" → "sharp focus, no motion blur"
• Instead of "no jpeg" → "high fidelity, no compression artifacts"
• Instead of "no chromatic" → "no chromatic aberration, accurate color"

The suppress_artifacts checkbox (or the standalone Ideogram Suppress Artifacts node) injects a pre-baked snippet that covers the common artifact categories Ideogram 4 can produce.

Second node: Ideogram Suppress Artifacts

A standalone post-processing node that bolts the same artifact-suppression snippet onto any text or JSON caption. Useful when you already have a hand-written or LLM-generated caption and don't want to re-run the magic-prompt API.

| Input | Type | Description | | --- | --- | --- | | caption | multiline string | Either a stringified JSON caption or a plain prompt. | | mode | combo (auto / json / plain text) | auto parses the input as JSON if it looks like JSON, else plain text. |

Output: caption (string, with the snippet applied).

Compatibility

| ComfyUI version | Status | | --- | --- | | V3 (Modern Node Design) | ✅ Primary target. Uses io.ComfyNode, io.Schema, ComfyExtension, comfy_entrypoint(). | | V1 / older installs | ✅ Works. Re-exports NODE_CLASS_MAPPINGS and NODE_DISPLAY_NAME_MAPPINGS for the legacy loader. |

The package has no runtime dependencies beyond comfy_api (bundled with ComfyUI V3) and the Python standard library.

Development

Run the tests locally:

python -m pip install -e .[test]   # if you add a test extra
python -m pytest

There's no test suite in this drop — pull requests welcome.

License

MIT — see LICENSE for the full text.