# WhatAI 图像生成技能（curl/bash）

通过 WhatAI 的 OpenAI 兼容接口，调用 `gpt-image-2` 模型：

- **文生图**：`/v1/images/generations` —— 纯文字描述生成新图
- **图像编辑 / 图生图**：`/v1/images/edits` —— 引用一张或多张已有图片再调整（换背景、改风格、多图合成、局部重绘）

## 关键配置

| 项 | 值 |
|----|----|
| Base URL | `https://api.whatai.cc` |
| 文生图路径 | `/v1/images/generations` |
| 图像编辑路径 | `/v1/images/edits` |
| 模型 | `gpt-image-2` |
| 协议 | 完全兼容 OpenAI 官方接口 |

> 密钥已通过数字员工密钥库自动注入到本技能中，**直接执行 curl 即可**，不要再 `export`。
> 下面所有 `Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge` 在你看到这段文字时，已被替换为真实 key。

---

## 触发场景

当用户提出以下任一类请求时，使用本技能：

**文生图（用 `/v1/images/generations`）**

1. 直接生成图像："帮我画一只赛博朋克风格的猫"、"生成一张产品海报"
2. 把 `dall-e-3` / `gpt-image-1` 换成 `gpt-image-2`

**图像编辑 / 图生图（用 `/v1/images/edits`）**

3. 引用某张图调整："把这张照片背景换成海滩"、"把这张图改成吉卜力风格"
4. 多图合成："让图一的人物拿着图二的产品"
5. 局部重绘："只把图里的沙发换成绿色，其它不动"

---

## 标准用法

### 方式 1：最简调用

```bash
curl https://api.whatai.cc/v1/images/generations \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a cyberpunk fox sitting on a neon-lit rooftop in tokyo at night, cinematic lighting, ultra detailed, 8k",
    "size": "1024x1024",
    "n": 1
  }'
```

### 方式 2：调用 + 自动下载到工作目录（推荐）

```bash
URL=$(curl -sS https://api.whatai.cc/v1/images/generations \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a serene japanese garden at dawn, watercolor style",
    "size": "1024x1024",
    "n": 1
  }' | jq -r '.data[0].url')

curl -sS -o output.png "$URL"
echo "✅ 已保存到 output.png"
echo "🔗 原始 URL: $URL"
```

### 方式 3：批量生成

```bash
curl -sS https://api.whatai.cc/v1/images/generations \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a cute corgi astronaut floating in space",
    "size": "1024x1024",
    "n": 4
  }' \
  | jq -r '.data[].url' \
  | awk '{print "curl -sS -o img_" NR ".png \"" $0 "\""}' \
  | bash
```

### 方式 4：只拿 URL 不下载

```bash
curl -sS https://api.whatai.cc/v1/images/generations \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "minimalist mountain logo, flat design",
    "size": "1024x1024",
    "n": 1
  }' \
  | jq -r '.data[0].url'
```

### 方式 5：查看模型对 prompt 的改写（调试用）

```bash
curl -sS https://api.whatai.cc/v1/images/generations \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "武则天",
    "size": "1024x1024",
    "n": 1
  }' \
  | jq '{revised_prompt: .data[0].revised_prompt, url: .data[0].url, usage}'
```

---

## 图像编辑 / 图生图（引用已有图片调整）

用 `/v1/images/edits` 接口。与文生图最大的区别：**请求体是 `multipart/form-data` 表单，不是 JSON**。

> ⚠️ 用 `-F` 提交时**不要**再手动加 `-H "Content-Type: application/json"`。
> curl 会自动设置 `multipart/form-data` 并带上 boundary，手动加 JSON 头会直接 400。

> 兼容性说明：WhatAI 宣称完全兼容 OpenAI 官方接口，以下 curl 按 OpenAI 官方
> `images/edits` 规范编写。首次使用请实测一次，确认字段名（`image` / `image[]`）
> 和返回格式（`url` / `b64_json`）。

### 与文生图的接口差异

| 项 | 文生图 generations | 图像编辑 edits |
|----|----|----|
| 路径 | `/v1/images/generations` | `/v1/images/edits` |
| 提交方式 | `-d '{...}'`（JSON） | `-F "k=v"`（表单） |
| 必填 | `prompt` | `image` + `prompt` |
| 参考图 | 不支持 | `image`（可传多张） |
| 局部重绘 | 不支持 | `mask`（可选蒙版） |

### 方式 A：整图调整（引用一张图 → 改）

```bash
curl -sS https://api.whatai.cc/v1/images/edits \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=把背景换成日落海滩，人物姿势和服装保持不变" \
  -F "size=1024x1024" \
  -F "n=1"
```

### 方式 B：多图参考 / 合成

传多张参考图，prompt 里用"图一""图二"指代：

```bash
curl -sS https://api.whatai.cc/v1/images/edits \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -F "model=gpt-image-2" \
  -F "image[]=@person.png" \
  -F "image[]=@product.png" \
  -F "prompt=让图一的人物手里拿着图二的产品，自然合影"
```

> 多图字段名按 OpenAI 官方规范是 `image[]`（重复传）。若 WhatAI 报字段错误，
> 改成重复的 `-F "image=@a.png" -F "image=@b.png"` 再试。

### 方式 C：局部重绘（mask 蒙版）

`mask` 是一张和原图**同尺寸**的 PNG：透明区域（alpha=0）= 要重新生成的部分，
不透明区域保持不变。

```bash
curl -sS https://api.whatai.cc/v1/images/edits \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -F "model=gpt-image-2" \
  -F "image=@room.png" \
  -F "mask=@room-mask.png" \
  -F "prompt=把沙发换成一张绿色天鹅绒沙发"
```

### 方式 D：编辑 + 自动下载（推荐，兼容 url / b64_json 两种返回）

edits 接口的返回字段可能是 `url`，也可能是 `b64_json`（base64），下面脚本两种都兼容：

```bash
RESP=$(curl -sS https://api.whatai.cc/v1/images/edits \
  -H "Authorization: Bearer sk-8NXnGENP8fySh2a8L4xkvJX59yXVIKVqvPnlRUsBVo6jiFge" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=把这张图改成吉卜力动画风格" \
  --max-time 180)

# 优先取 url，没有就把 b64_json 解码成 png
URL=$(echo "$RESP" | jq -r '.data[0].url // empty')
if [ -n "$URL" ]; then
  curl -sS -o output.png "$URL"
  echo "🔗 原始 URL: $URL"
else
  echo "$RESP" | jq -r '.data[0].b64_json' | base64 -d > output.png
fi
echo "✅ 已保存到 output.png"
```

### 输入图片要求

- 格式：PNG / JPEG / WebP
- 大小：单张建议 < 25MB
- `mask` 必须是 PNG，且尺寸与 `image` 完全一致
- 路径前的 `@` 不能漏：`-F "image=@input.png"`，`@` 表示读取本地文件内容

---

## 响应结构

```json
{
  "created": 1777361358,
  "data": [
    {
      "revised_prompt": "模型自动优化后的 prompt 版本",
      "url": "https://webstatic.aiproxy.vip/output/.../xxx.png"
    }
  ],
  "model": "gpt-image-2",
  "usage": {
    "total_tokens": 1016,
    "input_tokens": 456,
    "output_tokens": 560
  }
}
```

关键字段：
- `data[].url` — 图片地址（**临时链接**，建议立刻下载保存）
- `data[].revised_prompt` — 模型对原 prompt 的改写（调试时很有用）
- `usage` — token 消耗统计

---

## 常用参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 固定填 `gpt-image-2` |
| `prompt` | string | 图像描述，越具体效果越好（建议英文或中英混合） |
| `size` | string | `1024x1024`（方）/ `1024x1792`（竖）/ `1792x1024`（横） |
| `n` | int | 一次生成几张，默认 1 |
| `quality` | string | `standard` 或 `hd`（部分接口支持） |

> 图像编辑接口（`/v1/images/edits`）参数同上，但全部通过 `-F` 表单字段提交（不是 JSON）；并额外支持 `image`（必填，参考图，可多张）和 `mask`（可选，局部重绘蒙版）。

---

## Prompt 写作建议（提升出图质量）

一个好的 prompt 通常包含 4 个要素：

1. **主体**：画什么（猫、城市、人物）
2. **风格**：油画 / 写实 / 赛博朋克 / 吉卜力 / 像素风
3. **细节**：颜色、材质、光照、角度
4. **画质**：`highly detailed`, `8k`, `cinematic lighting`, `sharp focus`

示例对比：
- ✅ 好：`a cyberpunk fox sitting on a neon-lit rooftop in tokyo at night, rain reflections, cinematic lighting, ultra detailed, 8k`
- ❌ 差：`一只狐狸`

---

## 错误排查

| 现象 | 可能原因 | 处理 |
|------|----------|------|
| `401 Unauthorized` | 密钥库里 `WHATAI_API_KEY` 没建或值错 | 去数字员工密钥管理页新建/修正 |
| `404 Not Found` | URL 漏了 `/v1` | 用 `https://api.whatai.cc/v1/images/generations` |
| `model not found` | 模型名拼错 | 必须是 `gpt-image-2`（中划线） |
| `jq: command not found` | 系统没装 jq | 工作站镜像里默认应该带；缺失时用 `apt install jq` |
| 下载的 png 是 0 字节 | url 已过期 / 网络问题 | url 有时效，立即下载；加 `--retry 3` |
| 请求超时 | 图像生成耗时较长 | 加 `--max-time 180` |
| edits 接口 400 / JSON 解析错 | 用 `-F` 时手动加了 `-H "Content-Type: application/json"` | 删掉那行 `-H`，让 curl 自动设 multipart 边界 |
| `No such file or directory` | `-F "image=@xxx"` 路径错或漏了 `@` | 确认文件存在；`@` 表示读取本地文件，不能省 |
| edits 报 `mask` 尺寸不符 | 蒙版与原图尺寸不一致 | `mask` 必须是与 `image` 同尺寸的 PNG |

---

## 输出建议

- 默认把图片保存到当前任务工作目录下，文件名用语义化英文（如 `cyberpunk-fox.png`）
- 把本地路径和原始 url 都告诉用户
- 用户只要命令不要执行时，给完整 curl 即可