scenario-image

场景图像生成与编辑

概述

Scenario 运行数百种图像模型，分为 txt2img（根据提示词生成）和 img2img（编辑、重绘风格、局部重绘、放大）。scenario 技能会介绍这套流程。图像任务出问题时，通常是因为各模型的契约不同：即使两个模型执行相同任务，它们的尺寸字段、提示词长度限制和参考图上限也可能不同，因此每次都要读取 model_schema_get。各模型系列的契约（尺寸系列、参考图上限、编辑模式）：scenario-seedream、scenario-gpt-image、scenario-gemini-image、scenario-ideogram、scenario-reve、scenario-luma-image、scenario-mai-image、scenario-grok-imagine-image。放大、评分、特效、扩展、调整尺寸及其他工具模型：参见 scenario-image-editing。让一组图像保持统一风格：参见 scenario-consistency。使用多张参考图生成一张图，并为每张参考图指定不同用途：参见 scenario-multi-reference。精灵图、图标和图块集：参见 scenario-game-assets。如果当前可用技能中缺少此处提到的某个同系列技能，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；在无人值守的情况下，请根据工具架构继续操作，并指出缺失项。

快速参考

需求	调用
选择模型	使用 recommend，设置 capability="txt2img" 或 "img2img"；或使用 search（target="models"、public=true）
读取契约	每次调用 model_run 之前使用 model_schema_get
估算成本	使用 model_run 并设置 dry_run=true；cost_impact: true 会标出影响价格的字段
生成或编辑	使用 model_run，然后使用 jobs_wait
审核并保存	使用 asset_display，然后使用 asset_download（默认格式为 png，也可用 webp、jpg）
精确输出像素尺寸	以最接近的可达尺寸生成，然后使用 model_scenario-resize-image（参见“输出精确尺寸”）

局部重绘和扩图属于 img2img，不是独立能力。

导致任务失败的三个字段

这三个字段因模型而异，因此应从架构中读取，不能沿用之前任务的值：

• 尺寸。 尺寸没有通用格式：可能是带有 min、max 和可取步长 step 的数值型 width 和 height；可能是枚举类型（aspectRatio、以百万像素或 K 级别表示的 resolution，或混合级别和像素尺寸的 size）；也可能只有纵横比，此时无法达到精确像素尺寸。向枚举字段传入像素值，或提供不符合步长的值，都会被拒绝。如果架构无法表示所需尺寸，应说明它能达到的尺寸，而不是默默取整。
• 提示词长度。 提示词字段的 max_length 从大约 2000 个字符到 32000 个字符不等。适用于一个模型的提示词，换到下一个模型就可能触发 400 错误。
• 参考图。 字段名称（referenceImages、image）、上限和数量规则都以架构为准，字段名称本身不能说明这些信息：在某些模型中，名为 referenceImages 的字段实际上只接受单个标量文件。只有架构注明 array: true 时才传入数组；即使只有一张图片，也要在这种情况下传入数组，因为裸字符串会被静默丢弃，随后任务虽然成功，却会忽略参考图。使用多张参考图时，应在提示词中说明每张图分别对应什么。

批量数量字段（numOutputs、numImages）会重复使用同一条提示词，因此生成的是变体，而非一组不同内容的图像。凡是每个项目需要有所不同的情况，都必须为每个项目单独调用一次 model_run。

精确调整尺寸

游戏内素材需要精确的像素尺寸（如 210x600 横幅、256x256 图标），生成式模型可能无法直接支持。数值尺寸字段会按网格对齐（常见的 step 为 16，范围由 min 和 max 限定），枚举字段提供固定档位，有些成员则会悄悄将低于其下限的请求替换为其他尺寸：某个成员收到 512x128 后返回了 1408x480，且没有报错。目标尺寸不受支持时，请以最接近且不小于目标尺寸的可用尺寸生成；在可能的情况下匹配宽高比，并遵守所有架构限制（对于最低尺寸为 1K 的成员，256x256 图标可生成 1024x1024；对于 210x600 横幅，只有当两个尺寸都符合该成员的限制时才可生成 224x640），然后使用 model_scenario-resize-image 完成调整。这个固定 ID 对应 Scenario 唯一的确定性精确尺寸调整工具，无需通过发现流程重新推导：即使只有一个素材，images 也必须是数组；设置 width 和 height，并将 fit 设为 cover，以填满目标尺寸并居中裁切溢出部分，或设为 stretch，以精确匹配尺寸，但会产生变形（默认的 contain 可能返回小于目标尺寸的图片）。只有在明确要求高画质或有文档记录的模型指导时，才选择更大的源图，而不要凭空假设某个系列的最佳尺寸。使用 asset_get 确认结果。缩小图片可能会让模糊不那么明显；放大则无法恢复缺失的细节。

模糊问题也需要同样谨慎处理：多个成员默认使用 1K 档位，但架构中提供了更高档位，因此新生成时应明确设置分辨率或 quality 档位。要保留已批准的画面，请放大确切的保留版本（scenario-image-editing）；重新运行其生成配方可能会改变图片。对于自定义训练的成员，在提高步数前，请对照其架构和模型指导检查相关指导与步数。如果输出过于照字面生成，请将提示词拆分为固定内容和模型可以自行创作的内容，并明确说明。自行创作的细节也必须遵守固定约束（例如，不含文字的需求中不能出现装饰性符文）；运行前，prompt_spark 可将简略的需求扩展为符合模型风格的提示词。

提示词措辞

图片中的文字：请逐字引用每段文字，并说明其位置（“标签写着‘NORTH’，位于顶部中央”）；文字尽量简短；如果某个词总是生成错误，请逐字母拼写（NORTH：N、O、R、T、H）；未加引号的文案可能会被改写。必须逐字准确的文案（价格、法律声明）应使用 scenario-text-overlay 合成，绝不要通过提示词生成。电影剧照或电影感提示词，或以文字描述的宽高比（2.39:1），可能会让画面像素中嵌入黑边；asset_get 的尺寸检查会将其视为图片内容。请要求画面从边缘到边缘完整铺满，不加信箱式黑边，也不加黑边，并且只在尺寸字段中设置宽高比。画面中出现皮肤时，请描述其质感（可见毛孔、细小汗毛、微弱高光），否则生成结果往往会被磨皮得过于光滑。

修改指令应明确说明更改内容，并锁定其余部分：“把椅子放到阳光照耀的露台上；椅子的形状、布料和阴影保持完全不变。”如果要修改文字，则写：“只将标题改为‘NORTH’，字体、字号和位置保持不变。”未明确指定的内容都可能发生变化。

示例：替换产品图片上的标签

1. 使用 capability="img2img" 和用户自己的表述作为 prompt 调用 recommend。按 scenario 技能的指示处理 next_step，绝不运行 requires_plan_upgrade 条目。
2. 对产品照片调用 upload_asset，然后调用 upload_asset_complete，后者会返回 asset_id。只有约 100KB 以下的内联路径无需第二次调用。
3. 对选定项调用 model_schema_get：查看参考图字段的名称和上限、使用的尺寸系列、提示词的 max_length，以及是否存在 mask 字段。
4. 对于带蒙版的编辑，在构建任何内容之前，先阅读 mask 字段自身的说明。不同蒙版不能互换：有的模型需要尺寸与源图完全一致并带 Alpha 通道的图像，有的模型需要由模型自行缩放的黑白图像，而且需要涂抹的像素也各不相同。手头没有蒙版时，可使用 capability="img2img" 和用户自己的表述描述蒙版需求，调用 recommend，以查找接受简短名词短语或边界框、并为每个对象返回一个蒙版的分割模型；目录中的大多数分割模型分割的是 3D 网格，因此请检查选定项的 capabilities。若没有合适的约定，则由指令编辑器通过文字限定编辑范围。
5. 使用架构定义中的字段名称调用 model_run：传入提示词、参考图（仅当架构定义标注 array: true 时才用数组包装），以及架构定义所列的蒙版和尺寸字段。需要关注成本时，先使用 dry_run=true。
6. 调用 jobs_wait；其约 180 秒的超时不代表出错，因此请使用返回的 pending_job_ids 作为 job_ids 再次调用。然后调用 asset_display 进行检查，再调用 asset_download 保存。

常见错误

• 架构定义将参考图字段标记为 array: true，却传入普通字符串：该值会被丢弃且不会报错，输出会悄无声息地忽略它。
• 将一个模型的参数块套用到另一个模型：aspectRatio 和 width/height 很少共存，且未知字段会被拒绝。
• 重试 403 ModelAccessRestrictedError：其中会指出 modelId 和 requiredPlan，因此应提示用户升级或选择其他模型。
• 提示“透明背景”：扩散模型的输出是不透明的。若架构定义中有 background 字段，请使用该字段；否则之后再运行背景移除模型。
• 对已获认可的画面使用更高尺寸档重新运行，并期待画面更清晰：许多模型不提供 seed；即使提供了，只有其他所有字段均保持不变时，才能复现一次运行，因此重新运行会生成新图像。先用成本最低的档位起草，再放大确切选定的图像（scenario-image-editing）。
• 假设模型能生成指定像素尺寸：有些模型只提供宽高比，不提供其他选项；另一些则会悄悄将低于其下限的尺寸替换为其他尺寸。先生成接近目标的图像，再调整尺寸（精确匹配尺寸），并使用 asset_get 确认最终结果；它会报告 properties.width 和 properties.height，而 jobs_wait 只返回资源 ID。