self-media-james/doc/passport/image2图片生成.md

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：最简调用

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：调用 + 自动下载到工作目录（推荐）

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：批量生成

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 不下载

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 的改写（调试用）

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：整图调整（引用一张图 → 改）

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 里用"图一""图二"指代：

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）= 要重新生成的部分， 不透明区域保持不变。

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），下面脚本两种都兼容：

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"，@ 表示读取本地文件内容

---

响应结构

{
  "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 即可