image_multi_reference
Generate a new image by merging 2-10 reference images with a prompt, combining visual information from all inputs into one composite. Ideal for fusing product angles, styles, or graphics.
Instructions
多图融合参考 → 输出 1 张新图；当前线路支持 1K/2K/4K。
[WHAT] 输入 2-10 张参考图 + prompt，模型综合所有图的视觉信息后画 1 张全新的图。 与 image_batch_edit 的本质区别：batch 是 N 进 N 出（每张独立改），此 tool 是 N 进 1 出（综合参考）。
[WHEN TO USE]
用户："这几张是同一产品的不同角度，按这个风格画一个新角度" → 用此 tool。
用户："这些是我喜欢的风格，画一张类似风格的 X" → 用此 tool。
用户："这是 logo 主图，这是辅助图，做成海报" → 用此 tool。
如果用户只想"逐张修改" → 改用 image_batch_edit。
如果用户只有 1 张图 → 改用 image_edit。
如果用户没提供任何参考图 → 改用 image_generate。
[当前线路]
参考图 4K 的旧线路硬阻断已移除；所有尺寸统一走 /v1/images/edits + image[]。
2K/4K 自动使用 gpt-image-2-openai，并通过跨进程锁串行请求高质量队列。
[路由实现]
固定走 /v1/images/edits + 多个 image[] 字段。米醋唯一真正消费输入图的端点 （实测 image_tokens 线性 = 560×N）。旧的 generations + image_urls 被米醋静默忽略 （image_tokens=0，等于纯文生图，参考图不起作用），已弃用。
自动切高质量线路：max edge ≥1600 → gpt-image-2-openai
Images API 返回错误时直接报错，不把图像模型转发到不兼容的 /v1/chat/completions。
[LIMITS]（当前真实状态，会变化）
image_paths 长度 2-10 张。
1K 档：多图 N=2..10 历史实测成功，参考图真消费；实际像素以 saved.actual_size 为准。
2K/4K：自动切 gpt-image-2-openai + edits/image[]；不再有本地尺寸硬阻断。 高分辨率多图融合的耗时会随参考图数量增加，成功后以 saved.actual_size / size_honored 核对真实像素。
米醋多图间歇拒绝时会按重试策略处理，仍失败则直接返回 Images API 错误。
单张参考图建议 ≤2MB；总输入 ≤8MB（米醋代理上限实测约 10MB）。
Args: prompt: 综合指令。例："combine the colors from img1 and the composition from img2 into a sunset cityscape". image_paths: 2-10 张参考图路径（绝对或相对）。 size: 输出 size。支持 1K/2K/4K；≥2K 自动切高质量线路。 成功时以 saved.actual_size 和 size_honored 核对真实像素。默认 "1024x1024"。 model: "gpt-image-2"（默认）/ "gpt-image-2-openai"（高质量线路，≥2K 自动切换）。 save_dir: 输出目录（必须在安全根目录之下）。 basename: 文件名前缀（仅 [A-Za-z0-9_-.]，含 / .. 会被拒）。默认 "multiref_"。 api_key: 覆盖 MICU_API_KEY；base_url 已锁在启动期 env，运行期不接受。
Returns: dict 含： ok (bool): 是否成功。 model (str): 实际用的模型。 n_references (int): 实际嵌入的参考图张数。 saved (dict): { path, size_bytes, actual_size, actual_megapixels }。 notes (list[str]): 决策与提示。
Examples: # 1K 综合参考 image_multi_reference( prompt="combine these into a single cinematic poster", image_paths=["/p/sketch.png", "/p/character.png", "/p/background.png"], )
# 2K 综合参考（高质量线路）
image_multi_reference(
prompt="merge the architecture style from img1 with the lighting from img2",
image_paths=["/p/img1.jpg", "/p/img2.jpg"],
size="2048x2048",
)
# 4K 综合参考（自动使用高质量线路）
image_multi_reference(
prompt="combine the product references into one 4K campaign visual",
image_paths=["/p/front.jpg", "/p/side.jpg"],
size="3840x2160",
)Common errors: "至少需要 2 张参考图" → 1 张请用 image_edit。 "请求体超 X MB" → 减少图片数量或先压缩。 "HTTP 524" → 当前高质量队列繁忙；自动策略仍失败时请稍后再试。
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 1024x1024 | |
| model | No | ||
| prompt | Yes | ||
| api_key | No | ||
| basename | No | ||
| save_dir | No | ||
| image_paths | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||