邓文兵
a647557c9f
- 014 字节又整大活：给AI配了云电脑+云手机 - 015 七天连撩三颗王炸：GPT-5.5、DeepSeek V4、Claude 4.7 混战 - 016 Loop Engineering 保姆级指南 - 补全 doc/passport/image2图片生成.md：WhatAI 图像生成技能文档 - CLAUDE.md 增加 AI 图片生成规范说明 - 删除过时的 open-source-code/openclaw-arch-by-claude.md Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
294 lines
9.9 KiB
Markdown
294 lines
9.9 KiB
Markdown
# 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 即可 |