Ideogram 4 技能
使用 Ideogram 4（9.3B 参数，开放权重，2026 年 6 月发布）进行文本到图像生成。其超能力是业界最佳的图像内文字渲染——它在渲染可读标牌、徽标、字幕和多行文本方面击败了更大的模型（FLUX.2 dev 32B、Qwen-Image 20B、Hunyuan 80B）——同时支持精确的颜色调色板和边界框控制。
这一优势被锁定在结构化的 JSON 提示格式之后。纯文本提示只能得到 FLUX 级别的结果，完全浪费了使用此模型的初衷。本技能教导 Claude 充当“魔法提示”扩展器——将用户的随意请求转化为 Ideogram 4 训练所使用的 JSON 提示。
后端： 本工具包使用 Ideogram 的托管 v4 API（而非自托管权重）。该 API 接受结构化的
json_prompt，因此本技能教授的所有内容都直接适用——Claude 构建提示，工具将其作为json_prompt提交。付费 API 计划包含商业许可，而自托管权重（非商业许可）则不包含——这就是我们使用 API 的原因。费用约为每个图像 $0.03（快速）到 $0.10（高质量）。
何时使用此技能
当图像需要可读的图像内文字时（优于 FLUX.2 等模型），请使用 Ideogram 4：
- 可读的图像内文字 — 标题卡、缩略图、底部三分之一背景、标牌、徽标、引用卡、带有标题的行动号召
- 精确的品牌颜色 — 十六进制颜色调色板条件化，每个元素独立控制
- 受控布局 — 边界框将文本/对象放置在特定区域
- 图像中的多语言文本
在以下情况使用 FLUX.2：图像中没有关键文本，需要商业许可输出，或者只需要一个快速的环境背景。FLUX 接受纯自然语言提示；Ideogram 需要 JSON。请参阅 tools/flux2.py。
必须做对的一件事
始终输出结构化的 JSON 提示，而不是一个简单的句子。 该模型仅基于明确命名每个元素的 JSON 提示进行训练。Claude 是比 Ideogram 的免费托管“魔法提示”更好的扩展器（他们的官方文档指出提供的魔法提示“与生产环境中使用的不同”），因此请使用此技能自己构建提示，而不是传递原始文本。
最小有效提示：
{"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、严格的键顺序规则以及边界框坐标系统位于 prompting.md 中。已完成的标题卡 / 缩略图 / 引用卡示例位于 examples.md 中。
快速参考 — tools/ideogram4.py
对 Ideogram 托管 v4 API 的轻量封装。需要在
.env文件中设置IDEOGRAM_API_KEY（密钥来自 developer.ideogram.ai）。--json将提示作为 API 的json_prompt字段提交（无服务器端魔法提示 — Claude 是扩展器）；--prompt提交text_prompt。
# 手动编写的 JSON 提示（文本/布局的推荐方式）—— Claude 编写 caption.json
uv run tools/ideogram4.py --json caption.json --output title.png
# 从标准输入读取提示（Claude 可以直接管道传输）
cat caption.json | uv run tools/ideogram4.py --json - --output title.png
# 纯文本提示——Ideogram 的服务器端魔法提示进行扩展（效果较弱；推荐使用 --json）
uv run tools/ideogram4.py --prompt "Title card: 'AI ENGINEERING REVIEW' bold white on dark" --output title.png
# 将品牌十六进制颜色注入提示的调色板（JSON 模式）
uv run tools/ideogram4.py --json caption.json --brand digital-samba --output cta.png
# 质量级别 + 分辨率
uv run tools/ideogram4.py --json caption.json --speed QUALITY --resolution 2048x2048 --output slide.png
Ideogram 4.5（可选）
--model 4.5 将相同的标志发送到 Ideogram 4.5 v2 API（POST /v2/image/generate/ideogram-4-5，与 v1 调用类似的多部分请求）。它已在线测试通过：JSON 提示渲染出近乎完美的文本；纯文本提示会添加乱码填充文本，因此始终向 4.5 发送 JSON 提示。Ideogram 4 保持为默认值，因为 4.5 的分辨率必须是 32 的倍数，这使得无法使用精确的 YouTube 1280x720（/thumbnail 为此使用 4.0）。
uv run tools/ideogram4.py --model 4.5 --json caption.json --speed QUALITY --resolution 1440x2560 --output card.png
-
提示： 两种模式都进入 4.5 的单个
prompt字段。--json将提示作为紧凑的 JSON 发送。4.5 能够读取 Ideogram 4 的提示格式，且有效的提示会跳过服务器端魔法提示。--prompt文本会被魔法提示扩展，如同 v1 一样。 -
--speed映射到quality：TURBO、DEFAULT 和 QUALITY 的价格与 Ideogram 4 相同，FLASH（Ideogram 4 没有此价格）映射到 low（基于 Ideogram 公布的价格，检查于 2026-10-12；1K 和 2K 尺寸价格相同）：--speed4.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 会根据提示选择尺寸。工具在调用 API 前会检查这些规则，如果尺寸不符合规则则退出并返回代码 2。1440x2560（9:16 卡片尺寸）和2048x2048通过检查。六个 Ideogram 4 预设尺寸不符合要求，错误信息会建议替换值：720x1280（1440x2560），1280x720（2560x1440），720x1440（1440x2880），1440x720（2880x1440），1296x3168（1280x3072），3168x1296（3072x1280）。在没有源图像的情况下，Ideogram 还需要其支持的 1K/2K 预设之一，但 Ideogram 并未公布此列表，因此即使尺寸通过检查，仍可能收到 HTTP 400。
关键文件
prompting.md— 完整的 JSON schema、严格的键顺序、边界框坐标系统、调色板规则examples.md— 标题卡、缩略图、引用卡、品牌行动号召的已完成提示示例
视频制作场景
Ideogram 4 在该工具包中的定位是包含嵌入文本的幻灯片和缩略图，而 FLUX 和 LTX-2 在这方面有所不足（两者都会渲染出乱码文本）。自然的搭配场景：
| 用例 | 为何选择 Ideogram 4 |
|---|---|
| 带有标题文本的标题卡 / 行动号召背景 | 一步完成可读文本 + 精确的品牌十六进制颜色 |
| YouTube / 社交媒体的带有醒目短语的缩略图 | 大型可读文本是其最强项 |
| 引用卡 / 数据统计卡 | 多行文本 + 通过边界框进行布局控制 |
| 产品演示场景中的标牌/徽标 | 其他模型无法渲染的图像内文字 |
然后，将生成的静态图像输入 Remotion（使用 <OffthreadVideo>/<Img>）或使用 tools/ltx2.py --input 进行动画处理。