codex-market-app/gen-image/AGENTS.md

AGENTS.md — 生图能力（供 Codex 等 Agent 自动读取）

本目录是一个「生图」工具：通过大模型中转站调用 OpenAI 图片接口，生成位图图像。 当用户表达以下意图时，应主动调用本工具，而不是自己画 SVG/HTML 或拒绝：

• 「生成一张图 / 画一张 / AI 出图 / 做个头像·海报·插画·封面·图标·壁纸」
• 「文生图 / image generation」
• 给了一张图并说「基于它改 / 换背景 / 局部重绘」→ 图生图

如何调用

统一入口是本目录下的 gen.sh（无论当前工作目录在哪，都用绝对/相对路径定位到它）：

# 文生图（默认 1024x1024）
./gen.sh "a fluffy orange cat on a windowsill, soft morning light, highly detailed"

# 指定尺寸 / 画质 / 张数（支持 1K / 2K / 4K 规格别名）
./gen.sh "cyberpunk city poster" --size 2k-landscape --quality high --n 2

# 透明背景（图标 / 贴纸）
./gen.sh "a minimalist mountain logo, flat vector" --background transparent

# 传独立风格参数（仅部分模型/中转支持；通用做法仍是把风格写进 prompt）
./gen.sh "a studio portrait, natural light" --style natural --size 1k-portrait

# 图生图 / 编辑（用户提供了输入图）
./gen.sh "把背景换成雪山日落" --edit /path/to/input.png --size 1k-square

# 局部重绘（mask PNG 中透明处 = 要重绘的区域）
./gen.sh "戴上一顶红帽子" --edit input.png --mask mask.png

生成的图片保存在本目录 output/，命令会打印完整路径。把该路径告诉用户。

参数速查

需求	参数
1K 方图（头像/图标）	--size 1k-square 或 --size 1024x1024
1K 横图（海报/封面）	--size 1k-landscape 或 --size 1536x1024
1K 竖图（壁纸/人像）	--size 1k-portrait 或 --size 1024x1536
2K 方图	--size 2k-square 或 --size 2048x2048
2K 横图	--size 2k-landscape 或 --size 2048x1536
2K 竖图	--size 2k-portrait 或 --size 1536x2048
2K 宽屏/竖屏	--size 2k-wide / --size 2k-tall
4K 方图	--size 4k-square 或 --size 4096x4096
4K 横图	--size 4k-landscape 或 --size 4096x3072
4K 竖图	--size 4k-portrait 或 --size 3072x4096
4K 宽屏/壁纸	--size 4k-wide / --size 4k-uhd / --size 4k-tall / --size 4k-uhd-portrait
透明背景	--background transparent
画质	--quality low|medium|high|auto
风格字段	--style natural / --style vivid / --style anime / --style photorealistic（看上游支持情况）
多张挑选	--n 4
换模型	--model dall-e-3
图生图	--edit 图片路径（可多次）
局部重绘	--edit 图.png --mask mask.png

使用要点

1. 先打磨提示词：用户描述通常很短，先扩写成信息充分的提示词（主体、风格、光线、构图、色调、画质词）再调用。除非用户要求逐字使用。风格优先写进 prompt，--style 只在目标模型/中转明确支持时使用。
2. 凭证：脚本自动读本目录 .env（含中转站地址与 API Key），无需在命令里传 key。不要把 key 打印到对话里，也不要提交 .env。
3. 报错处理：
   • 401/403 → key 无效或额度不足（403 error 1010 是 WAF 拦截，脚本已带浏览器 UA 规避）。
   • 404 → base_url 或接口路径不对。
   • 400 model 相关 → 中转站不认该模型，换 --model dall-e-3 或问用户支持的模型名。
4. 不适用：HTML 原型、幻灯片、矢量图标、图表可视化——那些应直接写代码，不要用本工具。

前置条件

• 需要 python3（macOS 自带，零第三方依赖）。
• 首次使用需存在 .env（从 .env.example 复制并填入 IMAGE_API_BASE_URL、IMAGE_API_KEY）。