GPT Image 的 1K、2K、4K、Quality 和 Mask，到底怎么用？BetterToken 实测指南

• 为什么相同模型、相同参数，不同时候调用的结果却不一样？
• 为什么明明传了 4K 或特定尺寸，拿到的却是被缩水的 1K 图？
• 带了 Mask 局部重绘或 quality=high，到底有没有真正生效？最后又是按什么标准扣费的？

说明：本篇聚焦 gpt-image-2、gpt-image-2.5-flare 与 gpt-image-2.5-sunburst。Nano Banana 系列模型的参数与计费体系不同，我们将另文详解，避免混淆。

​

1. 为什么相同模型、相同参数，结果可能不同？

​

2. 我们怎么测试：“支持”是怎么判断的？

1. 解码原始文件像素：不轻信接口声明，每张交付图片均读取原始文件内容解码宽高，并核对响应中的计费档位与账户实际扣款。
2. 尺寸达标判定：对明确指定的宽、高分别比对。实际返回更大尺寸视为通过；任一边比目标尺寸缩小超过 5% 即判定为未达标（注：此标准用于严格评价测试结果，不代表 API 会自动丢弃尺寸不达标的有效图片）。当省略尺寸或传入 auto 时，则视为不设固定画布目标。
3. 参数接受与实际效果分列：接口不报错只代表“参数被接受”；至于 Mask 是否做到严格区域隔离、quality=high 是否有肉眼可见的提升，必须看最终画面的真实表现。

​

3. 实测发现了什么：哪些参数最容易被误解？

• 默认参数容错：quality 与 size 无论省略、传 null 还是显式传 "auto"，均可正常出图。
• 4K 的正确传法：“4K”是计费档位概念，不代表支持 4096x4096 方图。需要 4K 级别高清大图时，请使用横图尺寸 3840x2160。
• 非法参数零扣费拦截：传入 4096x4096、stream=true、空字符串 quality=""、空字符串 size="" 以及 n=0 时，这些测试请求均返回 HTTP 400 错误且完全不扣费。

​

4. BetterToken 提供了什么：不用自己适配每条线路

1. 按能力智能选路：系统会根据你传入的模型、目标尺寸（如 2K/4K）以及是否包含图片编辑/Mask 参数，自动匹配具备对应处理能力的可用服务。
2. 统一接口与参数兜底：标准化的 POST /v1/images/generations（生图）与 POST /v1/images/edits（参考图/Mask 编辑）接口，自动处理 null、auto 及缺省参数，并在网关层直接拦截非法输入。
3. 透明返回实际尺寸与计费明细：在返回图片数据的同时，响应体中的 bettertoken_image_billing 字段会直接告诉你这张图的实际解码宽高（width/height）、计费档位（billing_resolution）、币种及结算金额（settled_amount）。
4. 明确划定两组核心概念：
   • 支持 Mask 参数 ≠ 像素级精准重绘：接口支持上传参考图与 Mask 完成编辑，但部分实测结果对遮罩外的保护区域产生了连带修改。例如在我们的几何双圆测试中，左侧透明要求改色、右侧不透明要求保护，最终左右两个圆均被改色。因此，我们明确支持 Mask 参数传递，但不承诺每次都能实现严格的像素级区域隔离。
   • 支持 quality 参数 ≠ 承诺固定画质提升幅度：接口支持传入 "auto" 或 "high" 等参数并正确路由，但由于每次生图存在随机性，我们不凭单次样本过度承诺 high 一定带来多少百分比的画质提升。

⚠️ 接入前必须了解的两个真实边界：

1. 按能力选路，不等于每次都能严格锁定像素：受底层服务输出差异影响，即使路由到了正确节点，实际输出像素仍可能出现波动（例如今日仍有请求 1024x1024 实际返回 1024×936，或请求 3840x2160 返回 3840×2161 的样本）。业务端对画布比例极度敏感时，请结合返回的实际宽高做裁剪或后处理。
2. 请求 1K，不一定最终按 1K 收费：计费系统以最终实际交付的有效图片规格定档。今天两款 2.5 模型（以及部分场景下的 gpt-image-2）在请求 1024x1024 时，实际返回了像素更多的 1254×1254，系统会将其判定为 2K 档位并按对应标准计费。

​

5. 三款模型的支持情况：我该调用哪个模型、传什么值？

​

6. 两组真实图片案例：效果到底怎么样？

​

案例 A：电商商品摄影，展示 1K / 2K / 4K 尺寸与细节

生成一张真实的电商棚拍照片：一只珊瑚红色陶瓷马克杯（杯柄朝右），放在浅灰色石材台面上，左侧放一块折叠的米色亚麻布。杯身印有清晰的白色文字“BETTER DAY”。左上方柔和侧光，保留陶瓷釉面的细微反光、亚麻织物纤维和自然接触阴影。杯子完整居中入镜，背景简洁中性，无其他杂物、无水印、无额外文字。

Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads "BETTER DAY" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.

• 画面完成度高：三张图均呈现了珊瑚红釉面反光、右侧杯柄、浅灰石材台面、米色亚麻布纤维以及清晰可读的“BETTER DAY”白色字样。
• 独立采样差异：每次生成属于独立采样，杯身胖瘦比例、字体粗细和布料折叠方式存在自然差异（例如 4K 横图将文字排成了上下两行），因此局部裁切图仅用于展示各张图片的实际细节，不作为严格同构图的光学清晰度实验。
• 计费边界直观体现：第一张虽然请求的是 1024x1024，但因为实际交付了 1254×1254 高清方图，最终与第二张 2048×2048 一样按 2K 档位（¥0.11） 计费。

​

案例 B：商品局部改色，展示 Mask 的实际效果与边界

仅将透明遮罩区域内的珊瑚红色杯身改为深海军蓝色，保留陶瓷材质、光照和反光。保持白色的“BETTER DAY”文字、红色杯柄、亚麻布、台面、背景和整体构图不变，不添加或删除任何物体。

Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.

• 核心改色意图达成：马克杯外侧杯身成功变为深海军蓝，保留了陶瓷高光质感；遮罩外的红色杯柄、左侧亚麻布及背景整体保留，遮罩内的“BETTER DAY”文字也仍可读。
• 严格 Mask 边界未通过（存在越界渗透）：仔细观察杯口边缘和杯子内壁可以发现，这部分原本处于不透明保护区域内的珊瑚红色，也被模型顺带改成了深蓝色；而在更极端的“双圆变色”几何测试中，未遮罩的右侧圆同样发生了变色。
• 使用建议：上传参考图与 Mask 时请确保二者画布尺寸一致（需修改处透明、需保留处不透明），并在 Prompt 中同时写明“改什么”和“保留什么”。对于包含品牌 Logo、包装小字或严苛边缘要求的工业级商业图，生成后务必放大检查保护区域边界。

​

7. 价格与实际使用成本：最后按什么收费？

💡 预算规划重点提示：请按“实际交付档位”而非“请求参数”估算成本！ 正如前文实测所示，今天向 flare、sunburst 或 gpt-image-2 发起 1024x1024（1K）请求时，本次部分请求交付了 1254×1254 的图片。此时系统会按实际交付定档为 2K（即收取 ¥0.15 或 ¥0.11，而非 1K 的 ¥0.035）。如果 100 次 1024x1024 请求在 flare 上全部返回 1254×1254，那么按当前单价计算，这 100 张图的费用为 ¥15.00（算术估算）。 此外，系统定档逻辑综合了目标尺寸与合理偏差阈值（例如 3840×2159 正常定档为 4K，1536×1024 定档为 1K），请勿在业务端简单用“最长边是否大于 1024”自行硬编码重算费用，一切结算以响应体中的 bettertoken_image_billing 字段为准。

​

为什么不能只看表面的“单张低价”？

1. 只有实际返回达到目标尺寸，报价才有可比性：一次标榜“支持 4K 且价格极低”、但实际只返回 1024 缩水小图的请求，无法放进需要高清大图的生产环境，不能作为有效的 4K 价格参与对比。
2. 把失败与返工成本算进总账：本次非法参数测试未收费；已成功交付但效果不满意时，重新提交生成属于新请求，应单独预算。本文展示的 4 张商品与 Mask 案例图（3 张生图 + 1 张编辑），均由一次请求交付，Mask 样本存在上文说明的越界改色，单价分别为 ¥0.11、¥0.11、¥0.13、¥0.11，4 张图总计真实花费仅 ¥0.46，账单与账户扣款分毫不差。如果因为线路不稳定或参数不兼容导致反复重抽，单张表面报价再低，最终获得一张可用素材的真实综合成本也可能增加。
3. 节省隐形的研发适配成本：BetterToken 通过统一参数规范、按能力智能选路和实时返回真实像素及账单字段，减少逐条适配不同服务和自行整理尺寸、费用信息的开发工作。

​

8. 可直接复制的调用示例

​

示例 1：JSON 请求生成高清商品图（POST /v1/images/generations）

curl https://bettertoken.ai/v1/images/generations -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gpt-image-2",
  "prompt": "Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads \"BETTER DAY\" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
JSON

• 尺寸规范提示：需要 4K 横图时请将 "size" 改为 "3840x2160"（切勿使用 "4096x4096"）。当前有效尺寸需满足：宽高均为 16 的倍数、最长边不超过 3840、长短边比例不超过 3:1、总像素在 655,360 至 8,294,400 之间。
• 文件格式识别提示：即使请求中指定了 "output_format": "png"，部分底层节点返回的二进制内容仍可能为 JPEG 格式。在保存或处理图片时，建议根据文件头（Magic Bytes）识别真实图片格式，不要硬编码后缀名。

​

示例 2：Multipart 参考图与 Mask 局部编辑（POST /v1/images/edits）

curl https://bettertoken.ai/v1/images/edits -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product-1k-0.png;type=image/png" \
  -F "mask=@mask-mug.png;type=image/png" \
  -F 'prompt=Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.' \
  -F "size=2048x2048" \
  -F "quality=high" \
  -F "n=1" \
  -F "response_format=b64_json"

​

示例 3：读取实际交付像素与计费信息（响应结构与解析代码）

{
  "created": 1792398084,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "bettertoken_image_billing": {
    "currency": "CNY",
    "settled_amount": "0.11",
    "outputs": [
      {
        "index": 0,
        "width": 2048,
        "height": 2048,
        "billing_resolution": "2K",
        "currency": "CNY",
        "amount": "0.11"
      }
    ]
  }
}

import base64
import io
import json
from pathlib import Path
from PIL import Image  # 需要 Pillow

# 将 API 的 JSON 响应保存为 response.json 后执行。
resp_json = json.loads(Path("response.json").read_text())
if "error" in resp_json:
    raise RuntimeError(resp_json["error"])

billing = resp_json["bettertoken_image_billing"]
outputs = {item["index"]: item for item in billing["outputs"]}
for index, item in enumerate(resp_json["data"]):
    img_bytes = base64.b64decode(item["b64_json"], validate=True)
    with Image.open(io.BytesIO(img_bytes)) as image:
        image.load()
        width, height = image.size
        ext = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(image.format)
        if ext is None:
            raise ValueError(f"未处理的图片格式：{image.format}")
    Path(f"output_{index}.{ext}").write_bytes(img_bytes)
    info = outputs[index]
    print(f"图片 {index}：原图 {width}×{height}；计费档位 {info['billing_resolution']}")
    print(f"单张费用：{info['amount']} {info['currency']}")
    if (width, height) != (info["width"], info["height"]):
        print("图片像素与响应尺寸不一致，请保留结果并联系支持。")
print(f"本次结算：{billing['settled_amount']} {billing['currency']}")

• OpenAI 官方文档：图片提示词编写指南 (Image Prompting Guide)
• OpenAI Cookbook：高输入保真度图片生成与编辑示例