# Image 2

> Use when the user asks to generate, render, or recreate an image — phrases like "生成图片"、"图生图"、"海报图"、"封面图"，or when they specify an output resolution such as 1024x1024 / 1920x1080 / 1080x1920. Do NOT use for video generation, OCR, or non-generative image editing (crop, compress, watermark).

- Skill: `cookaihq/image-2` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add cookaihq/image-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cookaihq/image-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cookaihq (https://skillmd.com/u/cookaihq)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cookaihq/image-2

---


# image-2

## Overview

通过 [aihubmax.com](https://docs.aihubmax.com/pages/zh/api-manual/image-series/gpt-image-2/gpt-image-2) 的 `gpt-image-2` 接口创建异步图片生成任务，创建成功后必须继续查询直到任务终态（`completed` 或 `failed`）。鉴权采用 `Authorization: Bearer <key>`。

完整字段说明、错误码、响应结构见 [references/api-guide.md](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（可选）**：

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

**会话级使用（推荐）**：

```bash
export X_API_KEY='sk-xxx'
```

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

```ini
# .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

| 参数 | 必填 | 说明 |
|------|------|------|
| `model` | 是 | `gpt-image-2`（完整版，默认）或 `gpt-image-2-limit`（精简版） |
| `prompt` | 是 | 提示词；图生图时描述「在参考图基础上做什么改变」 |
| `image_urls` | 否 | 参考图 URL 数组；传入即图生图模式 |
| `resolution` | 否 | 预设字符串或 `{width, height}` 对象，默认 `1024x1024`，详见下方 |
| `num_outputs` | 否 | 完整版 1-10，精简版只能 1，默认 1 |
| `quality` | 否 | `low/medium/high`，默认 `high`，**精简版不支持** |
| `output_format` | 否 | `png/jpeg/webp`，默认 `png`，**精简版不支持** |
| `background` | 否 | `auto/opaque`，与 `mask_url` 互斥，**精简版不支持** |
| `mask_url` | 否 | 遮罩图（白色区域可编辑），与 `background` 互斥，**精简版不支持** |

### 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](#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`...

### 覆盖优先级

| 项 | 覆盖来源（高 → 低） | 说明 |
|---|---|---|
| 保存目录 | `--output-dir DIR` → env `IMAGE_2_OUTPUT_DIR` → `$PWD` | 目录不存在会自动 `mkdir -p` |
| 标签部分 | `--label TEXT` → prompt 前 10 字自动提取 | 仅影响默认文件名中的标签段，时间戳照常 |
| 完整文件名 | `--filename NAME` | 整段替换 `{时间戳}-{标签}` 部分（仍自动加扩展名 & 多输出索引） |
| 关闭下载 | `--no-save` | 跳过下载，只回显 URL |

### Agent 解析用户意图

| 用户话语 | Agent 应传递的参数 |
|---|---|
| 「生成一张……」（未提保存位置） | 不传 `--output-dir` 也不传 `--filename`，走默认 |
| 「保存到 `~/Desktop`」 | `--output-dir ~/Desktop` |
| 「文件叫 `banner`」 | `--filename banner` |
| 「叫 `banner.jpg`」 | `--filename banner`（扩展名由 content-type 决定，无需传） |
| 「设置环境变量 `IMAGE_2_OUTPUT_DIR=/foo` 后再跑」 | 由用户自己 `export`；脚本会自动读取，Agent 无需再传 |
| 「不要保存到本地，只给我链接」 | `--no-save` |



```bash
# 文生图（默认 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](https://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 场景文档）