Image 2

image-2

Overview

通过 aihubmax.com 的 gpt-image-2 接口创建异步图片生成任务，创建成功后必须继续查询直到任务终态（completed 或 failed）。鉴权采用 Authorization: Bearer <key>。

完整字段说明、错误码、响应结构见 references/api-guide.md。

When to Use

• 用户想用 prompt 生成图片（文生图）
• 用户提供参考图，希望基于参考图生成新图（图生图，传 image_urls）
• 用户指定输出像素分辨率（如 1024x1024、1920x1080、1080x1920）

When NOT to Use

• 视频生成、视频处理、音频处理
• OCR、文档解析、表格识别
• 非生成式编辑（裁剪、压缩、加水印、加边框）

CRITICAL

• 调用前必须完成参数校验，缺必填先补齐再调用 API
• 不得回显完整 Authorization token，日志只允许 head4****tail4 掩码
• 同参数任务在同一轮对话内禁止二次提交（参数任意变化即视为新任务，可创建）
• 禁止自动循环重试创建接口；重试需先告知会再次消耗积分并取得用户同意。唯一例外：HTTP 401 触发的 key 链 fallback——它换的是 key 不是同请求，且 401 不消耗积分，详见下方「401 自动 fallback」
• 创建接口返回的是异步任务，必须接着轮询查询接口直到终态
• 生成的图片 URL 24 小时后失效，需要长期保留请下载或转存
• 默认会把图片下载到当前工作区根目录，文件名 {YYYYMMDD-HHMMSS}-{≤10字标签}.{ext}；优先级：--filename > --label > 自动从 prompt 前 10 字提取。环境变量 IMAGE_2_OUTPUT_DIR 或 --output-dir 可改保存目录

Auth & Key Handling

读取优先级（从高到低）：

1. 本轮对话显式提供的 key（通过 X_API_KEY=... 注入给脚本）
2. 环境变量 X_API_KEY
3. $PWD/.env.local 中的 X_API_KEY=...（自动读取，无需 flag）
4. $PWD/.env 中的 X_API_KEY=...（自动读取，无需 flag）
5. ~/.config/image-2/.env（仅 --use-local-key 时读）

环境变量名 X_API_KEY 是历史延续命名；值通过 Authorization: Bearer <key> 提交给 aihubmax.com。

401 自动 fallback：

• 如果某一层的 key 调用 POST /v1/images/generations 返回 HTTP 401（authentication_error），脚本会自动尝试链条中的下一个 key。401 不消耗积分，所以这种 fallback 安全。
• 其他错误码（402 余额不足 / 422 参数非法 / 429 限流 / 5xx 服务错误）以及网络错误不触发 fallback，立即返回让用户决定。
• 同一个 key 值在多个来源重复出现时只会试一次（按值去重）。
• 一旦某层 key 通过 create 调用成功，后续轮询查询接口都用同一个 key。

作用域约束：

• 第 3、4 层只读 $PWD 下的文件，不向上递归，避免在 Agent 任意 cwd 下误读父项目的 key。
• 想用 ~/.config/image-2/.env 必须显式 --use-local-key，避免 Agent 在用户不知情时静默用持久化 key 扣费。
• key 在日志中始终掩码为 head4****tail4，完整值只出现在 Authorization header 内。

首次配置 key（可选）：

./scripts/set_key.sh                  # 交互式输入，存到 ~/.config/image-2/.env
echo 'sk-xxx' | ./scripts/set_key.sh --stdin

会话级使用（推荐）：

export X_API_KEY='sk-xxx'

项目级使用：在项目根目录建 .env 或 .env.local：

# .env.local（不入版本控制）
X_API_KEY=sk-xxx

.env / .env.local 解析规则（极简，不等同于 shell）：

• 支持：KEY=value / KEY="value" / KEY='value'、等号两侧空白、# 起首的注释行、空行
• 文件中 X_API_KEY 出现多次时取最后一次
• 不支持 shell 展开（${OTHER} / $OTHER）、命令替换（$(...) / 反引号）、续行符 \ ——这些都会被当作字面字符串
• 只识别变量名 X_API_KEY，不识别 OPENAI_API_KEY / FOXAPI_KEY 等其他命名

Required & Optional Parameters

Resolution 取值

完整版预设（11 种）：1024x768 768x1024 1024x1024 1536x1024 1024x1536 1920x1080 1080x1920 2560x1440 1440x2560 3840x2160 2160x3840

精简版预设（3 种）：1024x1024 1024x1536 1536x1024

完整版自定义（仅完整版）：{"width": W, "height": H}，W/H 均为 16 的倍数，256≤W,H≤3840，长短边比 ≤ 3:1，总像素 655,360..8,294,400。

Workflow

1. 收集与校验：补齐 prompt；如果用户描述涉及"基于这几张图"/"参考这张图"等，需要 image_urls；按上表校验 resolution、num_outputs、精简版禁用字段。
2. 预览摘要：向用户输出请求摘要（模型、模式、resolution、num_outputs、是否有参考图、掩码 key），明确"将消耗积分"，等待用户确认后再调用脚本。
3. 调用脚本：用 scripts/create_task.sh 提交。脚本本身不再二次确认，直接发起 create 并轮询。
4. 查询直到终态：脚本会以默认 8 秒间隔轮询 /v1/tasks/{id}?sync_upstream=true，直到 status=completed 或 failed。
5. 返回结果 & 自动保存：成功时输出 results[].url，并把图片下载到本地（详见下方 Output & Save）。失败时输出 error.code / error.message，不下载。

Output & Save

任务终态为 completed 后，脚本会自动下载 results[].url 中的图片到本地。Agent 必须把这一步当成主流程，不要只把 URL 抛给用户——24 小时后 URL 失效。

默认行为

• 保存目录：$PWD（脚本被调用时的工作目录 = 当前工作区根目录）
• 文件名：{YYYYMMDD-HHMMSS}-{标签}.{ext}
  • 时间戳取脚本启动时刻，所有相关任务共享一致前缀
  • 标签 = prompt 前 10 个 Unicode 字符，去除 /\:*?"<>| 等文件系统不安全字符，空白折叠为 _
  • 扩展名按响应的 content_type 推断：image/png → png、image/jpeg → jpg、image/webp → webp
• 多输出（num_outputs > 1）：自动加 -01、-02 后缀
• 文件冲突：同名文件存在时追加 -2、-3...

覆盖优先级

Agent 解析用户意图

# 文生图（默认 1024x1024）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "生成科技风产品海报" \
  --resolution 1920x1080

# 图生图（多张参考图重复传 --image-url，最多按 aihubmax.com 实际上限）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "基于参考图重绘成极简海报" \
  --image-url 'https://example.com/a.png' \
  --image-url 'https://example.com/b.png' \
  --resolution 1024x1536

# 精简版（仅 3 种预设、num_outputs 必须 1）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --model gpt-image-2-limit \
  --prompt "极简产品图" \
  --resolution 1536x1024

# 自定义分辨率（仅完整版）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "宽屏 banner" \
  --resolution 2400x800

# 保存到指定目录 + 指定文件名（用户在上下文中明确要求时）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "Logo 设计" \
  --resolution 1024x1024 \
  --output-dir ~/Desktop \
  --filename brand-logo

# 用环境变量统一指定保存目录（适合反复生成场景）
IMAGE_2_OUTPUT_DIR=~/Pictures/image-2 \
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "宣传图" --resolution 1920x1080

# 只要 URL，不下载
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "..." --resolution 1024x1024 --no-save

Error Handling

• 缺 prompt：提示用户补全提示词
• 缺 image_urls 但 prompt 暗示需要参考图：先和用户确认是否提供参考图，再选择 text2img 或 img2img
• resolution 非法：返回模型对应的预设清单，要求重选；若自定义需提示 16 的倍数/范围/总像素约束
• 精简版用了禁用字段（quality、output_format、background、mask_url、num_outputs>1）：明确告知精简版限制
• mask_url 与 background 同时传：二选一
• HTTP 401 authentication_error：key 无效/过期/权限不足，去 aihubmax.com 检查
• HTTP 402 insufficient_quota：余额不足，请用户充值后再试
• HTTP 422 validation_error：根据 error.message 调整参数
• HTTP 429 rate_limit_error：限流，禁止自动重试，告知用户稍后再试
• HTTP 5xx：服务异常，建议用户确认后由用户决定是否重试
• 轮询超时：明确告知任务可能仍在运行，给出 task_id 让用户后续手动查询

Dedup Rule

同一轮对话内，若 model + prompt + image_urls + resolution + num_outputs + quality + mask_url + output_format + background 全部相同，禁止再次提交；任何一项变化都允许新建。

Pre-Response Checklist

最终响应前自检：

• 是否完成必填与字段约束校验
• 是否对 key 做了 head4****tail4 掩码
• 创建成功后是否输出了 task_id
• 是否轮询到 completed / failed 才结束
• 是否提示了图片 URL 24 小时过期
• 是否输出了本地保存路径（除非显式 --no-save）
• 用户在上下文里指定了保存位置/文件名时，是否被正确传给 --output-dir / --filename

Directory

• SKILL.md
• scripts/set_key.sh、scripts/create_task.sh
• references/api-guide.md
• tests/（pressure 场景文档）