scenario-ideogram

Scenario Ideogram Image

概述

Scenario 上的 Ideogram 图像系列由多个用途单一的成员组成，而不是一个具有多种模式的模型： 4.5 用于生成必须让图像内文字清晰可读的图像，以及参考图引导的编辑；4.5 Precise Edit 用于只更改一处并保持其余部分不变；V3 Generate Transparent 用于原生 alpha 输出； V3 Layerize Text 用于将扁平图形转换为可编辑的文字图层；Character 用于在不同场景中保持同一身份； Remove Background 用于抠图。V4 仍会出现在搜索结果中，但在编写本文时已标记为弃用，建议改用 4.5。这些成员在机制上几乎没有共通之处：同一个概念在不同成员中的名称、大小写和允许值都可能不同，因此请通过 search 发现成员，并将其 model_schema_get 视为规范。

连接和核心流程：请参阅此代码库中的 scenario 技能；与模型无关的图像处理（尺寸系列、参考图数量、蒙版）：请参阅 scenario-image 技能；与其他系列进行对比测试：请参阅 scenario-model-comparison。如果你的可用技能中缺少此处提到的同级技能，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；如需无人值守地继续，请依据工具架构操作并指出缺少该技能。

快速参考

根据任务选择成员（名称来自实时架构，能力上限为编写本文时的情况）：

成员	用途	重要输入
4.5	文字密集型生成、参考图编辑	prompt、referenceImages（最多 5 张，第一张为源图）、mask、aspectRatio（auto、source，以及从 3:1 到 1:3 的 25 种比例）、resolution（1K、2K）、quality、magicPrompt、numOutputs（最多 8 张）
4.5 Precise Edit	只更改一处，保持其余部分不变	image（输出保留原尺寸）、mask、referenceImages（最多 4 张引导图）、quality（默认 medium）、numOutputs（最多 8 张）
V3 Generate Transparent	原生 alpha 输出	prompt、negativePrompt、aspectRatio（15 种比例）、renderingSpeed（新增 FLASH）、expandPrompt、numOutputs（最多 8 张）、seed
V3 Layerize Text	将扁平图形转换为图层	image、可选的 prompt、每个层级（H1、H2、Body、Small）对应的 fontName* 或 fontFile*、seed
Character	同一角色，全新场景	prompt、characterReferenceImage、styleType（Auto、Fiction、Realistic）、aspectRatio 或 resolution、image 与 mask、renderingSpeed（Default、Turbo、Quality）、seed
Remove Background	抠图并输出透明 PNG	image（上限 10MB）

不同成员之间不能通用任何设置。蒙版的含义也因成员而异：在 4.5 和 Precise Edit 中，白色标记要编辑的区域；在 Character 中，黑色区域会重新绘制，白色区域保持不变。只有 V3 Transparent 接受 negativePrompt。V3 Transparent 的 renderingSpeed 使用全大写形式；Character 则使用标题式大小写，其中间档为 Default。

4.5：档位、尺寸及费用

quality 是两个 4.5 成员的价格调节项（very_low、low、medium、high；very_low 需要输入图像，Precise Edit 的 image 可满足此要求，而 4.5 会将其作为 referenceImages 条目）。编写时，dry_run 报出的 low、medium 和 high 费用分别为 7.75、13.75 和 41.75 CU，Precise Edit 的 very_low 为 3.75 CU；1K 和 2K 的费用相同，0.4 MP、4.3 MP 或 8.3 MP 的源图也一样；实际计费的任务均比每项预估低 1.75 CU。4.5 默认为 high，这是最高且最贵的档位；Precise Edit 默认为 medium，而其 high 会以三倍价格从多个候选结果中选出最佳结果。不同系列的档位名称并不对应：Ideogram 的 high 是其上限，而 GPT Image 2.5 的 high 是五个档位中的第三档，价格接近 Ideogram 的 medium。比较不同系列时，应按相同价格对比，而不是按相同档位名称对比，并对确切的负载运行 dry_run。

编写时观察到的 2K 输出尺寸：2048 × 2048（1:1）、2560 × 1440（16:9）、2880 × 1440（2:1）、2944 × 1152（23:9）、3072 × 1024（3:1），因此长边最高约为 3072，且没有 4K。1K 约为 1 MP（16:9 返回 1280 × 720），仅支持 1:1、4:5、3:4、2:3、5:8、9:16、1:2 及其横向对应比例；3:1 的 1K 请求会通过 dry_run，但运行时会失败，并提示如何修正。不在列表中的比例（4:1）会返回 400 错误，并列出允许的值。mask 需要 aspectRatio: "auto"。

保持画布不变的编辑

编辑时，4.5 的 aspectRatio: "source" 和 Precise Edit 的每次运行都会返回与源图完全相同的像素尺寸，即使尺寸不符合比例列表也一样：一张 1326 × 313（4.24:1）的转面图，两者都返回了 1326 × 313；而 auto 会将其重建为完整的 3072 × 1024 场景。若编辑后的文件必须原样放回版面、精灵图集或页面模板，请使用此设置。像替换标题这样的局部修改，在 Precise Edit 上无需 mask：使用默认的 medium 且不提供掩码时，场景的其余部分保持不变。GPT Image 系列会改为在此类源图两侧添加白边（参见 scenario-gpt-image）。

编写时进行的一次单样本对比测试中，使用相同的源图与 GPT Image 2.5 对比，4.5 成员在替换标志文字和添加、移除物体的编辑中，改动区域外受影响的像素少了两到四倍；在生成指定的绘画风格时也更贴近要求（如水彩风格重绘、丙烯风格风景画；实际使用中，铅笔素描也有同样的表现）。GPT Image 2.5 在写实产品图、遵循角色简介，以及材质和颜色修改方面表现更好：要求生成抛光金色盔甲时，两个 4.5 成员都生成了橄榄色黄铜；而 Precise Edit 还把提示词要求保留的剑重新着了色。应根据任务选择模型，并在每条编辑提示词中写上“其他所有内容都保持完全不变”，再列出必须保留的内容。

需要精确文本时关闭扩写

默认情况下，生成器会在生成前重写提示词，这有助于处理简短的探索性提示词，却会损害该系列的一项专长：重写可能会改写必须准确呈现的文案。图像包含文字时，请关闭此功能（4.5 使用 magicPrompt: "off"，V3 Transparent 使用 expandPrompt: false），将每段文案加上引号，并说明其位置和样式（例如，“标题文字为‘GRAND OPENING’，以粗体窄体大写字母横跨顶部”）。magicPrompt 仅适用于文生图：4.5 会将所有编辑请求转换为结构化指令。

两种实现透明背景的方式

原生方式：V3 Generate Transparent 直接写入 alpha 通道，因此图标、贴纸和 UI 元素可直接用于合成。抠图方式：使用 4.5 生成图像，再对结果运行 Remove Background；它会重建边缘像素并添加部分透明度，而不是进行分割，因此能保留头发、毛发和玻璃。若素材本身就是孤立元素，请选择原生方式；若更看重排版或整体质量，请选择抠图方式。4.5 没有背景字段，因此提示“透明背景”只会生成不透明图像。

示例：可本地化的海报

1. 使用 search，设置 target="models"、query="ideogram"、public=true。成员会作为单独的命中项返回；按名称匹配，例如用于排版的 model_ideogram-v4-5（编写本文时的实时命中项：每次会话都要重新发现）。
2. 使用该 ID 调用 model_schema_get：先查看字段名称、允许的值和默认值。
3. 使用该 model_id 调用 model_run，设置 dry_run=true 和 parameters={"prompt": "Retro travel poster, warm dusk palette. The headline reads \"KYOTO IN BLOOM\" in bold serif across the top; caption \"April 2027\" bottom right.", "aspectRatio": "9:16", "resolution": "2K", "quality": "high", "magicPrompt": "off", "numOutputs": 2} 以估算费用。
4. 再次调用 model_run，设置 wait=false，然后使用返回的任务 ID 调用 jobs_wait；超时时使用 pending_job_ids 再次调用，切勿第二次调用 model_run。
5. 使用 asset_display 查看输出并选出一个。
6. 要让文案可编辑，请用相同方式发现 Layerize 成员（编写本文时为 model_ideogram-v3-layerize-text），读取其 schema，然后调用 model_run，并设置 parameters={"image": "<poster asset id>"}：生成的资源 ID 可直接传入文件输入，无需重新上传。输出包括去除文字的底图，以及带有角色、位置和内容的文本块。
7. 调用 jobs_wait，然后调用 asset_display 和 asset_download。

常见错误

• 将一个成员的参数块带到另一个成员：magicPrompt 和 resolution 属于 4.5；V3 Transparent 需要 aspectRatio 和 expandPrompt；Precise Edit 的源图参数是 image，而不是 referenceImages。
• 草稿阶段让 4.5 使用较高的默认值：先选 low 或 medium，最终稿再选 high。
• 提示词中有精确文案，却保持扩展开启：模型看到文字之前，改写可能会更改文案。
• 画布必须保持不变时，编辑时却设置 aspectRatio: "auto"：请使用 source 或 Precise Edit。
• 在 4.5 上提示使用透明背景：改用 V3 Transparent 生成，或串联 Remove Background。
• 对 Character 进行修复时提供了 image 却未提供 mask：两者必须同时提供；characterReferenceImage 仍为必填项，修复时会忽略尺寸字段。
• 在 Layerize 上同时设置 fontNameH1 和 fontFileH1：每个层级的字体只能来自字体名称或字体文件，不能两者兼用。upload_asset 没有字体类型，因此只有本地字体文件时，请使用字体名称路径并说明这一限制。