文本生成图像（text-to-image）。米醋代理 + gpt-image-2 系列。

[WHAT] 把一段文字 prompt 渲染成 1 张或 N 张图像，落盘到本地。

[WHEN TO USE]

• 用户要"画 / 生成 / 创建一张图"且没有提供任何参考图 → 用此 tool。

• 如果用户提供了 1 张参考图要"修改 / 编辑 / 替换某部分" → 改用 image_edit。

• 如果用户提供了多张参考图要"按它们的风格画一张新的" → 用 image_multi_reference。

• 如果不知道怎么选 size：先调 server_info() 看 recommended_sizes。

[SIZE 选取建议]

• 默认 None：MCP 自动从 prompt 关键字推断（4K/UHD → 3840x2160；1080p/2K → 2048x1152； 正方形/logo/头像 → 1024x1024；竖屏/9:16 → 1024x1536；横屏/16:9 → 1536x1024 等）。 推断不出来 fallback 1024x1024。

• 强烈推荐：如果你（LLM）已经从用户消息读出确定的 size 偏好，直接显式传 size，比关键字推断准。

• 用户提到"高清/4K/海报/壁纸" → "3840x2160"（横）或 "2160x3840"（竖），自动用 pro。

• 用户提到"FullHD/1080p/横屏视频封面" → "2048x1152"（横）或 "1152x2048"（竖），跨过 2.25MP 阈值。

• pro 与非 pro 价格一致 —— 想要真分辨率请直接拉高 size，1920×1080 这种 ≤2.25MP 的会被压成 ~1.57MP。

• W 与 H 必须都是 8 的倍数（米醋实测约束；OpenAI 官方要 16，米醋更宽容）。

• ≤2.25MP 的请求都被代理压到 ~1.57MP；要真实分辨率必须 ≥4MP（即 2048² 或更大）。

[PROMPT 写法建议]

• 中英文混合可。gpt-image-2 文本渲染近完美，可大段嵌字（中英标点都行）。

• 越具体越好：风格 / 视角 / 光线 / 主体 / 细节程度。

Args: prompt: 图像描述。1-2000 字符。例："A minimalist sushi mascot logo, soft pastel palette". size: "WxH" 字符串或 None。留 None 让 MCP 从 prompt 推（弱 LLM 兜底用）； 强 LLM 已知偏好时直接显式传更准。W 和 H 都必须是 8 的倍数（米醋约束）。常用： "1024x1024" "1280x720" "1024x1536" "1536x1024" "720x1280" ← 1K 档（被压到 1.57MP） "1920x1080" "1080x1920" ← 名义 2K 但 ≤2.25MP，被压到 1.57MP "2048x2048" "2048x1152" "1152x2048" ← 真 2K 档（仅 pro，≥4MP 严格 1:1） "3840x2160" "2160x3840" ← 4K 档（仅 pro，严格 1:1） 默认 None（推断后兜底 1024x1024）。 n: 张数 1-10。1K 时 N>1 自动 5 并发；≥2K 强制 N=1（代理限流）。默认 1。 model: 显式指定模型。留空时按 size 自动选（max edge ≥1600 用 pro，否则 non-pro）。 可选值："gpt-image-2"（快、便宜）/ "gpt-image-2-pro"（高细节、≥2K 必需）。 save_dir: 输出目录。必须在安全根目录 MICU_SAVE_DIR_ROOT 之下（默认 ~/Pictures/micu-out）； 传 root 之外路径会被拒。留空使用默认。 basename: 文件名前缀（不带扩展名），仅允许 [A-Za-z0-9_-.]。 含 / .. 或路径分量会被拒。默认 "gen_"。 api_key: 覆盖 MICU_API_KEY 环境变量。一般留空。 注意：base_url 已锁在启动时 env，运行期不接受 tool 参数（防 key 外泄到攻击者 host）。

Returns: dict 含以下字段： ok (bool): 至少有 1 张成功才为 True。 model (str): 实际用的模型 id。 size (str): 请求的 size。 requested_n (int): 实际生成的张数。 saved (list[dict]): 每张成功的图。每项含 path（绝对路径）/ size_bytes / actual_size（PNG header 读出的真实像素）/ actual_megapixels。 errors (list[str]): 失败请求的错误描述。 notes (list[str]): 路由 / 自动决策 / 实测尺寸偏差的说明。

Examples: # 最简：默认 1024x1024 单张 image_generate(prompt="a red apple on white")

# 4K 壁纸
image_generate(prompt="cyberpunk Tokyo at night", size="3840x2160")

# 一次出 4 张候选（1K 自动并发）
image_generate(prompt="cute sticker of a cat", size="1024x1024", n=4)

Common errors and what to do: "size W/H 必须是 8 的倍数" → 客户端入口拒，改 size 即可（OpenAI 端有时返回"divisible by 16" 提示，米醋 8 倍数已能过）。 "HTTP 524: timeout" → 已自动重试 3 次仍失败，建议改小 size 或稍后再试。 "未配置 API key" → 设置 MICU_API_KEY 环境变量或传 api_key 参数。

图像编辑（image-to-image，单张输入，支持 1K + 真 2K；4K 已禁用见下）。

[WHAT] 接受 1 张本地图片 + 修改指令，输出修改后的图。

[WHEN TO USE]

• 用户提供 1 张图（路径或刚刚生成的图）且要"改 / 替换 / 加 / 去掉某部分" → 用此 tool。

• 如果用户没提供图想从零生成 → 改用 image_generate。

• 如果用户提供了多张图想"批量改"（每张做同样操作）→ 改用 image_batch_edit。

• 如果用户用多张图作风格参考想画一张新的 → 用 image_multi_reference（≤1.57MP）。

[4K 已禁用] origin 处理 4K + 参考图稳定 > 120s，撞 CF Proxy Read Timeout (524)。 入口直接拒 4K size，不发请求。请改 2K（"2048x1152" / "1152x2048" / "2048x2048"）， 或两步法：先 1K/2K image_edit → image_generate(size="3840x2160", 描述同场景) 升 4K。

[路由实现]（实测确定，双路径）

• 1K（边长 ≤1536）：走 /v1/images/edits multipart，支持 alpha mask。 失败 fallback 到 /v1/chat/completions stream。

• 2K（边长 1600–2999）：走 /v1/images/generations + 米醋扩展字段 reference_image=data_url。 size 真实生效（实测 2048² 真 2048²）。 此路径不支持 mask（米醋扩展字段不接受 mask）；如需 mask 请降到 1K。

• 自动锁 pro：max edge ≥1600 → gpt-image-2-pro。

[MASK 工作原理]（仅 1K 路径）

• mask_path 指向一张 PNG，尺寸应与 image_path 一致。

• mask 中 alpha=0（透明） 的像素 = 要修改的区域。

• alpha=255（不透明）的像素 = 要保持原样。

• 不传 mask 则模型自由决定改哪里。

Args: prompt: 修改指令，越具体越好。例："change the background to deep navy with stars, keep the subject pixel-identical". image_path: 输入图的绝对或相对路径。PNG / JPG / WebP 都支持。 mask_path: 可选 alpha mask PNG 路径，透明区即编辑区。仅 1K 路径生效；≥2K 时被忽略。 size: 输出 size。 "1024x1024" "1280x720" "1024x1536" "1536x1024" "720x1280" ← 1K（被压到 1.57MP，含 mask 支持） "1920x1080" "1080x1920" ← 名义 2K 但 ≤2.25MP，会被压到 1.57MP "2048x2048" "2048x1152" "1152x2048" ← 真 2K（≥4MP 严格 1:1，pro 自动） "3840x2160" / "2160x3840" ← 4K 已禁用（撞 CF 524 物理上限），传入直接拒 默认 "1024x1024"。 model: "gpt-image-2"（默认）/ "gpt-image-2-pro"（≥2K 自动切）。 save_dir: 输出目录（必须在安全根目录之下）。默认 ~/Pictures/micu-out 或 MICU_SAVE_DIR。 basename: 文件名前缀（仅 [A-Za-z0-9_-.]）。默认 "edit_"。 api_key: 覆盖 MICU_API_KEY；base_url 已锁在启动期 env，运行期不接受。

Returns: dict 含： ok (bool): 是否成功。 model (str): 实际用的模型。 size (str): 请求 size。 used_fallback (bool): True 表示主端点失败已切换到 chat/completions（仅 1K 可能触发）。 saved (dict): { path, size_bytes, actual_size, actual_megapixels }。 notes (list[str]): 决策与提示。

Examples: # 1K 换背景 image_edit(prompt="replace background with a sunset beach", image_path="/p/portrait.jpg")

# 1K 局部修改（mask 生效）
image_edit(prompt="change hair color to silver", image_path="/p/x.png", mask_path="/p/x_mask.png")

# 真 2K 升级（无 mask）
image_edit(prompt="enhance to cinematic detail, preserve composition", image_path="/p/draft.png", size="2048x2048")

Common errors: "image_path 不存在" → 检查路径，建议用绝对路径。 "size=3840x2160 (4K) 在 image_edit 已禁用" → 4K image_edit 物理撞 CF 524 上限，请改 2K 或两步法。 "HTTP 524" → 2K 单图正常 ~50s，撞了说明 origin 那阵特别忙；自动重试仍失败请稍后再试。

批量图像编辑：N 张输入图 → N 张输出图，每张独立应用同一指令。

[WHAT] 对 image_paths 里的每一张图分别调用 image_edit，统一 prompt 与 size，结果合并返回。

[WHEN TO USE]

• 用户提供多张图且每张要做"同样的修改"（如批量加水印 / 统一换底 / 统一调色）→ 用此 tool。

• 如果是"用多张图作风格参考画 1 张新图" → 这不是此 tool，暂未实现。

• 如果只有 1 张图 → 用 image_edit。

[并发策略]

• non-pro 模型：5 并发（HTML 网页同款）。

• pro 模型：串行 + 1.5s gap（代理对 pro 并发会拒）。

• 任意一张失败不影响其他张；返回 results 里逐张标 ok/error。

[LIMITS]

• 同 image_edit：size 仅 1K 档（≤1536 边长），≥2K 拒绝。

• image_paths 长度建议 2-20 张；过多请分批调用避免超时。

Args: prompt: 应用到每张图的修改指令。例："add a subtle watermark in bottom-right". image_paths: 输入图路径列表（绝对或相对）。 size: 输出 size，仅 1K 档。默认 "1024x1024"。 model: "gpt-image-2" / "gpt-image-2-pro"。留空按 size 自动选。 save_dir: 输出目录（必须在安全根目录之下）。文件名 batch__.png。 api_key: 覆盖 MICU_API_KEY；base_url 已锁在启动期 env，运行期不接受。

Returns: dict 含： ok (bool): True 表示至少 1 张成功。 total (int): 输入图总数。 succeeded (int): 成功张数。 failed (int): 失败张数。 concurrency (int): 实际用的并发度（5 或 1）。 results (list[dict]): 每张图的详细结果（含 input 路径、saved.path、可能的 error）。

Examples: image_batch_edit( prompt="convert to pencil sketch style", image_paths=["/p/a.jpg", "/p/b.jpg", "/p/c.jpg"], size="1024x1024", )

多图融合参考 → 输出 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 已禁用] origin 处理 4K 多图融合稳定 > 120s 撞 CF 524；入口直接拒。 想要真 4K 多图融合：两步法 — 此 tool 出 1K/2K 综合图 → image_generate(size="3840x2160") 描述同场景升 4K。

[路由实现]（双路径 + 自动 fallback）

• 主路径：/v1/images/generations + image_urls=[...]（米醋扩展字段，size 真实生效）

• 兜底：/v1/chat/completions + 顶层 image_urls + stream:true SSE（永不撞 CF 524，但 size 不生效输出 ~1.57MP）

• 自动锁 pro：max edge ≥1600 → gpt-image-2-pro

• 主路径 5xx/524 失败 → 自动 fallback chat stream，notes 标注降级原因

• 返回的 used_fallback 字段说明走的哪条路径

[LIMITS]（当前真实状态，会变化）

• image_paths 长度 2-10 张。

• 1K 稳定：主路径 ~30-100s，size=1024² 实际输出 ~1.57MP。

• 2K 不稳定：主路径 generations + image_urls 在米醋后端间歇 HTTP 500"系统繁忙"； 触发 fallback 后改走 chat stream，size 字段被忽略，实际仍输出 ~1.57MP。

• 单张参考图建议 ≤2MB；总 base64 体积 ≤8MB（米醋代理上限实测约 10MB）。

Args: prompt: 综合指令。例："combine the colors from img1 and the composition from img2 into a sunset cityscape". image_paths: 2-10 张参考图路径（绝对或相对）。 size: 输出 size。真实生效（不再像旧版 chat 路径那样被忽略）。 推荐："1024x1024"（1.57MP 福利）/ "2048x2048"（真 2K，可能 fallback 到 1.57MP）。 "3840x2160" / "2160x3840" 已禁用（撞 CF 524 物理上限），传入直接拒。 默认 "1024x1024"。 model: "gpt-image-2"（默认）/ "gpt-image-2-pro"（≥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 综合参考（不稳，可能 fallback 到 1.57MP）
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",
)

Common errors: "至少需要 2 张参考图" → 1 张请用 image_edit。 "请求体超 X MB" → 减少图片数量或先压缩。 "size=3840x2160 (4K) 在 image_multi_reference 已禁用" → 4K 多图融合物理撞 CF 524； 两步法：先 1K/2K 出综合图 → image_generate(size="3840x2160") 升 4K。

诊断 / 能力查询：在调任何生图 tool 之前，先调一次此 tool 拿到完整路由规则与 size 约束矩阵。

Returns: base_url, default_model, default_save_dir, api_key_configured: 当前配置。 size_rules: size 字段的硬约束 + 代理实际行为（已通过实测确定）。 recommended_sizes: 各 tier 推荐 size（保证 W/H 都是 8 的倍数，米醋约束）。 capability_matrix: 各 tool × 各 size tier 的可用性。 retry_policy: 重试与并发策略。