@henjicc/ai-sdk 0.2.8 → 0.4.0

package/docs/model-adaptation/GPT-Image-2/GPT-Image-2_APIMart.md

@@ -1,173 +1,173 @@
-# GPT-Image-2 · APIMart
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-30 |
-| 模态 | 图片 |
-| 供应商 | APIMart（聚合平台） |
-| 平台模型 ID | **两条独立渠道**：`gpt-image-2`（兼容别名 `gpt-image-2-ext`）与 `gpt-image-2-official` |
-| 接口形态 | **异步任务** |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-> APIMart 上 GPT-Image-2 有两个平台模型与两份文档，参数与计费方式都不同；Henji 产品中合并为一个“GPT Image 2”入口，通过首项“渠道”（普通 / 官方）切换，但适配和运行时仍必须分开对待：
->
-> - **`gpt-image-2`（EXT 渠道）**：按张按分辨率档位固定计费，参数较少
-> - **`gpt-image-2-official`（官方渠道）**：直连 OpenAI 官方模型，参数最全（quality / background / mask / output_format 等），按 **token** 计费
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.apimart.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /v1/images/generations`（基于 OpenAI Images 兼容协议）→ `{ code, data: [{ status: "submitted", task_id }] }`
-- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
-- **任务结果只返回 `url`**——需要 base64 请自行下载转换
-- 其它 OpenAI 标准字段（`response_format`、`style`）**不支持，会被忽略**
-
----
-
-## 2. 渠道 A：`gpt-image-2`（EXT）
-
-### 2.1 能力
-
-- 文生图 / 图生图（参考图最多 **16 张**，URL 与 base64 可混填）
-- 15 种比例 + `auto`
-- `1k` / `2k` / `4k` 三档分辨率
-
-### 2.2 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `model` | string | 必填 | `gpt-image-2` | `gpt-image-2`；兼容别名 `gpt-image-2-ext`（等价、效果一致） |
-| `prompt` | string | 必填 | — | 支持中英文。提交前经平台敏感词/安全审核，命中直接报错 |
-| `n` | integer | 可选 | `1` | **取值只能是 1**。必须传纯数字，加引号会报错 |
-| `size` | string | 可选 | `1:1` | 15 种比例 + `auto`：`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`5:4`、`4:5`、`16:9`、`9:16`、`2:1`、`1:2`、`3:1`、`1:3`、`21:9`、`9:21`。也支持直接传像素（如 `1881x836`）。**`auto` 时默认比例为 `1:1`** |
-| `resolution` | string | 可选 | `1k` | `1k` / `2k` / `4k` |
-| `image_urls` | array | 可选 | — | 传入后走图生图。**最多 16 张**（超过返回 `image_urls exceeds max 16`）；单张 ≤ 20 M，总体 ≤ 256 M；URL 与 `data:image/png;base64,...` 可混填。**不传 `size` 时输出分辨率 = 输入图分辨率**；传 `size` 则强制按指定尺寸出图 |
-| `official_fallback` | boolean | 可选 | `false` | `true` 时使用官方渠道兜底 |
-| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审 |
-
-### 2.3 `size × resolution` → 实际像素
-
-| size | 1k | 2k | 4k |
-|---|---|---|---|
-| 1:1 | 1024×1024 / 1254×1254 | 2048×2048 | 2880×2880 |
-| 3:2 | 1536×1024 | 2048×1360 | 3520×2336 |
-| 2:3 | 1024×1536 | 1360×2048 | 2336×3520 |
-| 4:3 | 1024×768 | 2048×1536 | 3312×2480 |
-| 3:4 | 768×1024 | 1536×2048 | 2480×3312 |
-| 5:4 | 1280×1024 / 1448×1086 | 2560×2048 | 3216×2576 |
-| 4:5 | 1024×1280 / 1122×1402 | 2048×2560 | 2576×3216 |
-| 16:9 | 1536×864 / 1672×941 | 2048×1152 | 3840×2160 |
-| 9:16 | 864×1536 / 941×1672 | 1152×2048 | 2160×3840 |
-| 2:1 | 2048×1024 / 1774×887 | 2688×1344 | 3840×1920 |
-| 1:2 | 1024×2048 / 887×1774 | 1344×2688 | 1920×3840 |
-| 3:1 | 1881×836 / 1536×512 | 3072×1024 | 3840×1280 |
-| 1:3 | 887×1774 / 512×1536 | 1024×3072 | 1280×3840 |
-| 21:9 | 2016×864 / 1915×821 | 2688×1152 | 3840×1648 |
-| 9:21 | 864×2016 / 821×1915 | 1152×2688 | 1648×3840 |
-
-### 2.4 价格
-
-来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → `GPT-IMAGE-2-EXT (gpt-image-2)`（2026-08-22，1 Credit ≈ $0.1）。
-
-| 规格 | 我们的价格 | 官方价 | 节省 |
-|---|---|---|---|
-| 默认 | 0.085 Credits/张 ≈ **$0.0085/张** | $0.010625 | 20% |
-| 1K | 0.085 Credits/张 ≈ **$0.0085/张** | $0.010625 | 20% |
-| 2K | 0.14 Credits/张 ≈ **$0.014/张** | $0.0175 | 20% |
-| 4K | 0.21 Credits/张 ≈ **$0.021/张** | $0.02625 | 20% |
-
----
-
-## 3. 渠道 B：`gpt-image-2-official`（OpenAI 官方渠道）
-
-### 3.1 能力
-
-文生图 / 图生图 / **局部重绘（mask）**三合一；支持 PNG / WebP **透明背景（Alpha 通道）**；15 种比例 × 1K/2K/4K；单次最多 **4 张**；参考图最多 16 张。文档称与 `gpt-image-1.5-official` 接口 95% 对齐，迁移只需改模型名。
-
-### 3.2 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `model` | string | 必填 | `gpt-image-2-official` | 固定值 |
-| `prompt` | string | 必填 | — | 支持中英文 |
-| `size` | string | 可选 | `1:1` | 同 15 种比例 + `auto`（服务端按 prompt / 参考图自动选择） |
-| `resolution` | string | 可选 | `1k` | `1k`（1024 基准）/ `2k`（2048 基准）/ `4k`（3840 基准） |
-| `quality` | string | 可选 | `auto` | `auto`（**通常等同 `low`**）/ `low` / `medium` / `high`。**4K + high 耗时 > 120 s** |
-| `background` | string | 可选 | `auto` | `auto` / `opaque` / `transparent`（输出含 Alpha 通道） |
-| `moderation` | string | 可选 | `auto` | `auto` / `low`（更宽松） |
-| `output_format` | string | 可选 | `png` | `png`（支持透明）/ `jpeg`（无 Alpha）/ `webp`（支持透明）。**`background: transparent` 时只能选 `png` 或 `webp`** |
-| `output_compression` | integer | 可选 | — | `0–100`，**仅对 `jpeg` / `webp` 有效** |
-| `n` | integer | 可选 | `1` | **1–4**。必须传纯数字 |
-| `image_urls` | array | 可选 | — | 最多 **16 张**；单张 ≤ 20 M，总体 ≤ 256 M；须是公网可直接访问的稳定 URL |
-| `mask_url` | string | 可选 | — | 局部重绘遮罩图。**必须搭配 `image_urls`**；遮罩图**必须有 Alpha 通道**，且**尺寸需与首张参考图一致** |
-| `nsfw_check` | boolean | 可选 | `false` | 同上 |
-
-### 3.3 `size × resolution` → 实际像素（官方渠道）
-
-| size | 1k | 2k | 4k |
-|---|---|---|---|
-| 1:1 | 1024×1024 | 2048×2048 | 2880×2880 |
-| 3:2 | 1536×1024 | 2048×1360 | 3520×2336 |
-| 2:3 | 1024×1536 | 1360×2048 | 2336×3520 |
-| 4:3 | 1024×768 | 2048×1536 | 3312×2480 |
-| 3:4 | 768×1024 | 1536×2048 | 2480×3312 |
-| 5:4 | 1280×1024 | 2560×2048 | 3216×2576 |
-| 4:5 | 1024×1280 | 2048×2560 | 2576×3216 |
-| 16:9 | 1536×864 | 2048×1152 | 3840×2160 |
-| 9:16 | 864×1536 | 1152×2048 | 2160×3840 |
-| 2:1 | 2048×1024 | 2688×1344 | 3840×1920 |
-| 1:2 | 1024×2048 | 1344×2688 | 1920×3840 |
-| 3:1 | 1881×836 / 1536×512 | 3072×1024 | 3840×1280 |
-| 1:3 | 887×1774 / 512×1536 | 1024×3072 | 1280×3840 |
-| 21:9 | 2016×864 | 2688×1152 | 3840×1648 |
-| 9:21 | 864×2016 | 1152×2688 | 1648×3840 |
-
-> 部分尺寸按 16 倍数和像素上限做近似映射（如 `3:2` @2K 实际 2048×1360，`21:9` @4K 是 3840×1648），以表格为准。
-
-### 3.4 价格（按 token）
-
-来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)与 [GPT Image 2 模型专属页](https://apimart.ai/zh/model/gpt-image-2)（2026-08-30，1 Credit ≈ $0.1）。
-
-| 计费项 | 我们的价格 | 官方价 | 节省 |
-|---|---|---|---|
-| 文本输入 | 40 Credits/M ≈ **$4/M** | $5/M | 20% |
-| 缓存文本输入 | 10 Credits/M ≈ **$1/M** | $1.25/M | 20% |
-| 图片输入 | 64 Credits/M ≈ **$6.4/M** | $8/M | 20% |
-| 缓存图片输入 | 16 Credits/M ≈ **$1.6/M** | $2/M | 20% |
-| 图片输出 | 240 Credits/M ≈ **$24/M** | $30/M | 20% |
-
-**官方渠道按 token 计费，不是按张**。模型专属页提供可交互的质量与分辨率估价器；2026-08-30 实际切换 `low` / `medium` / `high` 与 1K / 2K / 4K 后，当前单张输出估价如下：
-
-| 分辨率 | low（`auto` 按 low 估算） | medium | high |
-|---|---:|---:|---:|
-| 1K | **$0.00488** | **$0.04232** | **$0.16872** |
-| 2K | **$0.00968** | **$0.08576** | **$0.34264** |
-| 4K | **$0.01592** | **$0.1424** | **$0.56936** |
-
-这些值是模型页按当前输出 token 预算给出的**单张预估**，不是固定包价；实际账单还受提示词、参考图片输入 token、缓存命中和最终输出 token 影响。不能再用「1K 单价 × 4 / × 8」推算 2K / 4K，该算法会把 2K 与 4K 严重高估。`n > 1` 时 SDK 只把当前单张估价乘输出数量。
-
-> 官方来源冲突：同一模型页的 FAQ 仍写“OpenAI 尚未公布定价”，但页面的定价组件与 APIMart 总定价中心已经公开 `gpt-image-2-official` token 单价和动态估价。当前实现按 APIMart 正在展示的估价器处理，并保留“预估”语义，不把它表述为 OpenAI 最终固定价。
-
-## 4. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。两条渠道都没有这两个字段。
-- `output_format` 默认不显示、不请求（官方渠道有该字段）。
-- 两条渠道在产品中合成一个入口，但计费口径（按张 vs 按 token）、参数集合、`n` 上限（1 vs 4）必须随“渠道”分别显隐、校验、构建和计价。
-- 官方渠道估价必须使用上表九个当前档位；`auto` 暂按官方文档所述的常见行为映射为 `low`。不得按分辨率使用固定倍数推算。
-- EXT 渠道 `n` 只能是 1；`n` 必须是数字类型。
-- 图生图不传 `size` 时会**继承输入图分辨率**（EXT 渠道），产品若期望固定比例必须显式下发 `size`。
-- 局部重绘（mask）是官方渠道独有，且对遮罩图有硬性要求（含 Alpha、尺寸与首图一致），要作为独立能力分支处理。
-- 15 种比例里 `3:1` / `1:3` / `9:21` 等在其他供应商上大多不支持，跨供应商比例集合必须分别裁剪。
-
-## 5. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| GPT-Image-2 图像生成（EXT 渠道） | https://docs.apimart.ai/cn/api-reference/images/gpt-image-2/generation | 否 |
-| GPT-Image-2 官方渠道 图像生成 | https://docs.apimart.ai/cn/api-reference/images/gpt-image-2/official | 否 |
-| GPT Image 2 模型专属页（动态质量/分辨率估价） | https://apimart.ai/zh/model/gpt-image-2 | 否 |
-| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
-| 定价中心（搜 GPT-IMAGE-2-EXT / GPT-IMAGE-2-OFFICIAL） | https://apimart.ai/zh/pricing | 否 |
-| API Key 管理 | https://apimart.ai/keys | **是** |
+# GPT-Image-2 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | **两条独立渠道**：`gpt-image-2`（兼容别名 `gpt-image-2-ext`）与 `gpt-image-2-official` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> APIMart 上 GPT-Image-2 有两个平台模型与两份文档，参数与计费方式都不同；Henji 产品中合并为一个“GPT Image 2”入口，通过首项“渠道”（普通 / 官方）切换，但适配和运行时仍必须分开对待：
+>
+> - **`gpt-image-2`（EXT 渠道）**：按张按分辨率档位固定计费，参数较少
+> - **`gpt-image-2-official`（官方渠道）**：直连 OpenAI 官方模型，参数最全（quality / background / mask / output_format 等），按 **token** 计费
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/images/generations`（基于 OpenAI Images 兼容协议）→ `{ code, data: [{ status: "submitted", task_id }] }`
+- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
+- **任务结果只返回 `url`**——需要 base64 请自行下载转换
+- 其它 OpenAI 标准字段（`response_format`、`style`）**不支持，会被忽略**
+
+---
+
+## 2. 渠道 A：`gpt-image-2`（EXT）
+
+### 2.1 能力
+
+- 文生图 / 图生图（参考图最多 **16 张**，URL 与 base64 可混填）
+- 15 种比例 + `auto`
+- `1k` / `2k` / `4k` 三档分辨率
+
+### 2.2 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | `gpt-image-2` | `gpt-image-2`；兼容别名 `gpt-image-2-ext`（等价、效果一致） |
+| `prompt` | string | 必填 | — | 支持中英文。提交前经平台敏感词/安全审核，命中直接报错 |
+| `n` | integer | 可选 | `1` | **取值只能是 1**。必须传纯数字，加引号会报错 |
+| `size` | string | 可选 | `1:1` | 15 种比例 + `auto`：`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`5:4`、`4:5`、`16:9`、`9:16`、`2:1`、`1:2`、`3:1`、`1:3`、`21:9`、`9:21`。也支持直接传像素（如 `1881x836`）。**`auto` 时默认比例为 `1:1`** |
+| `resolution` | string | 可选 | `1k` | `1k` / `2k` / `4k` |
+| `image_urls` | array | 可选 | — | 传入后走图生图。**最多 16 张**（超过返回 `image_urls exceeds max 16`）；单张 ≤ 20 M，总体 ≤ 256 M；URL 与 `data:image/png;base64,...` 可混填。**不传 `size` 时输出分辨率 = 输入图分辨率**；传 `size` 则强制按指定尺寸出图 |
+| `official_fallback` | boolean | 可选 | `false` | `true` 时使用官方渠道兜底 |
+| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审 |
+
+### 2.3 `size × resolution` → 实际像素
+
+| size | 1k | 2k | 4k |
+|---|---|---|---|
+| 1:1 | 1024×1024 / 1254×1254 | 2048×2048 | 2880×2880 |
+| 3:2 | 1536×1024 | 2048×1360 | 3520×2336 |
+| 2:3 | 1024×1536 | 1360×2048 | 2336×3520 |
+| 4:3 | 1024×768 | 2048×1536 | 3312×2480 |
+| 3:4 | 768×1024 | 1536×2048 | 2480×3312 |
+| 5:4 | 1280×1024 / 1448×1086 | 2560×2048 | 3216×2576 |
+| 4:5 | 1024×1280 / 1122×1402 | 2048×2560 | 2576×3216 |
+| 16:9 | 1536×864 / 1672×941 | 2048×1152 | 3840×2160 |
+| 9:16 | 864×1536 / 941×1672 | 1152×2048 | 2160×3840 |
+| 2:1 | 2048×1024 / 1774×887 | 2688×1344 | 3840×1920 |
+| 1:2 | 1024×2048 / 887×1774 | 1344×2688 | 1920×3840 |
+| 3:1 | 1881×836 / 1536×512 | 3072×1024 | 3840×1280 |
+| 1:3 | 887×1774 / 512×1536 | 1024×3072 | 1280×3840 |
+| 21:9 | 2016×864 / 1915×821 | 2688×1152 | 3840×1648 |
+| 9:21 | 864×2016 / 821×1915 | 1152×2688 | 1648×3840 |
+
+### 2.4 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → `GPT-IMAGE-2-EXT (gpt-image-2)`（2026-08-22，1 Credit ≈ $0.1）。
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 | 0.085 Credits/张 ≈ **$0.0085/张** | $0.010625 | 20% |
+| 1K | 0.085 Credits/张 ≈ **$0.0085/张** | $0.010625 | 20% |
+| 2K | 0.14 Credits/张 ≈ **$0.014/张** | $0.0175 | 20% |
+| 4K | 0.21 Credits/张 ≈ **$0.021/张** | $0.02625 | 20% |
+
+---
+
+## 3. 渠道 B：`gpt-image-2-official`（OpenAI 官方渠道）
+
+### 3.1 能力
+
+文生图 / 图生图 / **局部重绘（mask）**三合一；支持 PNG / WebP **透明背景（Alpha 通道）**；15 种比例 × 1K/2K/4K；单次最多 **4 张**；参考图最多 16 张。文档称与 `gpt-image-1.5-official` 接口 95% 对齐，迁移只需改模型名。
+
+### 3.2 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | `gpt-image-2-official` | 固定值 |
+| `prompt` | string | 必填 | — | 支持中英文 |
+| `size` | string | 可选 | `1:1` | 同 15 种比例 + `auto`（服务端按 prompt / 参考图自动选择） |
+| `resolution` | string | 可选 | `1k` | `1k`（1024 基准）/ `2k`（2048 基准）/ `4k`（3840 基准） |
+| `quality` | string | 可选 | `auto` | `auto`（**通常等同 `low`**）/ `low` / `medium` / `high`。**4K + high 耗时 > 120 s** |
+| `background` | string | 可选 | `auto` | `auto` / `opaque` / `transparent`（输出含 Alpha 通道） |
+| `moderation` | string | 可选 | `auto` | `auto` / `low`（更宽松） |
+| `output_format` | string | 可选 | `png` | `png`（支持透明）/ `jpeg`（无 Alpha）/ `webp`（支持透明）。**`background: transparent` 时只能选 `png` 或 `webp`** |
+| `output_compression` | integer | 可选 | — | `0–100`，**仅对 `jpeg` / `webp` 有效** |
+| `n` | integer | 可选 | `1` | **1–4**。必须传纯数字 |
+| `image_urls` | array | 可选 | — | 最多 **16 张**；单张 ≤ 20 M，总体 ≤ 256 M；须是公网可直接访问的稳定 URL |
+| `mask_url` | string | 可选 | — | 局部重绘遮罩图。**必须搭配 `image_urls`**；遮罩图**必须有 Alpha 通道**，且**尺寸需与首张参考图一致** |
+| `nsfw_check` | boolean | 可选 | `false` | 同上 |
+
+### 3.3 `size × resolution` → 实际像素（官方渠道）
+
+| size | 1k | 2k | 4k |
+|---|---|---|---|
+| 1:1 | 1024×1024 | 2048×2048 | 2880×2880 |
+| 3:2 | 1536×1024 | 2048×1360 | 3520×2336 |
+| 2:3 | 1024×1536 | 1360×2048 | 2336×3520 |
+| 4:3 | 1024×768 | 2048×1536 | 3312×2480 |
+| 3:4 | 768×1024 | 1536×2048 | 2480×3312 |
+| 5:4 | 1280×1024 | 2560×2048 | 3216×2576 |
+| 4:5 | 1024×1280 | 2048×2560 | 2576×3216 |
+| 16:9 | 1536×864 | 2048×1152 | 3840×2160 |
+| 9:16 | 864×1536 | 1152×2048 | 2160×3840 |
+| 2:1 | 2048×1024 | 2688×1344 | 3840×1920 |
+| 1:2 | 1024×2048 | 1344×2688 | 1920×3840 |
+| 3:1 | 1881×836 / 1536×512 | 3072×1024 | 3840×1280 |
+| 1:3 | 887×1774 / 512×1536 | 1024×3072 | 1280×3840 |
+| 21:9 | 2016×864 | 2688×1152 | 3840×1648 |
+| 9:21 | 864×2016 | 1152×2688 | 1648×3840 |
+
+> 部分尺寸按 16 倍数和像素上限做近似映射（如 `3:2` @2K 实际 2048×1360，`21:9` @4K 是 3840×1648），以表格为准。
+
+### 3.4 价格（按 token）
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)与 [GPT Image 2 模型专属页](https://apimart.ai/zh/model/gpt-image-2)（2026-08-30，1 Credit ≈ $0.1）。
+
+| 计费项 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 文本输入 | 40 Credits/M ≈ **$4/M** | $5/M | 20% |
+| 缓存文本输入 | 10 Credits/M ≈ **$1/M** | $1.25/M | 20% |
+| 图片输入 | 64 Credits/M ≈ **$6.4/M** | $8/M | 20% |
+| 缓存图片输入 | 16 Credits/M ≈ **$1.6/M** | $2/M | 20% |
+| 图片输出 | 240 Credits/M ≈ **$24/M** | $30/M | 20% |
+
+**官方渠道按 token 计费，不是按张**。模型专属页提供可交互的质量与分辨率估价器；2026-08-30 实际切换 `low` / `medium` / `high` 与 1K / 2K / 4K 后，当前单张输出估价如下：
+
+| 分辨率 | low（`auto` 按 low 估算） | medium | high |
+|---|---:|---:|---:|
+| 1K | **$0.00488** | **$0.04232** | **$0.16872** |
+| 2K | **$0.00968** | **$0.08576** | **$0.34264** |
+| 4K | **$0.01592** | **$0.1424** | **$0.56936** |
+
+这些值是模型页按当前输出 token 预算给出的**单张预估**，不是固定包价；实际账单还受提示词、参考图片输入 token、缓存命中和最终输出 token 影响。不能再用「1K 单价 × 4 / × 8」推算 2K / 4K，该算法会把 2K 与 4K 严重高估。`n > 1` 时 SDK 只把当前单张估价乘输出数量。
+
+> 官方来源冲突：同一模型页的 FAQ 仍写“OpenAI 尚未公布定价”，但页面的定价组件与 APIMart 总定价中心已经公开 `gpt-image-2-official` token 单价和动态估价。当前实现按 APIMart 正在展示的估价器处理，并保留“预估”语义，不把它表述为 OpenAI 最终固定价。
+
+## 4. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。两条渠道都没有这两个字段。
+- `output_format` 默认不显示、不请求（官方渠道有该字段）。
+- 两条渠道在产品中合成一个入口，但计费口径（按张 vs 按 token）、参数集合、`n` 上限（1 vs 4）必须随“渠道”分别显隐、校验、构建和计价。
+- 官方渠道估价必须使用上表九个当前档位；`auto` 暂按官方文档所述的常见行为映射为 `low`。不得按分辨率使用固定倍数推算。
+- EXT 渠道 `n` 只能是 1；`n` 必须是数字类型。
+- 图生图不传 `size` 时会**继承输入图分辨率**（EXT 渠道），产品若期望固定比例必须显式下发 `size`。
+- 局部重绘（mask）是官方渠道独有，且对遮罩图有硬性要求（含 Alpha、尺寸与首图一致），要作为独立能力分支处理。
+- 15 种比例里 `3:1` / `1:3` / `9:21` 等在其他供应商上大多不支持，跨供应商比例集合必须分别裁剪。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| GPT-Image-2 图像生成（EXT 渠道） | https://docs.apimart.ai/cn/api-reference/images/gpt-image-2/generation | 否 |
+| GPT-Image-2 官方渠道 图像生成 | https://docs.apimart.ai/cn/api-reference/images/gpt-image-2/official | 否 |
+| GPT Image 2 模型专属页（动态质量/分辨率估价） | https://apimart.ai/zh/model/gpt-image-2 | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（搜 GPT-IMAGE-2-EXT / GPT-IMAGE-2-OFFICIAL） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

package/docs/model-adaptation/GPT-Image-2/GPT-Image-2_Fal.md

@@ -1,94 +1,94 @@
-# GPT-Image-2 · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-29 |
-| 模态 | 图片 |
-| 供应商 | fal.ai（聚合平台） |
-| 平台模型 ID | `openai/gpt-image-2`、`openai/gpt-image-2/edit` |
-| 接口形态 | 队列异步（推荐）或同步直连 |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-## 1. 接入协议（Fal 通用）
-
-- **鉴权**：`Authorization: Key $FAL_KEY`
-- **同步**：`POST https://fal.run/<endpoint-id>`
-- **队列**：`POST https://queue.fal.run/<endpoint-id>` → `{ request_id, status_url, response_url, cancel_url }`；`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）；`GET .../requests/{id}` 取结果
-- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
-
-## 2. 能力清单
-
-| 能力 | endpoint id |
-|---|---|
-| 文生图 | `openai/gpt-image-2` |
-| 图像编辑 + **局部重绘（mask）** | `openai/gpt-image-2/edit` |
-
-## 3. 请求参数
-
-### 3.1 `openai/gpt-image-2`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `prompt` | string | 必填 | — | 生成描述 |
-| `image_size` | 枚举或对象 | 可选 | `landscape_4_3` | 预设名、`{ width, height }`，或 `'auto'` 让模型自选。**明确尺寸时：宽高都必须是 16 的倍数、最长边 ≤ 3840 px、宽高比 ≤ 3:1、总像素在 655,360 ~ 8,294,400 之间** |
-| `quality` | string | 可选 | **`high`** | `auto` / `low` / `medium` / `high`。**Fal 默认 `high`，显著影响成本** |
-| `num_images` | integer | 可选 | `1` | 1–4 |
-| `output_format` | string | 可选 | `png` | `jpeg` / `png` / `webp` |
-| `sync_mode` | boolean | 可选 | `false` | `true` 时以 data URI 返回且不入请求历史 |
-
-### 3.2 `openai/gpt-image-2/edit`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `prompt` | string | 必填 | — | 编辑描述 |
-| `image_urls` | string[] | **必填** | — | 参考图 URL 列表，**最多 16 张** |
-| `image_size` | 枚举或对象 | 可选 | **`auto`** | `auto` 时从输入图推断 |
-| `quality` | string | 可选 | `high` | 同上 |
-| `num_images` | integer | 可选 | `1` | 1–4 |
-| `output_format` | string | 可选 | `png` | `jpeg` / `png` / `webp` |
-| `sync_mode` | boolean | 可选 | `false` | 同上 |
-| `mask_url` | string | 可选 | — | 遮罩图 URL，指明要编辑的区域（局部重绘） |
-
-## 4. 响应结构
-
-```json
-{ "images": [ { "url": "https://...", "content_type": "image/png", "width": 1024, "height": 768 } ] }
-```
-
-## 5. 价格（按 token）
-
-来源：两个端点的 `llms.txt`（2026-08-22 读取）。
-
-| 计费项 | 单价（每 1M token） |
-|---|---|
-| 文本输入 | **$5.00** |
-| 文本缓存输入 | **$1.25** |
-| 文本输出 | **$10.00** |
-| 图片输入 | **$8.00** |
-| 图片缓存输入 | **$2.00** |
-| 图片输出 | **$30.00** |
-
-> **`quality` 参数显著影响成本，Fal 默认用 `high`**——这是最贵的档位，接入时应按产品定位显式设置。总费用向上取整到 $0.0001。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点两个字段都没有。
-- `output_format`、`sync_mode` 不展示、不请求。
-- **`quality` 默认 `high` 是成本陷阱**：Fal 与 APIMart 官方渠道（默认 `auto`≈`low`）默认值相反，必须显式下发。
-- `image_size` 的明确尺寸约束很硬（16 的倍数、≤ 3840、比例 ≤ 3:1、总像素区间），画布比例换算必须做对齐，否则报错。
-- SDK 保留旧参数 ID `falGptImage2Resolution` 以兼容 0.1.5，但展示语义已校正为 `quality`，并补齐官方合法的 `auto`；独立的 `falGptImage2ImageSize`（默认 `provider`，可选 `1MP` / `2K`）避免把质量与尺寸混为一谈。GPT Image 2 在通用比例之外单独开放 `2:1`，不会把该比例无差别扩散到其他 Fal 模型。
-- `2K + 2:1` 显式映射为官方自定义尺寸约束内的 `2688×1344`（两边均为 16 的倍数、比例 2:1、约 3.61MP）；请求仍单独使用 `quality=auto/low/medium/high`，不会把产品分辨率语义误传为质量值。
-- `edit` 的 `image_urls` 是**必填**；`mask_url` 让 Fal 成为除 APIMart 官方渠道外唯一支持局部重绘的 GPT-Image-2 供应商。
-- 按 token 计费，成本估算不能按张算。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| 文生图模型页 | https://fal.ai/models/openai/gpt-image-2 | 否 |
-| 文生图 schema + 价格 | https://fal.ai/models/openai/gpt-image-2/llms.txt | 否 |
-| 编辑模型页 | https://fal.ai/models/openai/gpt-image-2/edit | 否 |
-| 编辑 schema + 价格 | https://fal.ai/models/openai/gpt-image-2/edit/llms.txt | 否 |
-| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
-| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+# GPT-Image-2 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 模态 | 图片 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `openai/gpt-image-2`、`openai/gpt-image-2/edit` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议（Fal 通用）
+
+- **鉴权**：`Authorization: Key $FAL_KEY`
+- **同步**：`POST https://fal.run/<endpoint-id>`
+- **队列**：`POST https://queue.fal.run/<endpoint-id>` → `{ request_id, status_url, response_url, cancel_url }`；`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）；`GET .../requests/{id}` 取结果
+- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
+
+## 2. 能力清单
+
+| 能力 | endpoint id |
+|---|---|
+| 文生图 | `openai/gpt-image-2` |
+| 图像编辑 + **局部重绘（mask）** | `openai/gpt-image-2/edit` |
+
+## 3. 请求参数
+
+### 3.1 `openai/gpt-image-2`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 生成描述 |
+| `image_size` | 枚举或对象 | 可选 | `landscape_4_3` | 预设名、`{ width, height }`，或 `'auto'` 让模型自选。**明确尺寸时：宽高都必须是 16 的倍数、最长边 ≤ 3840 px、宽高比 ≤ 3:1、总像素在 655,360 ~ 8,294,400 之间** |
+| `quality` | string | 可选 | **`high`** | `auto` / `low` / `medium` / `high`。**Fal 默认 `high`，显著影响成本** |
+| `num_images` | integer | 可选 | `1` | 1–4 |
+| `output_format` | string | 可选 | `png` | `jpeg` / `png` / `webp` |
+| `sync_mode` | boolean | 可选 | `false` | `true` 时以 data URI 返回且不入请求历史 |
+
+### 3.2 `openai/gpt-image-2/edit`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 编辑描述 |
+| `image_urls` | string[] | **必填** | — | 参考图 URL 列表，**最多 16 张** |
+| `image_size` | 枚举或对象 | 可选 | **`auto`** | `auto` 时从输入图推断 |
+| `quality` | string | 可选 | `high` | 同上 |
+| `num_images` | integer | 可选 | `1` | 1–4 |
+| `output_format` | string | 可选 | `png` | `jpeg` / `png` / `webp` |
+| `sync_mode` | boolean | 可选 | `false` | 同上 |
+| `mask_url` | string | 可选 | — | 遮罩图 URL，指明要编辑的区域（局部重绘） |
+
+## 4. 响应结构
+
+```json
+{ "images": [ { "url": "https://...", "content_type": "image/png", "width": 1024, "height": 768 } ] }
+```
+
+## 5. 价格（按 token）
+
+来源：两个端点的 `llms.txt`（2026-08-22 读取）。
+
+| 计费项 | 单价（每 1M token） |
+|---|---|
+| 文本输入 | **$5.00** |
+| 文本缓存输入 | **$1.25** |
+| 文本输出 | **$10.00** |
+| 图片输入 | **$8.00** |
+| 图片缓存输入 | **$2.00** |
+| 图片输出 | **$30.00** |
+
+> **`quality` 参数显著影响成本，Fal 默认用 `high`**——这是最贵的档位，接入时应按产品定位显式设置。总费用向上取整到 $0.0001。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点两个字段都没有。
+- `output_format`、`sync_mode` 不展示、不请求。
+- **`quality` 默认 `high` 是成本陷阱**：Fal 与 APIMart 官方渠道（默认 `auto`≈`low`）默认值相反，必须显式下发。
+- `image_size` 的明确尺寸约束很硬（16 的倍数、≤ 3840、比例 ≤ 3:1、总像素区间），画布比例换算必须做对齐，否则报错。
+- SDK 保留旧参数 ID `falGptImage2Resolution` 以兼容 0.1.5，但展示语义已校正为 `quality`，并补齐官方合法的 `auto`；独立的 `falGptImage2ImageSize`（默认 `provider`，可选 `1MP` / `2K`）避免把质量与尺寸混为一谈。GPT Image 2 在通用比例之外单独开放 `2:1`，不会把该比例无差别扩散到其他 Fal 模型。
+- `2K + 2:1` 显式映射为官方自定义尺寸约束内的 `2688×1344`（两边均为 16 的倍数、比例 2:1、约 3.61MP）；请求仍单独使用 `quality=auto/low/medium/high`，不会把产品分辨率语义误传为质量值。
+- `edit` 的 `image_urls` 是**必填**；`mask_url` 让 Fal 成为除 APIMart 官方渠道外唯一支持局部重绘的 GPT-Image-2 供应商。
+- 按 token 计费，成本估算不能按张算。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生图模型页 | https://fal.ai/models/openai/gpt-image-2 | 否 |
+| 文生图 schema + 价格 | https://fal.ai/models/openai/gpt-image-2/llms.txt | 否 |
+| 编辑模型页 | https://fal.ai/models/openai/gpt-image-2/edit | 否 |
+| 编辑 schema + 价格 | https://fal.ai/models/openai/gpt-image-2/edit/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |