用途：该技能用于 Ideogram 4（9.3B 开放权重）文生图，核心优势是图像内文字渲染，以及通过结构化 JSON caption 实现精确调色板与边界框布局控制。适合标题卡、缩略图、引言卡、带标题的 CTA 背景、招牌与 logo 等需要清晰文字的场景；无关键文字或只需氛围背景时可改用 FLUX.2。
主要能力：模型基于 JSON caption 训练，纯文本提示只能得到 FLUX 级效果。技能让 Claude 充当提示扩写器，把用户随口描述转成 JSON caption，显式命名每个元素，并支持 hex 品牌色注入与 bbox 区域布局。
使用方式：工具为托管 v4 API 的薄封装，需在 .env 配置 IDEOGRAM_API_KEY（来自 developer.ideogram.ai）。--json 将 caption 作为 json_prompt 提交（推荐，无服务端 magic prompt）；--prompt 提交 text_prompt。示例：uv run tools/ideogram4.py --json caption.json --output title.png；cat caption.json | uv run tools/ideogram4.py --json - --output title.png；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。
可选 4.5：--model 4.5 走 v2 API，同样建议发 JSON caption。--speed 映射质量档：FLASH/TURBO 为 low（$0.03）、DEFAULT 为 medium（$0.06）、QUALITY 为 high（$0.10）。--resolution 需为 auto 或 WIDTHxHEIGHT，边长 32 的倍数、至少 256px、总像素不超过 2048x2048、宽高比不超过 6:1；工具会在调用前校验，不合规退出码 2。
限制：4.5 尺寸须为 32 的倍数，故缩略图仍用 4.0 的 1280x720；4.0 下 FLASH 会返回 HTTP 400；部分预设尺寸不被支持，且未提供源图时还需匹配未公开的 1K/2K 预设，可能仍返回 HTTP 400。完整 schema、键序规则与 bbox 坐标见 prompting.md，示例见 examples.md。