Ideogram 4.0 只在一个格式上训练过，而那不是散文，是结构化的 JSON 描述。自然语言依然能用，但按这套结构写出来的 JSON 对象能做到散文表达不了的事：精确控制颜色、用 bounding box 排布、逐个元素安放文字，以及多次运行之间保持构图。
为什么 Ideogram 4.0 要 JSON
同一个问题，两个官方页面给出的底气不一样。产品文档偏安抚：自然语言提示词照样好用，Magic Prompt 还能把一句简单的描述扩写成结构化描述。开源权重仓库说得更直白：把纯文本提示词直接喂给模型不会work，还可能触发安全警告。这不是矛盾，是入口不同——托管产品替你跑扩写这一步，裸权重不会。
| 手上的活 | 官方给的走法 |
|---|---|
| 快速试想法、方向还不清楚 | 自然语言 |
| 海报、品牌视觉、设计稿 | JSON |
| 精确的文字位置、品牌调色板 | JSON |
| 要跑很多次而版式不走样 | JSON |
| 位置不重要的写实场景 | 自然语言 |
Magic Prompt 替你写 JSON
开源权重包里带了三种 Magic Prompt 配置：ideogram-4-v1 走 Ideogram 自己的托管 API，另有 claude-opus-v1 与 claude-sonnet-v1 走 OpenRouter。Ideogram 那个是默认项，在服务端跑，而且免费，只需要一个 API key。有一条要先说清楚：随包发出来的 Magic Prompt 不是 ideogram.ai 生产环境用的那一个，所以输出会有差别。
三个顶层字段
一份描述有三个顶层字段，其中只有一个必填。
{
"high_level_description": "A medium-shot photograph of a barista pouring latte art in a cosy cafe.",
"style_description": {
"aesthetics": "warm, calm, editorial",
"lighting": "soft window light from the left, gentle falloff",
"photo": "50mm, f/2, shallow depth of field",
"medium": "photograph"
},
"compositional_deconstruction": {
"background": "A wooden counter with a polished espresso machine behind it.",
"elements": [
{
"type": "obj",
"desc": "A ceramic cup held in both hands, latte art holding a clean rosetta."
}
]
}
}high_level_description
一到两句概括整张图。官方标注「强烈建议」，但不是必填——如果只能留一句，留它。
style_description
整个块可以省，块内却很严。它必须恰好带上 photo 或 art_style 之一（插画、绘画、3D 渲染、平面设计走后者），不能两个都要。一旦这个块出现，aesthetics、lighting、medium 也变成必填，只有 color_palette 可以省。medium 的取值例如 photograph、3d_render、graphic_design。
compositional_deconstruction
必填。里面先 background 后 elements，两个都不能少。每个元素要么是对象（"obj"），要么是文字元素（"text"），官方只定义了这两种类型。对象带 desc；文字元素多一个 text 字符串，里面是要渲染的字面文本。
bounding box 与调色板
一个 bounding box 是四个整数，[y_min, x_min, y_max, x_max]，坐标系归一化到 0–1000，原点在左上角。[0, 0, 500, 1000] 占住画面上半部分，[250, 250, 750, 750] 大致居中。不写就交给模型自由摆放。
{
"type": "text",
"bbox": [30, 50, 140, 950],
"text": "FARMERS MARKET",
"desc": "Large all-caps sans-serif headline in warm cream, spanning the top of the poster.",
"color_palette": ["#F5F0E8"]
}颜色在两个层级上生效：整张图在 style_description.color_palette 里最多 16 个大写 #RRGGBB，单个元素最多 5 个。小写和三位简写都会被拒。如果整体色调重要，就把背景色也放进调色板；再配上一组高光和阴影，光照才有东西可依。
两个可以直接复制的示例
下面两段提示词只用官方字段，也都按模型训练时的键序写。第一段是设计海报，每个元素都手动安放。第二段是摄影，什么都没放。
示例一 —— 设计海报，手动安放。 注意这里走的是 art_style 的键序：aesthetics、lighting、medium、art_style、color_palette。
{
"high_level_description": "A bold screen-printed poster for a Saturday farmers market, titled Harvest Row, listing the location and opening time.",
"style_description": {
"aesthetics": "warm, hand-made, mid-century screen print",
"lighting": "flat even light, no dramatic shadow",
"medium": "graphic_design",
"art_style": "two-colour screen print, visible paper grain, heavy geometric letterforms",
"color_palette": ["#1B3A2F", "#E9DFC7", "#C4622D", "#F5F0E8"]
},
"compositional_deconstruction": {
"background": "A single sheet of warm off-white cartridge paper with a fine fibre texture.",
"elements": [
{
"type": "text",
"bbox": [40, 60, 170, 940],
"text": "HARVEST ROW",
"desc": "Very large condensed sans-serif capitals in deep green, spanning the top of the sheet."
},
{
"type": "obj",
"bbox": [200, 120, 720, 880],
"desc": "A simplified illustration of five market stalls under striped awnings, drawn in flat shapes with no outline."
},
{
"type": "text",
"bbox": [740, 60, 830, 940],
"text": "SATURDAY 8AM - 1PM",
"desc": "Medium spaced capitals in burnt orange, centred below the illustration."
},
{
"type": "text",
"bbox": [860, 60, 950, 940],
"text": "OLD MILL YARD",
"desc": "Small light capitals in the same deep green, near the bottom edge."
}
]
}
}每个数字都有理由。主标题占住上面 17%，插画再大也挤不进来。摊位插画纵向从 200 到 720，下面空出一条文字带，字母的下伸部进不去。底部两行文字各自占一条独立的横向切片，这就是换个措辞也不会撞在一起的原因。
示例二 —— 摄影，位置交给模型。 这里走 photo 的键序：aesthetics、lighting、photo、medium、color_palette。
{
"high_level_description": "A close product photograph of a matte black pour-over coffee set on a dark stone surface.",
"style_description": {
"aesthetics": "restrained, premium, low-key",
"lighting": "single soft light from the upper right, deep falloff into shadow",
"photo": "85mm, f/2.8, product still life, gentle film grain",
"medium": "photograph",
"color_palette": ["#141414", "#2B2B2B", "#8C8377", "#D9D2C5"]
},
"compositional_deconstruction": {
"background": "A dark honed stone surface with a soft vertical shadow behind the set, fading into near black.",
"elements": [
{
"type": "obj",
"desc": "A matte black ceramic dripper on a matching glass carafe, both centred, with a thin steam wisp above the cone."
},
{
"type": "obj",
"desc": "A small scattering of roasted coffee beans on the stone in the lower left, softly out of focus."
}
]
}
}去掉框是一次有意的取舍：位置的保证没了，换来的是更自然的光线和纵深，因为没有东西在跟一个硬邦邦的矩形较劲。
键序为什么不是装饰
模型是在键序一致的描述上训练的，所以保持键序能提升结果，而管线会检查。CaptionVerifier 会跑过每一条提示词，对未知键、缺失的必填键和顺序错误的键发出警告。style_description 里有两种键序：摄影走 aesthetics、lighting、photo、medium、color_palette，非摄影走 aesthetics、lighting、medium、art_style、color_palette，两种情况下 color_palette 都留在最后。元素也有自己的键序。
有一个序列化细节专坑 Python 用户。导出时用 separators=(",", ":") 和 ensure_ascii=False，因为全文只有 \uXXXX 转义、没有字面非 ASCII 字符时，验证器会发警告。Ideogram 4.0 提示词指南 里有一条纯文本提示词可以对照，文字渲染那篇 讲的是这套结构怎么处理字体。
JSON 不划算的地方
官方给的建议比这股 JSON 热情要窄。快速试想法、以及位置并不重要的写实场景，官方都归给自然语言。真正该上 JSON 的场合，是这套版式要跑一百次而只换一个词。
官方没有交代的三件事，也别拿第三方的数字去顶：
- 元素数量。 每份描述没有固定上限。密集的文字版式还是压到几个元素以内，因为限制来自摆放的可靠性，不是结构本身。
- 框重叠。 元素框互相重叠时按什么顺序叠，官方没写。
- 质量收益。 只说保持键序能提升生成质量，没有给出量化数字。
两个实操事实收个尾。API 把 json_prompt 当对象接收，一旦提供就关闭 magic prompt，并与 text_prompt 互斥，端点参考 有记录。在产品界面里用 JSON，Magic Prompt 会被自动关掉。
常见问题
JSON 必须自己写吗？ 不必。Magic Prompt 会把纯文本扩写成结构化描述，日常使用从它起步就好。只有当版式、调色板和文字位置需要可复现时，才值得手写。
photo 和 art_style 能同时用吗？ 不能。只能要其中一个，而且选哪个会改变这个块要求的键序。
不写 bbox 会怎样？ 位置就交回给模型。元素照样渲染，只是没被钉在一个矩形里，这在摄影类画面里往往更好。
除了 "obj" 和 "text" 还有别的元素类型吗？ 官方文档里没有。列了 logo、panel 之类类型的页面，描述的是它自己那层封装。上手指南 讲的是浏览器那一侧的做法，想先看模型跑起来可以从那里开始。
三个顶层字段写好，按你选的那个风格块保持键序，只在位置必须站住的地方加框。