gpt-image-2 文生图 / 图生图调用

下面教程的终端命令把 sk-你的令牌 换成你自己的 API KEY 即可直接套用生成模板图像，想按照自己的想法调整画面还需要按照参数说明进行参数修改。

一、文生图:参数说明

常用可选参数，按需求选择修改：

{
  "model": "gpt-image-2",
  "prompt": "你的画面描述",
  "n": 1,                      // 一次生成几张，1-10
  "size": "1024x1024",         // 尺寸:1024x1024 / 1024x1536 / 1536x1024 / auto
  "quality": "low"             // 质量等级:low / medium / high / auto(影响清晰度+耗时)
}

quality 不支持 standard

老的 dall-e 系列模型用 quality: "standard"，但 gpt-image-2 只接受 low / medium / high / auto，传 standard 会直接 400 报错。

二、文生图:调用命令

复制下面命令到终端，修改 prompt 字段为你想要的画面描述，可按需调整 quality / size / n。F 变量带时间戳，避免多次生成时互相覆盖：

F=image-$(date +%s)         # 每次跑都会有新时间戳，互不覆盖

curl https://openclaw-api.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -o "$F.json" \
  --max-time 600 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫在江南春日的西湖边漫步,柳枝拂面,湖面波光粼粼,电影质感",
    "n": 1,
    "size": "1024x1024",
    "quality": "low"
  }'

国内访问慢可以把 host 换成 cn.openclaw-api.com（CDN 加速线，配置完全相同）。

重要

解码命令需要在同一个终端里继续执行，这样 F 变量还在。换了终端 F 就丢了，要走下方”换了终端”兜底方案。

三、文生图:返回示例

成功返回结构（data[0].b64_json 就是图像数据）：

{
  "created": 1778749135,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "total_tokens": 7047,
    "input_tokens": 23,
    "output_tokens": 7024,
    "input_tokens_details": {
      "text_tokens": 23,
      "image_tokens": 0
    }
  }
}

永远是 b64,没有 url

即使请求里加 "response_format": "url"，上游也会忽略该参数，永远返回 base64 编码的 PNG。客户端需要自己 decode 存盘。

四、文生图:把 b64 解码成图片文件

b64 文本不能直接看图，需要 decode 成 PNG。同一个终端里 $F 沿用 curl 那步设的时间戳，直接跑：

python3 -c "import json,base64,os;f=os.environ['F'];open(f'{f}.png','wb').write(base64.b64decode(json.load(open(f'{f}.json'))['data'][0]['b64_json']))"

或者用 shell jq + base64：

jq -r '.data[0].b64_json' "$F.json" | base64 -d > "$F.png"

换了终端 / 关掉窗口再回来怎么办

$F 只在当前 shell 进程里存在，关窗就丢。两种兜底方式：

方式 A · 用 ls 自动挑最新的：

F=$(ls -t image-*.json | head -1 | sed 's/.json$//')
jq -r '.data[0].b64_json' "$F.json" | base64 -d > "$F.png"

方式 B · 看一眼目录里有哪些文件，手动指定：

ls image-*.json
# 把下面这行的 image-1778750120 换成你看到的实际文件名前缀
jq -r '.data[0].b64_json' image-1778750120.json | base64 -d > image-1778750120.png

完成后 image-时间戳.png 就是生成的图像，可直接打开预览。重复调用会得到 image-1778750001.png / image-1778750120.png 这种带时间戳的多张，互不覆盖。

五、文生图:质量参数与等待时间

quality 参数直接影响图像精度和生成耗时：

quality 取值	耗时	输出 token 数	适用场景
low	22-33s	~196	快速预览、批量生成
auto	22-33s	~196	等价 low
medium	~82s	~1756	画面细节更丰富
high	~208s	~7024	最高质量、最慢

服务端已加超时保活机制，quality: "high" 的 3+ 分钟长请求也不会被中间网关切断。但客户端 curl 默认没超时上限，长请求记得加 --max-time 600 留够时间。

---

图生图:参数说明

gpt-image-2 模型允许传参考图作为编辑对象——比如让模型在原图上”加一片叶子”、“换成黑白”、“把背景换成海边”。

跟文生图相比，端点换成 /v1/images/edits，请求体改用 multipart/form-data（不是 JSON），必须传参考图 image[]：

model       gpt-image-2                       (必填)
prompt      编辑指令(强调动词:add/remove/change) (必填)
image[]     参考图文件,可重复传多张              (必填)
              格式: PNG / JPEG / WebP
              单张上限: 5 MB
              数量上限: 3 张
n           生成数量, 1-10                      (可选, 默认 1)
size        输出尺寸, 同文生图                   (可选, 默认 1024x1024)

edits 端点不接受 quality 参数

文生图能传 quality: low/medium/high/auto 调节画质，但图生图端点不接受 quality 字段，传了上游直接 400 报错 "Unknown parameter: 'quality'"。

图生图:调用命令

准备好参考图文件（这里命名 reference.png），用 -F 而不是 -d 上传 multipart 表单。F 变量带时间戳避免多次编辑互相覆盖：

F=edited-$(date +%s)        # 每次跑都会有新时间戳，互不覆盖

curl https://openclaw-api.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的令牌" \
  -o "$F.json" \
  --max-time 600 \
  -F "model=gpt-image-2" \
  -F "prompt=add a small green leaf on top of the apple" \
  -F "image[][email protected];type=image/png" \
  -F "n=1" \
  -F "size=1024x1024"

重要

解码命令需要在同一个终端里继续执行，这样 F 变量还在。换了终端 F 就丢了，要走下方”换了终端”兜底方案。

想传多张参考图就重复 -F "image[]=@..."：

  -F "image[][email protected];type=image/png" \
  -F "image[][email protected];type=image/png" \
  -F "image[][email protected];type=image/png"

注意 不要手动加 -H "Content-Type: ..."，curl 看到 -F 会自动设成 multipart/form-data; boundary=...，手动设会覆盖掉 boundary 导致上游解析失败。

图生图:返回示例

返回结构跟文生图完全一致，data[0].b64_json 是编辑后图像：

{
  "created": 1778741821,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "total_tokens": 259,
    "input_tokens": 30,
    "output_tokens": 229,
    "input_tokens_details": {
      "text_tokens": 14,
      "image_tokens": 16
    }
  }
}

跟文生图的 usage 差异：input_tokens_details.image_tokens 会有数值，代表参考图占用的 token；input_tokens 是文本 + 图像总和。

图生图:把 b64 解码成图片文件

解码方式跟文生图完全相同。同一个终端里 $F 沿用 curl 那步设的时间戳，直接跑：

python3 -c "import json,base64,os;f=os.environ['F'];open(f'{f}.png','wb').write(base64.b64decode(json.load(open(f'{f}.json'))['data'][0]['b64_json']))"

或 jq + base64：

jq -r '.data[0].b64_json' "$F.json" | base64 -d > "$F.png"

换了终端 / 关掉窗口再回来怎么办

$F 只在当前 shell 进程里存在，关窗就丢。两种兜底方式：

方式 A · 用 ls 自动挑最新的：

F=$(ls -t edited-*.json | head -1 | sed 's/.json$//')
jq -r '.data[0].b64_json' "$F.json" | base64 -d > "$F.png"

方式 B · 看一眼目录里有哪些文件，手动指定：

ls edited-*.json
# 把下面这行的 edited-1778750120 换成你看到的实际文件名前缀
jq -r '.data[0].b64_json' edited-1778750120.json | base64 -d > edited-1778750120.png

完成后 edited-时间戳.png 是编辑后的图像。

跟文生图的差异速查

维度	文生图（generations）	图生图（edits）
端点	/v1/images/generations	/v1/images/edits
请求体格式	application/json（curl -d）	multipart/form-data（curl -F）
是否必传参考图	否	是（image[]=@文件）
quality 参数	支持 low / medium / high / auto	不支持，传了直接 400
典型耗时	22s（low）/ 82s（medium）/ 208s（high）	60-240s（中位 ~105s，p90 ~241s）
返回 usage	image_tokens=0	image_tokens>0（参考图 token）