> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 通过 BetterToken 实测了解 GPT Image 的尺寸、画质、参考图与 Mask 编辑，查看真实商品图、裁切对比、费用记录和完整 API 调用代码。

export const GptImageComparison = ({kind, labels, caption, label}) => {
  const comparisonPanels = {
    crops: [["comparison-crop-1k.png", 480, 480], ["comparison-crop-2k.png", 480, 480], ["comparison-crop-4k.png", 480, 480]],
    mask: [["comparison-mask-original.png", 476, 476], ["comparison-mask-overlay.png", 476, 476], ["comparison-mask-result.png", 476, 476]],
    boundary: [["comparison-boundary-original.png", 576, 256], ["comparison-boundary-result.png", 576, 256]],
    circles: [["comparison-circles-original.png", 416, 416], ["comparison-circles-overlay.png", 416, 416], ["comparison-circles-result.png", 416, 416]]
  };
  const panels = comparisonPanels[kind];
  return <div className="bt-image-comparison not-prose">
      <div className="bt-image-comparison-scroll" role="region" aria-label={label} tabIndex={0}>
        <div className="bt-image-comparison-grid" style={{
    gridTemplateColumns: `repeat(${panels.length}, minmax(0, 1fr))`,
    '--bt-comparison-min-width': `${panels.length * 176 + (panels.length - 1) * 16}px`
  }}>
          {labels.map((title, index) => <p className="bt-image-comparison-title" key={`title-${index}`}>{title}</p>)}
          {panels.map(([file, width, height], index) => <a key={file} href={`/images/gpt-image-guide/${file}`} target="_blank" rel="noreferrer">
              <img src={`/images/gpt-image-guide/${file}`} alt={labels[index]} width={width} height={height} loading="lazy" style={{
    borderRadius: '0.5rem'
  }} />
            </a>)}
        </div>
      </div>
      <p className="bt-image-comparison-caption">{caption}</p>
    </div>;
};

在调用 `gpt-image-2`、`gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst` 生成商品图、广告素材或设计稿时，很多开发者都会遇到几个头疼的问题：

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

在日常接口调用中，仅仅看 HTTP 状态码是不是 `200 OK` 远远不够——**能出图、能放进目标版面、费用透明可预期**，这三个条件必须同时满足。

为了帮开发者彻底摸清这三款模型的真实脾气，BetterToken 在底层完成了**按能力智能选路、默认参数清洗、非法参数前置拦截，以及基于实际交付像素的透明计费**。本文基于 2026 年 10 月 19 日的最新实测数据与价格快照，用真实生成的原图和账单，带你一次看清怎么调用、能拿到什么效果，以及模型本身仍存在哪些客观边界。

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

***

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

在实际接入中，同一个模型名称背后的不同服务节点，其真实能力与稳定性往往存在差异：有的线路仅支持基础 1K 出图，有的线路能交付 `2048×2048` 甚至 `3840×2160` 高清大图；不同节点对 `quality` 取值、参考图编辑与 `Mask` 遮罩的支持程度也不尽相同。

如果平台只是简单地按模型名盲目转发，开发者就会频繁遭遇“传了 4K 却返回 1K 小图”、“传了 Mask 直接报错”或“需要反复调整参数”的窘境。这也是为什么我们需要一套严格的测试标准，把“接口接受参数”和“实际交付效果”拆开来逐一核验。

***

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

为了确保结论客观可靠，我们在正式版回归测试中设计了 **22 个标准测试场景**（其中 17 次合法请求成功交付 18 张图片，5 个非法参数场景按预期拦截且未扣费），并额外针对电商高频场景生成了商品图与 Mask 编辑样本。

我们的核验标准非常直接：

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

***

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

将请求参数、实际交付像素与最终账单放在一起对比，我们发现了几个最容易被开发者误解的关键事实：

| 请求场景 | 实际交付尺寸 | 计费档位与 CNY 单价 | 实测结论与使用含义 |
| :- | :- | :- | :- |
| `gpt-image-2`，`2048x2048`，省略 `quality` | 2048×2048 | 2K，¥0.11 | 不传 `quality`（使用默认画质）在本次请求中成功生成 2K 大图 |
| `flare`，`2048x2048`，省略 `quality` | 2048×2048 | 2K，¥0.15 | 已实测验证 2048×2048 尺寸交付 |
| `sunburst`，`2048x2048`，省略 `quality` | 2048×2048 | 2K，¥0.15 | 已实测验证 2048×2048 尺寸交付 |
| `gpt-image-2`，`1024x1024` | **1024×936** | 1K，¥0.035 | 成功交付有效图片，但高度缩水约 8.6%，未达本轮严格尺寸标准 |
| `flare` / `sunburst`，`1024x1024` | **均为 1254×1254** | **2K，均为 ¥0.15** | **请求 1K 并不保证按 1K 收费**；实际交付超规格方图，按 2K 定档 |
| `gpt-image-2`，`1536x1024` | 1536×1024 | 1K，¥0.035 | 常规比例横图同样归属 1K 计费档位 |
| `gpt-image-2`，`3840x2160` | **3840×2159** | 4K，¥0.13 | 高度仅差 1 像素（偏差 \< 0.05%），符合 4K 尺寸验收标准 |
| `gpt-image-2`，有效 Mask + `2048x2048` + `high` | 2048×2048 | 2K，¥0.11 | Mask 编辑链路畅通，但局部区域的精准隔离能力需结合画面验收 |

此外，在参数兼容性与错误处理上，实测表现如下：

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

***

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

面对底层模型复杂的尺寸漂移与节点差异，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. 三款模型的支持情况：我该调用哪个模型、传什么值？

目前 `gpt-image-2`、`gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst` 的能力配置与实测覆盖情况如下：

| 能力维度 | `gpt-image-2` | `gpt-image-2.5-flare` | `gpt-image-2.5-sunburst` |
| :- | :- | :- | :- |
| **1K 生图请求** | 支持（已实测，实际尺寸可能偏离目标，如返回 1024×936 或 1254×1254） | 支持（已实测，本轮返回更大的 1254×1254 并按 2K 计费） | 支持（已实测，本轮返回更大的 1254×1254 并按 2K 计费） |
| **2K 生图 (`2048x2048`)** | **本轮已实测交付** | **本轮已实测交付** | **本轮已实测交付** |
| **4K 生图 (`3840x2160`)** | **本轮已实测横图交付** | 路由配置已对齐支持 | 路由配置已对齐支持 |
| **普通参考图编辑（不带 Mask）** | **本轮已实测支持**（省略或传空 Mask 均走普通编辑） | 暂未确认单独可用（不能由 Mask 支持推断普通编辑也可用） | 暂未确认单独可用（不能由 Mask 支持推断普通编辑也可用） |
| **带 Mask 局部编辑** | **本轮已实测 2K 交付** | 已配置支持 4K Mask 编辑（其他档位未确认） | 已配置支持 4K Mask 编辑（其他档位未确认） |
| **画质参数 (`quality`)** | 默认/`auto`/`high` **均已实测验证** | 默认/`auto` 已实测；`high` 路由已配置对齐 | 默认/`auto` 已实测；`high` 路由已配置对齐 |

*注：表中“本轮已实测”代表在今日回归与案例生成中有直接交付的图片与账单样本；“路由配置已对齐支持”代表平台已完成对应能力通道的配置对齐，但未在今日回归中对所有排列组合逐一重复发包。*

***

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

为了展示最真实的生成水准，我们参考 [OpenAI 官方图片提示词指南](https://developers.openai.com/api/docs/guides/image-prompting) 中\*\*“明确主体 + 材质纹理 + 光照方向 + 构图比例 + 画面排除项”\*\*的写法，通过 BetterToken 真实接口生成了以下两组电商案例（保留原始输出，未做任何后期修图）。

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

**场景设计（中文构思）**：

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

**实际调用英文 Prompt**：

```text theme={null}
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.
```

我们使用 `gpt-image-2`（`quality="high"`，每次生成 1 张），保持上述 Prompt 完全不变，不靠在提示词里写“4K”凑数，而是纯粹通过 `size` 参数分别请求三档尺寸：

| 请求尺寸 (`size`) | 实际交付尺寸 | 实际计费档位 / 费用 | 单次请求耗时 |
| :- | :- | :- | :- |
| `1024x1024` | **1254×1254** | **2K / ¥0.11** | 34.35 秒 |
| `2048x2048` | **2048×2048** | **2K / ¥0.11** | 31.97 秒 |
| `3840x2160` | **3840×2161** | **4K / ¥0.13** | 24.36 秒 |

**1. 请求 `1024x1024` 的原始交付图（实际返回 1254×1254）：**

<Frame>
  <img src="https://mintcdn.com/bettertoken-d796114e/hPGTCgdK9IohJYOA/images/gpt-image-guide/product-1k-0.png?fit=max&auto=format&n=hPGTCgdK9IohJYOA&q=85&s=975ebb5653a1a0e6847310d8448a56d9" alt="GPT Image 2 商品图：请求 1024×1024，实际返回 1254×1254" style={{ borderRadius: '0.5rem' }} width="1254" height="1254" data-path="images/gpt-image-guide/product-1k-0.png" />
</Frame>

**2. 请求 `2048x2048` 的原始交付图（实际返回 2048×2048）：**

<Frame>
  <img src="https://mintcdn.com/bettertoken-d796114e/hPGTCgdK9IohJYOA/images/gpt-image-guide/product-2k-0.png?fit=max&auto=format&n=hPGTCgdK9IohJYOA&q=85&s=a290e92bd7db319ed801c06640c7ba8d" alt="GPT Image 2 商品图：请求与实际交付均为 2048×2048" style={{ borderRadius: '0.5rem' }} width="2048" height="2048" data-path="images/gpt-image-guide/product-2k-0.png" />
</Frame>

**3. 请求 `3840x2160` 的原始交付图（实际返回 3840×2161）：**

<Frame>
  <img src="https://mintcdn.com/bettertoken-d796114e/hPGTCgdK9IohJYOA/images/gpt-image-guide/product-4k-0.png?fit=max&auto=format&n=hPGTCgdK9IohJYOA&q=85&s=1e68f4d96829d9e52f9fa88aceac3c27" alt="GPT Image 2 商品横图：请求 3840×2160，实际返回 3840×2161" style={{ borderRadius: '0.5rem' }} width="3840" height="2161" data-path="images/gpt-image-guide/product-4k-0.png" />
</Frame>

**4. 三档图片对应部位（杯身文字与材质细节）原尺寸裁切对比：**

<Frame>
  <GptImageComparison kind="crops" label="三档商品图局部 100% 原始像素裁切对比" labels={["请求 1K · 返回 1254²","请求 2K · 返回 2048²","请求 4K · 返回 3840×2161"]} caption="每格为 480×480 原像素裁切；独立生成、构图不同。页面缩放不改变文件像素。" />
</Frame>

**实测点评**：

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

***

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

我们以案例 A 生成的第一张商品图（`1254×1254`）作为输入原图，制作了一张同尺寸的带 Alpha 通道遮罩图 [mask-mug.png](/images/gpt-image-guide/mask-mug.png)——**仅将杯身多边形区域设为透明（允许重绘），而将杯柄、杯口内壁及背景设为不透明（要求保留）；杯身文字位于透明区域内，通过提示词要求保留**。

<Frame>
  <GptImageComparison kind="mask" label="原图、遮罩覆盖示意和编辑结果" labels={["原图","绿色覆盖：允许编辑区域","实际编辑结果"]} caption="仅为对照排版缩小；遮罩外杯口也发生改色。原始 API 输出另行保留。" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/bettertoken-d796114e/hPGTCgdK9IohJYOA/images/gpt-image-guide/mask-diagram.png?fit=max&auto=format&n=hPGTCgdK9IohJYOA&q=85&s=7d648791e31a2358ee47907bc3755fae" alt="Mask 范围图解：黑色代表透明可改区域，白色代表不透明保留区域" style={{ borderRadius: '0.5rem' }} width="1254" height="1254" data-path="images/gpt-image-guide/mask-diagram.png" />
</Frame>

*(注：上图为黑白可视化示意，黑色代表可修改区域，白色代表保留区域；实际通过接口上传的是带透明通道的 `mask-mug.png`。)*

**场景设计（中文构思）**：

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

**实际调用英文 Prompt（模型：`gpt-image-2`，`size="2048x2048"`，`quality="high"`）**：

```text theme={null}
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.
```

**实际编辑交付结果（2048×2048，耗时 38.51 秒，费用 ¥0.11）：**

<Frame>
  <img src="https://mintcdn.com/bettertoken-d796114e/hPGTCgdK9IohJYOA/images/gpt-image-guide/product-mask-0.png?fit=max&auto=format&n=hPGTCgdK9IohJYOA&q=85&s=1a3ba294610d624bd6a09bc7c03aa228" alt="GPT Image 2 Mask 编辑结果：杯身变深蓝，杯柄保留红色，但杯口内壁也被改色" style={{ borderRadius: '0.5rem' }} width="2048" height="2048" data-path="images/gpt-image-guide/product-mask-0.png" />
</Frame>

**保护区域越界细节对比：**

<Frame>
  <GptImageComparison kind="boundary" label="Mask 保护区域细节放大：杯口与内壁不在透明遮罩内，但也连带变成了蓝色" labels={["原图：杯口与内壁为红色","编辑后：杯口与内壁也变蓝"]} caption="对应区域放大/缩放展示，不作逐像素一致性比较；这两个区域不在透明遮罩内。" />
</Frame>

**反例参考：回归测试中的“双圆变色”样本（接受 Mask ≠ 精准隔离）**

<Frame>
  <GptImageComparison kind="circles" label="回归测试双圆变色反例：仅左侧设为透明要求改色，但右侧保护区域的圆也被一并改色" labels={["原图：两个红圆","绿色：只允许左侧编辑","结果：左右两个圆都变蓝"]} caption="既有 BetterToken API 样本；右侧受保护对象仍被改变。图片仅缩小排版。" />
</Frame>

**实测点评（诚实披露限制）**：

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

***

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

BetterToken 坚持透明定价。以下为 **2026 年 10 月 19 日** 的公开售价快照（CNY 适用于企业人民币账户，USD 适用于普通美元账户，二者独立定价，不按实时汇率折算）：

| 模型名称 | 1K 单价 / 张 | 2K 单价 / 张 | 4K 单价 / 张 |
| :- | :- | :- | :- |
| **`gpt-image-2`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.11 / \$0.0194 | ¥0.13 / \$0.0229 |
| **`gpt-image-2.5-flare`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 |
| **`gpt-image-2.5-sunburst`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 |

按上述公开单价，假设生成的 100 张图片实际交付均落在对应计费档位，百张调用成本参考如下（算术估算）：

| 模型名称 | 100 张 1K 成本 | 100 张 2K 成本 | 100 张 4K 成本 |
| :- | :- | :- | :- |
| **`gpt-image-2`** (CNY / USD) | ¥3.50 / \$0.62 | ¥11.00 / \$1.94 | ¥13.00 / \$2.29 |
| **`flare` 或 `sunburst`** (CNY / USD) | ¥3.50 / \$0.62 | ¥15.00 / \$2.65 | ¥18.00 / \$3.18 |

> 💡 **预算规划重点提示：请按“实际交付档位”而非“请求参数”估算成本！**
>
> 正如前文实测所示，今天向 `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` 字段为准**。

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

在对比不同平台的图片 API 成本时，建议开发者算清三笔账：

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

***

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

将你的 BetterToken API Key 存入环境变量 `BETTERTOKEN_API_KEY`，即可直接复制以下命令开始调用。

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

以下示例调用 `gpt-image-2` 生成一张 `2048x2048` 的高清商品图（`model` 可直接替换为 `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`）：

```bash theme={null}
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`）

准备好原图 `product-1k-0.png` 与同尺寸透明遮罩 `mask-mug.png`（若只需普通参考图编辑，直接删掉 `-F "mask=..."` 那一行即可）：

```bash theme={null}
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：读取实际交付像素与计费信息（响应结构与解析代码）

BetterToken 的响应体除了标准的 `data[].b64_json` 外，还包含扩展字段 `bettertoken_image_billing` 节点：

```json theme={null}
{
  "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"
      }
    ]
  }
}
```

你可以使用以下 Python 代码片段，一步完成**图片解码、真实格式识别、实际尺寸读取与账单核对**：

```python theme={null}
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)](https://developers.openai.com/api/docs/guides/image-prompting)
* [OpenAI Cookbook：高输入保真度图片生成与编辑示例](https://developers.openai.com/cookbook/examples/generate_images_with_high_input_fidelity)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.