Back to Details

ideogram4

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ideogram 4 Skill

Ideogram 4 Skill

Text-to-image generation with Ideogram 4 (9.3B, open-weight, released June 2026). Its superpower is best-in-class in-image text rendering — it beats much larger models (FLUX.2 dev 32B, Qwen-Image 20B, Hunyuan 80B) at rendering legible signage, logos, captions, and multi-line text — plus exact color-palette and bounding-box control.
That advantage is locked behind a structured JSON caption format. A plain-text prompt gets you FLUX-level results and misses the entire point of using this model. This skill teaches Claude to act as the "magic prompt" expander — turning a user's casual request into the JSON caption Ideogram 4 was trained on.
Backend: The toolkit uses Ideogram's hosted v4 API (not self-hosted weights). The API accepts a structured 
json_prompt
, so everything this skill teaches applies directly — Claude builds the caption, the tool posts it as 
json_prompt
. Paid API plans include a commercial license, which the self-hostable weights (non-commercial) do not — that's why we use the API. Cost is ~$0.03/image (turbo) to ~$0.10/image (quality).
使用 Ideogram 4（9.3B，开放权重，于 2026 年 6 月发布）进行文生图。它的 superpower 是业内领先的图内文字渲染——在渲染清晰可读的标牌、Logo、说明文字 和多行文字方面，它胜过许多规模大得多的模型 （FLUX.2 dev 32B、Qwen-Image 20B、Hunyuan 80B）——此外还支持精确的调色板和边界框控制。
这一优势需要通过结构化 JSON caption 格式才能充分发挥。如果只使用纯文本 Prompt， 得到的就是 FLUX 级别的效果，完全没有发挥使用该模型的核心价值。本 Skill 指导 Claude 充当“magic prompt”扩展器——将用户的随口需求转换为 Ideogram 4 训练时使用的 JSON caption。
**后端：**该工具包使用 Ideogram 的 托管 v4 API（而非自托管权重）。API 接受结构化的 
json_prompt
，因此本 Skill 讲授的所有内容都可直接使用——Claude 构建 caption，工具将其作为 
json_prompt
提交。付费 API 套餐包含 商业许可证， 而可自托管权重（非商业用途）不包含该许可证——因此我们使用 API。 成本约为每张 $0.03（turbo）至 $0.10（quality）。

When to Use This Skill

何时使用本 Skill

Reach for Ideogram 4 (over FLUX.2) when the image needs:
  • Legible on-image text — title cards, thumbnails, lower-thirds backgrounds, signage, logos, quote cards, CTAs with a headline baked in
  • Exact brand colors — hex color-palette conditioning, per-element
  • Controlled layout — bounding boxes place text/objects in specific regions
  • Multilingual text in the image
Use FLUX.2 instead when: the image has no critical text, you need commercial-licensed output, or you just want a fast atmospheric background. FLUX takes plain natural-language prompts; Ideogram wants JSON. See 
tools/flux2.py
.
当图片需要以下内容时，优先选择 Ideogram 4（而非 FLUX.2）：
  • 清晰可读的图内文字——标题卡、缩略图、下三分之一标题背景、标牌、Logo、 引用卡，以及内置标题文案的 CTA
  • 精确的品牌色——十六进制调色板条件控制、逐元素控制
  • 受控布局——使用边界框将文字/对象放置在特定区域
  • 图片中的多语言文字
以下情况改用 FLUX.2：图片没有关键文字、你需要拥有商业许可的输出， 或只想快速生成氛围背景。FLUX 接受纯自然语言 Prompt；Ideogram 需要 JSON。参见 
tools/flux2.py
。

The One Thing to Get Right

最关键的一点

Always emit a structured JSON caption, not a plain sentence. The model is trained exclusively on JSON captions that name every element explicitly. Claude is a better expander than Ideogram's free hosted magic-prompt (their own docs note the shipped one "is not the same used in production"), so build the caption yourself using this skill rather than passing raw text.
Minimal valid caption:
json
{"high_level_description":"A sailboat at sunset on calm water.","style_description":{"aesthetics":"serene, warm, golden hour","lighting":"golden hour backlighting","photo":"wide angle, f/8","medium":"photograph","color_palette":["#FF6B35","#F7C59F","#004E89"]},"compositional_deconstruction":{"background":"Calm ocean at low horizon with orange-pink sky.","elements":[{"type":"obj","desc":"White triangular sail silhouetted against the setting sun."}]}}
Full schema, strict key-ordering rules, and the bbox coordinate system are in 
prompting.md
. Worked title-card / thumbnail / quote-card examples are in 
examples.md
.
**始终输出结构化 JSON caption，而不是普通句子。**该模型完全使用 显式命名每个元素的 JSON caption 进行训练。Claude 的扩展效果优于 Ideogram 免费托管的 magic-prompt（其官方文档指出，随附版本“并非生产环境使用的同一版本”）， 因此应使用本 Skill 自行构建 caption，而不是直接传入原始文本。
最小有效 caption：
json
{"high_level_description":"A sailboat at sunset on calm water.","style_description":{"aesthetics":"serene, warm, golden hour","lighting":"golden hour backlighting","photo":"wide angle, f/8","medium":"photograph","color_palette":["#FF6B35","#F7C59F","#004E89"]},"compositional_deconstruction":{"background":"Calm ocean at low horizon with orange-pink sky.","elements":[{"type":"obj","desc":"White triangular sail silhouetted against the setting sun."}]}}
完整 Schema、严格的键顺序规则以及 bbox 坐标系见 
prompting.md
。 标题卡/缩略图/引用卡的完整示例见 
examples.md
。

Quick Reference — 
tools/ideogram4.py

快速参考——
tools/ideogram4.py

Thin wrapper over Ideogram's hosted v4 API. Needs 
IDEOGRAM_API_KEY
in 
.env
(key from developer.ideogram.ai). 
--json
posts the caption as the API's 
json_prompt
field (no server-side magic prompt — Claude is the expander); 
--prompt
posts 
text_prompt
.
bash
undefined
Ideogram 托管 v4 API 的轻量封装。需要在 
.env
中配置 
IDEOGRAM_API_KEY
（密钥来自 developer.ideogram.ai）。
--json
会将 caption 作为 API 的 
json_prompt
字段提交（不启用服务端 magic prompt——由 Claude 负责扩展）；
--prompt
则提交 
text_prompt
。
bash
undefined

Hand-authored JSON caption (the recommended path for text/layout) — Claude writes caption.json

Hand-authored JSON caption (the recommended path for text/layout) — Claude writes caption.json

uv run tools/ideogram4.py --json caption.json --output title.png
uv run tools/ideogram4.py --json caption.json --output title.png

Caption from stdin (Claude can pipe it directly)

Caption from stdin (Claude can pipe it directly)

cat caption.json | uv run tools/ideogram4.py --json - --output title.png
cat caption.json | uv run tools/ideogram4.py --json - --output title.png

Plain prompt — Ideogram's server-side magic prompt expands it (weaker; prefer --json)

Plain prompt — Ideogram's server-side magic prompt expands it (weaker; prefer --json)

uv run tools/ideogram4.py --prompt "Title card: 'AI ENGINEERING REVIEW' bold white on dark" --output title.png
uv run tools/ideogram4.py --prompt "Title card: 'AI ENGINEERING REVIEW' bold white on dark" --output title.png

Inject brand hex colors into the caption's palette (JSON mode)

Inject brand hex colors into the caption's palette (JSON mode)

uv run tools/ideogram4.py --json caption.json --brand digital-samba --output cta.png
uv run tools/ideogram4.py --json caption.json --brand digital-samba --output cta.png

Quality tier + resolution

Quality tier + resolution

uv run tools/ideogram4.py --json caption.json --speed QUALITY --resolution 2048x2048 --output slide.png
undefined
uv run tools/ideogram4.py --json caption.json --speed QUALITY --resolution 2048x2048 --output slide.png
undefined

Ideogram 4.5 (opt-in)

Ideogram 4.5（可选启用）

--model 4.5
sends the same flags to Ideogram 4.5 on the v2 API (
POST /v2/image/generate/ideogram-4-5
, multipart like the v1 call). It has been run live: JSON captions render near-perfect text; plain prompts add garbled filler text, so always send a JSON caption to 4.5. Ideogram 4 stays the default because 4.5 sizes must be multiples of 32, which rules out exact YouTube 1280x720 (
/thumbnail
uses 4.0 for that).
bash
uv run tools/ideogram4.py --model 4.5 --json caption.json --speed QUALITY --resolution 1440x2560 --output card.png
  • Prompt: both modes go in 4.5's single 
    prompt
    field. 
    --json
    sends the caption as compact JSON. 4.5 reads the Ideogram 4 caption format, and a valid caption skips server-side magic prompt. 
    --prompt
    text is expanded by magic prompt, as on v1.
  • --speed
    maps to 
    quality
    : TURBO, DEFAULT and QUALITY at the same price as on Ideogram 4, and FLASH, which has no Ideogram 4 price, to low (Ideogram's list prices, checked 2026-10-12; 1K and 2K sizes cost the same):
    --speed
    		4.5 
    quality
    		Per image
    FLASH, TURBO
    low
    		$0.03
    DEFAULT (the default)
    medium
    		$0.06
    QUALITY
    high
    		$0.10
    4.5's 
    very_low
    tier needs source images, so the tool never sends it. On 
    --model 4
    , FLASH is still sent as is, but Ideogram's docs say it currently returns HTTP 400.
  • --resolution
    is sent as 
    size
    :     
    auto
    , or WIDTHxHEIGHT with both sides multiples of 32 and at least 256px, at most 2048x2048 pixels in total, and an aspect ratio of at most 6:1. Omit it and Ideogram picks a size from the prompt. The tool checks these rules before calling the API and exits 2 when a size breaks them. 
    1440x2560
    (the 9:16 card size) and 
    2048x2048
    pass. Six Ideogram 4 presets don't, and the error suggests a replacement: 720x1280 (1440x2560), 1280x720 (2560x1440), 720x1440 (1440x2880), 1440x720 (2880x1440), 1296x3168 (1280x3072), 3168x1296 (3072x1280). Without source images Ideogram also needs one of its supported 1K/2K presets, a list it doesn't publish, so a size that passes the checks can still get an HTTP 400.
--model 4.5
会通过 v2 API 将相同的参数发送给 Ideogram 4.5 （
POST /v2/image/generate/ideogram-4-5
，采用与 v1 调用相同的 multipart 格式）。该功能已经过实际运行验证： JSON caption 可渲染近乎完美的文字；纯文本 Prompt 则会添加乱码填充文字，因此始终 向 4.5 发送 JSON caption。Ideogram 4 仍为默认选项，因为 4.5 的尺寸必须是 32 的倍数， 这会排除精确的 YouTube 1280x720 尺寸（
/thumbnail
使用 4.0）。
bash
uv run tools/ideogram4.py --model 4.5 --json caption.json --speed QUALITY --resolution 1440x2560 --output card.png
  • **Prompt：**两种模式都写入 4.5 单一的 
    prompt
    字段。
    --json
    以紧凑 JSON 形式发送 caption。 4.5 可读取 Ideogram 4 的 caption 格式，有效 caption 会跳过服务端 magic prompt。 
    --prompt
    文本则像 v1 一样由 magic prompt 扩展。
  • --speed
    映射到 
    quality
    ：TURBO、DEFAULT 和 QUALITY 与 Ideogram 4 价格相同； FLASH 在 Ideogram 4 中没有对应价格，因此映射为 low（依据 Ideogram 公布的价目表， 检查日期为 2026-10-12；1K 和 2K 尺寸价格相同）：
    --speed
    		4.5 
    quality
    		每张图片
    FLASH, TURBO
    low
    		$0.03
    DEFAULT（默认）
    medium
    		$0.06
    QUALITY
    high
    		$0.10
    4.5 的 
    very_low
    档位需要源图像，因此工具绝不会发送该档位。在 
    --model 4
    下， FLASH 仍会按原值发送，但 Ideogram 文档指出目前会返回 HTTP 400。
  • **
    --resolution
    会作为 
    size
    发送：**可设为 
    auto
    ，或 WIDTHxHEIGHT；宽高两侧均须为 32 的倍数且不少于 256px，总像素不超过 2048x2048，宽高比不超过 6:1。 省略该参数时，Ideogram 会根据 Prompt 选择尺寸。工具会在调用 API 前检查这些规则， 尺寸不合规时以状态码 2 退出。
    1440x2560
    （9:16 卡片尺寸）和 
    2048x2048
    可通过。六个 Ideogram 4 预设尺寸无法通过，错误信息会建议替换为： 720x1280 (1440x2560)、1280x720 (2560x1440)、720x1440 (1440x2880)、1440x720 (2880x1440)、 1296x3168 (1280x3072)、3168x1296 (3072x1280)。在没有源图像时，Ideogram 还需要使用其支持的 1K/2K 预设之一，但官方未公布该列表，因此即使尺寸通过检查，仍可能收到 HTTP 400。

Key Files

关键文件

  • prompting.md
    — full JSON schema, strict key ordering, bbox coordinate system, palette rules
  • examples.md
    — worked captions for title cards, thumbnails, quote cards, brand CTAs
  • prompting.md
    ——完整 JSON Schema、严格键顺序、bbox 坐标系、调色板规则
  • examples.md
    ——标题卡、缩略图、引用卡、品牌 CTA 的实战 caption

Video Production Fit

视频制作适用场景

Ideogram 4's niche in the toolkit is slides and thumbnails with baked-in text, where FLUX and LTX-2 fail (both render garbled text). Natural pairings:
Use caseWhy Ideogram 4
Title-card / CTA background with headline textLegible text + exact brand hex colors in one pass
YouTube/social thumbnail with a punchy phraseBig readable text is its strongest suit
Quote card / stat cardMulti-line text + layout control via bboxes
Signage/logos inside a product-demo sceneIn-image text other models can't render
Then feed the still into Remotion (
<OffthreadVideo>
/
Img
) or animate it with 
tools/ltx2.py --input
.
Ideogram 4 在该工具包中的定位是生成带内置文字的幻灯片和缩略图，而 FLUX 和 LTX-2 在这类任务中会失败（两者都会渲染出乱码文字）。适合搭配的场景包括：
使用场景选择 Ideogram 4 的原因
带标题文字的标题卡/CTA 背景一次生成即可兼得清晰文字与精确的品牌十六进制颜色
YouTube/社交媒体配有醒目短语的缩略图大字号可读文字是其最强项
引用卡/数据卡支持多行文字，并通过 bbox 控制布局
产品演示场景中的标牌/Logo其他模型无法渲染的图内文字
随后可将静态图输入 Remotion（
<OffthreadVideo>
/
Img
），或使用 
tools/ltx2.py --input
为其添加动画。