@henjicc/ai-sdk 0.9.0 → 0.10.0

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

@@ -1,137 +1,138 @@
-# GPT-Image-2 · Grsai
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-26 |
-| 模态 | 图片 |
-| 供应商 | Grsai（聚合中转，详见 [Grsai 基础文档](../供应商/Grsai.md)） |
-| 平台模型 ID（渠道） | `gpt-image-2`（普通渠道）、`gpt-image-2-vip`（VIP 渠道） |
-| 接口形态 | 提交 `POST /v1/api/generate` + 轮询 `GET /v1/api/result`（新版统一接口，`replyType` 三选一） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录（dashboard「模型列表」页） |
-| 项目当前状态 | 已接入，[catalog/grsai/gpt-image-2.model.ts](../../../src/catalog/grsai/gpt-image-2.model.ts)，`canonicalModelId: gpt-image-2` |
-
-> Grsai 的 GPT-Image-2 只有**两个渠道**，不像 Nano Banana 系列拆出一堆 `-cl`/`-vip` 变体。两个渠道的核心差异是**分辨率参数形态不同**（比例字符串 vs 像素值）和**价格差 3~4 倍**。两个渠道都不是 OpenAI 官方直连，是 Grsai 自己的两条转发线路，所以选项没有套用「普通/官方」那套文案（那只适用于「第三方 vs 官方」的场景），代码里用自定义标签「标准/VIP」；字段名按项目约定仍走 `sharedFieldText('apiChannel')` 并声明 `role: 'channel'`，统一显示为「渠道」。
-
-## 1. 请求参数（新版统一接口）
-
-`POST /v1/api/generate`，`model` 字段二选一：
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `model` | string | 必填 | `gpt-image-2` 或 `gpt-image-2-vip` |
-| `prompt` | string | 必填 | 提示词 |
-| `images` | array\<string\> | 可选 | 参考图，base64 或 URL 混填，无需单独上传 |
-| `aspectRatio` | string | 可选 | **两个渠道取值形态不同**，见下 |
-| `replyType` | string | 可选 | `json` / `stream` / `async` |
-
-`imageSize` 字段在这个模型上**不使用**——分辨率信息直接编码进 `aspectRatio` 的像素值里（见下）。
-
-### 1.1 `gpt-image-2`（普通渠道）分辨率参数
-
-只支持 **1K** 档，`aspectRatio` 可传比例字符串（如 `16:9`）或直接传 1K 像素值：
-
-| 比例 | 像素值 |
-|---|---|
-| `auto` | — |
-| `1:1` | 1024×1024 |
-| `16:9` | 1672×941 |
-| `9:16` | 941×1672 |
-| `4:3` | 1443×1090 |
-| `3:4` | 1090×1443 |
-| `3:2` | 1536×1024 |
-| `2:3` | 1024×1536 |
-| `5:4` | 1408×1120 |
-| `4:5` | 1120×1408 |
-| `21:9` | 1920×832 |
-| `9:21` | 832×1920 |
-| `1:2` | 896×1792 |
-| `2:1` | 1792×896 |
-
-### 1.2 `gpt-image-2-vip`（VIP 渠道）分辨率参数
-
-**只支持 1–4K 像素值，不支持比例字符串**；支持自定义像素值，约束：
-
-- 最大边长 ≤ 3840px
-- 两条边都必须是 16 的倍数
-- 长边:短边 ≤ 3:1
-- 总像素数 ∈ [655,360, 8,294,400]
-
-官方给出的 1K/2K/4K 参考像素值：
-
-| 比例 | 1K | 2K | 4K |
-|---|---|---|---|
-| `auto` | — | — | — |
-| `1:1` | 1024×1024 | 2048×2048 | 2880×2880 |
-| `16:9` | 1280×720 | 2048×1152 | 3840×2160 |
-| `9:16` | 720×1280 | 1152×2048 | 2160×3840 |
-| `4:3` | 1152×864 | 2304×1728 | 3264×2448 |
-| `3:4` | 864×1152 | 1728×2304 | 2448×3264 |
-| `3:2` | 1536×1024 | 2048×1360 | 3504×2336 |
-| `2:3` | 1024×1536 | 1360×2048 | 2336×3504 |
-| `5:4` | 1120×896 | 2240×1792 | 3200×2560 |
-| `4:5` | 896×1120 | 1792×2240 | 2560×3200 |
-| `21:9` | 1456×624 | 2912×1248 | 3840×1648 |
-| `9:21` | 624×1456 | 1248×2912 | 1648×3840 |
-| `1:3` | 688×2048 | — | 1280×3840 |
-| `3:1` | 2048×688 | — | 3840×1280 |
-| `2:1` | 1536×768 | 3072×1536 | 3840×1920 |
-| `1:2` | 768×1536 | 1536×3072 | 1920×3840 |
-
-### 1.3 仅旧版接口存在的 `quality` 参数
-
-旧版 GPT Image 专用接口 `POST /v1/draw/completions`（见 [Grsai 基础文档 §3.5](../供应商/Grsai.md)）多一个 `quality` 参数：`auto` / `low` / `medium` / `high`，新版统一接口没有这个字段。若要暴露画质档位，需要评估走旧接口还是等新接口补齐——**接入前需二次确认新接口是否已隐性支持 quality（比如通过像素值间接控制），不要凭旧接口文档直接假定新接口也支持**。
-
-## 2. 响应
-
-```json
-{
-  "id": "14-5f3cf761-a4bb-486a-8016-77f490998f80",
-  "status": "succeeded",
-  "progress": 100,
-  "results": [{ "url": "https://file1.aitohumanize.com/file/....png" }],
-  "error": null
-}
-```
-
-状态枚举、轮询方式、结果链接有效期不确定项见 [Grsai 基础文档](../供应商/Grsai.md) 第 3、8 节，不在本文件重复。
-
-## 3. 价格
-
-来源：[dashboard 模型列表](https://grsai.com/zh/dashboard/models)（2026-08-26 实测，未登录可见）。价格区间由「积分消耗 × 积分单价区间」得出，区间下限对应 ¥999 最高档充值套餐（约 5 折），上限对应无优惠单价，详见 [Grsai 基础文档 §5.1](../供应商/Grsai.md)。
-
-| 渠道 | 积分消耗 | 价格区间 | 支持分辨率 |
-|---|---|---|---|
-| `gpt-image-2` | 600/次 | ¥0.03~¥0.06/次 | 1K |
-| `gpt-image-2-vip` | 2000/次 | ¥0.1~¥0.2/次 | 1K / 2K / 4K |
-
-代码里 `pricing.calculator` 按产品决定取**区间上限（无优惠价）**，即标准 ¥0.06、VIP ¥0.2，理由是不清楚用户的充值档位时按上限估算不会低报成本；用户按更高档位充值时实际扣费会更低。
-
-### 3.1 价格变动历史（公告原文摘录，供判断稳定性参考）
-
-- 2026-04-22：新增 `gpt-image-2`，¥0.03/次
-- 2026-04-30：新增 `gpt-image-2-vip`，最低价 ¥0.045/张，支持 1K/2K/4K 与 `quality`（`low`/`medium`/`high`，默认 `auto`）
-- 2026-05-08：因 OpenAI 官方风控成本上升，`gpt-image-2-vip` ¥0.045 → ¥0.065
-- 2026-06-19：`gpt-image-2-vip` 的 2K/4K 分辨率一度不可用，同日恢复
-- 2026-08-11：`gpt-image-2-vip` 的 2K/4K 分辨率再次回归，同时**所有分辨率价格统一调整为 ¥0.1/张**（此前分辨率越高价格越高）
-
-`gpt-image-2-vip` 上线以来价格上调、分辨率短暂下线各发生过至少一次，均由官方（OpenAI）侧风控或成本变化触发，印证「VIP/付费渠道也不是绝对稳定」。
-
-## 4. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。两个渠道文档都没有这两个字段。
-- `gpt-image-2` 与 `gpt-image-2-vip` 的分辨率参数**形态不同**（比例字符串 vs 纯像素值），代码用同一个「比例」下拉呈现给用户，`request.builder` 按渠道分别转换成对应格式再发送。
-- VIP 渠道当前只暴露 1K/2K/4K 三档预置像素值（第 1.2 节表格），**没有**开放自定义像素输入，因此不需要实现四条约束校验；表格里 `1:3`/`3:1` 缺 2K 官方数据，选中这两个比例时代码回退到 1K 像素值，不是虚构一个折中值。
-- `quality` 只在旧版接口出现，新旧接口是否等价未实测，代码没有暴露 `quality` 参数，若未来要补齐需要先用真实任务验证新接口是否隐性支持。
-- 图片输入统一走 `images` 字段，本地文件由公共媒体预处理层转 base64 内联，不需要接入供应商级别的上传 API。
-
-## 5. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| gpt-image-2 接口（新版统一生成，含渠道枚举与像素值表） | https://qmy27nhsd9.apifox.cn/452409160e0 | 否 |
-| 异步生成结果查询接口 | https://qmy27nhsd9.apifox.cn/452409577e0 | 否 |
-| GPT Image API 旧版文档（`quality` 参数来源） | https://grsai.ai/zh/dashboard/documents/gpt-image | 否 |
-| dashboard 模型列表（当前权威价格） | https://grsai.com/zh/dashboard/models | 否 |
-| dashboard 公告（价格变动历史） | https://grsai.com/zh/dashboard/announcements | 否 |
-| API Key 管理 | https://grsai.ai/zh/dashboard/api-keys | **是** |
+# GPT-Image-2 · Grsai
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 图片 |
+| 供应商 | Grsai（聚合中转，详见 [Grsai 基础文档](../供应商/Grsai.md)） |
+| 平台模型 ID（渠道） | `gpt-image-2`（普通渠道）、`gpt-image-2-vip`（VIP 渠道） |
+| 接口形态 | 提交 `POST /v1/api/generate` + 轮询 `GET /v1/api/result`（新版统一接口，`replyType` 三选一） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录（dashboard「模型列表」页） |
+| 项目当前状态 | 已接入，[catalog/grsai/gpt-image-2.model.ts](../../../src/catalog/grsai/gpt-image-2.model.ts)，`canonicalModelId: gpt-image-2` |
+
+> Grsai 的 GPT-Image-2 只有**两个渠道**，不像 Nano Banana 系列拆出一堆 `-cl`/`-vip` 变体。两个渠道的核心差异是**分辨率参数形态不同**（比例字符串 vs 像素值）和**价格差 3~4 倍**。两个渠道都不是 OpenAI 官方直连，是 Grsai 自己的两条转发线路，所以选项没有套用「普通/官方」那套文案（那只适用于「第三方 vs 官方」的场景），代码里用自定义标签「标准/VIP」；字段名按项目约定仍走 `sharedFieldText('apiChannel')` 并声明 `role: 'channel'`，统一显示为「渠道」。
+
+## 1. 请求参数（新版统一接口）
+
+`POST /v1/api/generate`，`model` 字段二选一：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `model` | string | 必填 | `gpt-image-2` 或 `gpt-image-2-vip` |
+| `prompt` | string | 必填 | 提示词 |
+| `images` | array\<string\> | 可选 | 参考图，base64 或 URL 混填，无需单独上传 |
+| `aspectRatio` | string | 可选 | **两个渠道取值形态不同**，见下 |
+| `replyType` | string | 可选 | `json` / `stream` / `async` |
+
+`imageSize` 字段在这个模型上**不使用**——分辨率信息直接编码进 `aspectRatio` 的像素值里（见下）。
+
+### 1.1 `gpt-image-2`（普通渠道）分辨率参数
+
+只支持 **1K** 档，`aspectRatio` 可传比例字符串（如 `16:9`）或直接传 1K 像素值：
+
+| 比例 | 像素值 |
+|---|---|
+| `auto` | — |
+| `1:1` | 1024×1024 |
+| `16:9` | 1672×941 |
+| `9:16` | 941×1672 |
+| `4:3` | 1443×1090 |
+| `3:4` | 1090×1443 |
+| `3:2` | 1536×1024 |
+| `2:3` | 1024×1536 |
+| `5:4` | 1408×1120 |
+| `4:5` | 1120×1408 |
+| `21:9` | 1920×832 |
+| `9:21` | 832×1920 |
+| `1:2` | 896×1792 |
+| `2:1` | 1792×896 |
+
+### 1.2 `gpt-image-2-vip`（VIP 渠道）分辨率参数
+
+**只支持 1–4K 像素值，不支持比例字符串**；支持自定义像素值，约束：
+
+- 最大边长 ≤ 3840px
+- 两条边都必须是 16 的倍数
+- 长边:短边 ≤ 3:1
+- 总像素数 ∈ [655,360, 8,294,400]
+
+官方给出的 1K/2K/4K 参考像素值：
+
+| 比例 | 1K | 2K | 4K |
+|---|---|---|---|
+| `auto` | — | — | — |
+| `1:1` | 1024×1024 | 2048×2048 | 2880×2880 |
+| `16:9` | 1280×720 | 2048×1152 | 3840×2160 |
+| `9:16` | 720×1280 | 1152×2048 | 2160×3840 |
+| `4:3` | 1152×864 | 2304×1728 | 3264×2448 |
+| `3:4` | 864×1152 | 1728×2304 | 2448×3264 |
+| `3:2` | 1536×1024 | 2048×1360 | 3504×2336 |
+| `2:3` | 1024×1536 | 1360×2048 | 2336×3504 |
+| `5:4` | 1120×896 | 2240×1792 | 3200×2560 |
+| `4:5` | 896×1120 | 1792×2240 | 2560×3200 |
+| `21:9` | 1456×624 | 2912×1248 | 3840×1648 |
+| `9:21` | 624×1456 | 1248×2912 | 1648×3840 |
+| `1:3` | 688×2048 | — | 1280×3840 |
+| `3:1` | 2048×688 | — | 3840×1280 |
+| `2:1` | 1536×768 | 3072×1536 | 3840×1920 |
+| `1:2` | 768×1536 | 1536×3072 | 1920×3840 |
+
+### 1.3 仅旧版接口存在的 `quality` 参数
+
+旧版 GPT Image 专用接口 `POST /v1/draw/completions`（见 [Grsai 基础文档 §3.5](../供应商/Grsai.md)）多一个 `quality` 参数：`auto` / `low` / `medium` / `high`，新版统一接口没有这个字段。若要暴露画质档位，需要评估走旧接口还是等新接口补齐——**接入前需二次确认新接口是否已隐性支持 quality（比如通过像素值间接控制），不要凭旧接口文档直接假定新接口也支持**。
+
+## 2. 响应
+
+```json
+{
+  "id": "14-5f3cf761-a4bb-486a-8016-77f490998f80",
+  "status": "succeeded",
+  "progress": 100,
+  "results": [{ "url": "https://file1.aitohumanize.com/file/....png" }],
+  "error": null
+}
+```
+
+状态枚举、轮询方式、结果链接有效期不确定项见 [Grsai 基础文档](../供应商/Grsai.md) 第 3、8 节，不在本文件重复。
+
+## 3. 价格
+
+来源：[dashboard 模型列表](https://grsai.com/zh/dashboard/models)（2026-08-26 实测，未登录可见）。价格区间由「积分消耗 × 积分单价区间」得出，区间下限对应 ¥999 最高档充值套餐（约 5 折），上限对应无优惠单价，详见 [Grsai 基础文档 §5.1](../供应商/Grsai.md)。
+
+| 渠道 | 积分消耗 | 价格区间 | 支持分辨率 |
+|---|---|---|---|
+| `gpt-image-2` | 600/次 | ¥0.03~¥0.06/次 | 1K |
+| `gpt-image-2-vip` | 2000/次 | ¥0.1~¥0.2/次 | 1K / 2K / 4K |
+
+代码里 `pricing.calculator` 按产品决定取**区间上限（无优惠价）**，即标准 ¥0.06、VIP ¥0.2，理由是不清楚用户的充值档位时按上限估算不会低报成本；用户按更高档位充值时实际扣费会更低。
+
+### 3.1 价格变动历史（公告原文摘录，供判断稳定性参考）
+
+- 2026-04-22：新增 `gpt-image-2`，¥0.03/次
+- 2026-04-30：新增 `gpt-image-2-vip`，最低价 ¥0.045/张，支持 1K/2K/4K 与 `quality`（`low`/`medium`/`high`，默认 `auto`）
+- 2026-05-08：因 OpenAI 官方风控成本上升，`gpt-image-2-vip` ¥0.045 → ¥0.065
+- 2026-06-19：`gpt-image-2-vip` 的 2K/4K 分辨率一度不可用，同日恢复
+- 2026-08-11：`gpt-image-2-vip` 的 2K/4K 分辨率再次回归，同时**所有分辨率价格统一调整为 ¥0.1/张**（此前分辨率越高价格越高）
+
+`gpt-image-2-vip` 上线以来价格上调、分辨率短暂下线各发生过至少一次，均由官方（OpenAI）侧风控或成本变化触发，印证「VIP/付费渠道也不是绝对稳定」。
+
+## 4. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。两个渠道文档都没有这两个字段。
+- `gpt-image-2` 与 `gpt-image-2-vip` 的分辨率参数**形态不同**（比例字符串 vs 纯像素值），代码用同一个「比例」下拉呈现给用户，`request.builder` 按渠道分别转换成对应格式再发送。
+- VIP 渠道当前只暴露 1K/2K/4K 三档预置像素值（第 1.2 节表格），**没有**开放自定义像素输入，因此不需要实现四条约束校验；表格里 `1:3`/`3:1` 缺 2K 官方数据，选中这两个比例时代码回退到 1K 像素值，不是虚构一个折中值。
+- 比例下拉统一展示 VIP 全集；标准渠道没有 `1:3`/`3:1`，选中时按数值贴近用户选的比例（分别落到 `9:21`/`21:9`），不退回正方形（2026-11-08 真实请求验收发现曾退回 `1:1`）。
+- `quality` 只在旧版接口出现，新旧接口是否等价未实测，代码没有暴露 `quality` 参数，若未来要补齐需要先用真实任务验证新接口是否隐性支持。
+- 图片输入统一走 `images` 字段，本地文件由公共媒体预处理层转 base64 内联，不需要接入供应商级别的上传 API。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| gpt-image-2 接口（新版统一生成，含渠道枚举与像素值表） | https://qmy27nhsd9.apifox.cn/452409160e0 | 否 |
+| 异步生成结果查询接口 | https://qmy27nhsd9.apifox.cn/452409577e0 | 否 |
+| GPT Image API 旧版文档（`quality` 参数来源） | https://grsai.ai/zh/dashboard/documents/gpt-image | 否 |
+| dashboard 模型列表（当前权威价格） | https://grsai.com/zh/dashboard/models | 否 |
+| dashboard 公告（价格变动历史） | https://grsai.com/zh/dashboard/announcements | 否 |
+| API Key 管理 | https://grsai.ai/zh/dashboard/api-keys | **是** |

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

@@ -1,93 +1,97 @@
-# GPT-Image-2 · KIE
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 图片 |
-| 供应商 | KIE.ai（聚合平台） |
-| 平台模型 ID | `gpt-image-2-text-to-image`、`gpt-image-2-image-to-image` |
-| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.kie.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model, callBackUrl?, input }`
-- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
-- **终态**：`state` ∈ `waiting` / `queuing` / `generating` / `success` / `fail`
-- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`
-
-## 2. 能力清单
-
-| 能力 | model |
-|---|---|
-| 文生图 | `gpt-image-2-text-to-image` |
-| 图生图（最多 16 张输入图） | `gpt-image-2-image-to-image` |
-
-> KIE 上的 GPT-Image-2 **没有 mask 局部重绘、没有 quality、没有透明背景、没有多张输出**。这些能力只在 APIMart 官方渠道或 Fal 上有。
-
-## 3. 请求参数
-
-### 3.1 `gpt-image-2-text-to-image`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `input.prompt` | string | 必填 | — | 1–**20000** 字符（远高于其他供应商） |
-| `input.aspect_ratio` | string | 可选 | `auto` | `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` |
-| `input.resolution` | string | 可选 | — | `1K` / `2K` / `4K`（**大写**） |
-
-**档位限制（文档明列）**：`2K` 和 `4K` **不支持** `5:4`、`4:5`、`3:1`、`1:3`、`9:21` 这 5 个比例。
-
-### 3.2 `gpt-image-2-image-to-image`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `input.prompt` | string | 必填 | — | 最多 20000 字符 |
-| `input.input_urls` | array | 必填 | — | 输入图片 URL 数组，**最多 16 张**。注意字段名是 **`input_urls`**，不是 `image_urls` |
-| `input.aspect_ratio` | string | 可选 | `auto` | 同上 16 个取值 |
-| `input.resolution` | string | 可选 | — | `1K` / `2K` / `4K` |
-
-**图生图的档位限制（与文生图不同，文档明列）**：
-- `5:4` 和 `4:5` 比例**只支持 1K**
-- `1:1` 比例**无法生成 4K**
-- `auto` 比例或未传比例参数时**只能生成 1K**，否则**无法创建任务**
-
-## 4. 响应结构
-
-`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`。
-
-## 5. 价格
-
-来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `gpt image`；1 Credit = $0.005）。
-
-| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
-|---|---|---|---|---|
-| 文生图 1k | 6 /张 | **$0.03/张** | $0.219 | 86.3% |
-| 文生图 2k | 10 /张 | **$0.05/张** | $0.234 | 78.6% |
-| 文生图 4k | 16 /张 | **$0.08/张** | $0.413 | 80.6% |
-| 图生图 1k | 6 /张 | **$0.03/张** | $0.219 | 86.3% |
-| 图生图 2k | 10 /张 | **$0.05/张** | $0.234 | 78.6% |
-| 图生图 4k | 16 /张 | **$0.08/张** | $0.413 | 80.6% |
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
-- **比例 × 分辨率的组合有硬性禁区**，且文生图与图生图规则不同：图生图侧 `auto`/不传比例只能出 1K，否则**任务直接创建失败**。UI 层必须做联动禁用，不能让用户选出非法组合。
-- 图生图的图片字段名是 `input_urls`（不是通用的 `image_urls`），容易写错。
-- 提示词上限 20000 字符，是所有供应商里最宽松的。
-- KIE 版没有 quality / 透明背景 / mask / 多张输出，能力集合明显小于 APIMart 官方渠道与 Fal。
-- `resolution` 用大写 `1K/2K/4K`，APIMart 用小写 `1k/2k/4k`，不要共用常量。
-- `resultJson` 是 JSON 字符串，必须二次 parse。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| GPT Image 2 文生图 | https://docs.kie.ai/cn/market/gpt/gpt-image-2-text-to-image | 否 |
-| GPT Image 2 图生图 | https://docs.kie.ai/cn/market/gpt/gpt-image-2-image-to-image | 否 |
-| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
-| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
-| 定价页（搜 `gpt image`） | https://kie.ai/pricing | 否 |
-| API Key 管理 | https://kie.ai/api-key | **是** |
+# GPT-Image-2 · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 图片 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `gpt-image-2-text-to-image`、`gpt-image-2-image-to-image` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model, callBackUrl?, input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **终态**：`state` ∈ `waiting` / `queuing` / `generating` / `success` / `fail`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`
+
+## 2. 能力清单
+
+| 能力 | model |
+|---|---|
+| 文生图 | `gpt-image-2-text-to-image` |
+| 图生图（最多 16 张输入图） | `gpt-image-2-image-to-image` |
+
+> KIE 上的 GPT-Image-2 **没有 mask 局部重绘、没有 quality、没有透明背景、没有多张输出**。这些能力只在 APIMart 官方渠道或 Fal 上有。
+
+## 3. 请求参数
+
+### 3.1 `gpt-image-2-text-to-image`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 1–**20000** 字符（远高于其他供应商） |
+| `input.aspect_ratio` | string | 可选 | `auto` | `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` |
+| `input.resolution` | string | 可选 | — | `1K` / `2K` / `4K`（**大写**） |
+
+**档位限制（文档明列）**：`2K` 和 `4K` **不支持** `5:4`、`4:5`、`3:1`、`1:3`、`9:21` 这 5 个比例。
+
+### 3.2 `gpt-image-2-image-to-image`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 最多 20000 字符 |
+| `input.input_urls` | array | 必填 | — | 输入图片 URL 数组，**最多 16 张**。注意字段名是 **`input_urls`**，不是 `image_urls` |
+| `input.aspect_ratio` | string | 可选 | `auto` | 同上 16 个取值 |
+| `input.resolution` | string | 可选 | — | `1K` / `2K` / `4K` |
+
+**图生图的档位限制（与文生图不同，文档明列）**：
+- `5:4` 和 `4:5` 比例**只支持 1K**
+- `1:1` 比例**无法生成 4K**
+- `auto` 比例或未传比例参数时**只能生成 1K**，否则**无法创建任务**
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`。
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `gpt image`；1 Credit = $0.005）。
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| 文生图 1k | 6 /张 | **$0.03/张** | $0.219 | 86.3% |
+| 文生图 2k | 10 /张 | **$0.05/张** | $0.234 | 78.6% |
+| 文生图 4k | 16 /张 | **$0.08/张** | $0.413 | 80.6% |
+| 图生图 1k | 6 /张 | **$0.03/张** | $0.219 | 86.3% |
+| 图生图 2k | 10 /张 | **$0.05/张** | $0.234 | 78.6% |
+| 图生图 4k | 16 /张 | **$0.08/张** | $0.413 | 80.6% |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
+- **比例 × 分辨率的组合有硬性禁区**，且文生图与图生图规则不同：图生图侧 `auto`/不传比例只能出 1K，否则**任务直接创建失败**。UI 层必须做联动禁用，不能让用户选出非法组合。
+- 图生图的图片字段名是 `input_urls`（不是通用的 `image_urls`），容易写错。
+- 提示词上限 20000 字符，是所有供应商里最宽松的。
+- KIE 版没有 quality / 透明背景 / mask / 多张输出，能力集合明显小于 APIMart 官方渠道与 Fal。
+- `resolution` 用大写 `1K/2K/4K`，APIMart 用小写 `1k/2k/4k`，不要共用常量。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| GPT Image 2 文生图 | https://docs.kie.ai/cn/market/gpt/gpt-image-2-text-to-image | 否 |
+| GPT Image 2 图生图 | https://docs.kie.ai/cn/market/gpt/gpt-image-2-image-to-image | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `gpt image`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |
+
+## 2026-11-08 比例与分辨率的搭配在界面上收住
+
+构建器一直按文档拒绝的搭配，现在界面同步过滤：5:4、4:5 只有 1K；文生图的 3:1、1:3、9:21 只有 1K；图生图的 1:1 没有 4K。智能比例改为只在当前分辨率与有无参考图下支持的比例里挑最接近的，不会自己挑出平台会拒绝的组合（例如方图 + 4K 图生图会挑 3:4）。

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

@@ -1,66 +1,66 @@
-# GPT Image 2.5 · APIMart
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-09-10 |
-| 模态 | 图片；不替换 GPT Image 2 |
-| 官方渠道 | `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` |
-| Ext渠道 | `model=gpt-image-2.5-ext`，`version=flare/sunburst` |
-| 文档/价格 | 公开，无需登录；模型页与Ext Tab均已实际展开 |
-
-## 请求与价格
-
-Base URL `https://api.apimart.ai`；Bearer API Key；JSON `POST /v1/images/generations`。
-共享 provider 已发送 `Idempotency-Key` 和 `X-APIMart-Response-Version: 2026-07-27`，无需为模型另建协议。
-`prompt` 必填非空；`image_urls: string[]` 最多16张，有图即编辑；`n` 为整数1–4，默认1。
-官方渠道只接受公开HTTP(S)参考图，使用官方 `POST /v1/uploads/images` 上传；Ext还接受data URL。
-
-| 参数 | 官方渠道 | Ext渠道 |
-|---|---|---|
-| 版本 | 编码进model | version=flare/sunburst，默认flare |
-| size | auto、1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、21:9、9:21、3:1、1:3或像素 | auto、1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5、21:9 |
-| resolution | 1k/2k/4k，默认1k；像素size时忽略 | 1K/2K/4K，默认1K |
-| quality | auto/low/medium/high/xhigh/max，API默认auto | 未定义，不发送 |
-| background | auto/opaque/transparent | 未定义，不发送 |
-| moderation | auto/low，服务默认low | 未定义，不发送 |
-| output_format | png/jpeg/webp，默认png | 未定义 |
-| output_compression | 0–100，仅jpeg/webp | 未定义 |
-
-产品一个入口，渠道先于版本；默认Ext、Flare、智能比例、1K、1张；官方质量使用medium（与平台playground初始值一致）。
-智能比例本地计算，无图1:1。output_format/output_compression/moderation/seed不展示、不发送；默认PNG允许透明背景。
-新版官方文档未定义mask，不沿用2的mask字段。Ext不能显示质量和背景。
-
-Ext实时基础价两个版本相同：1K $0.0085、2K $0.014、4K $0.021/张，参考图不额外收费。
-官方渠道实际公开价每百万token：文本输入$4、缓存$1、图片输入$6.4、缓存$1.6、图片输出$24。
-API正文$5/$1.25/$8/$2/$30是OpenAI原价；按实时价格页20%折扣采用上述平台价，不与充值优惠混淆。
-官方页面提供不同尺寸的输出token参考表；估算按size/resolution/quality/n计算输出部分，不含提示词及参考图输入；auto保守按max。
-1024方图low/medium/high/xhigh/max分别196/439/1756/3122/7024输出token。
-两版token单价一致不保证旧版与新版每张费用一致；官方文档说明2.5 medium/high输出token约为2同名档四分之一。
-
-## 任务状态契约
-
-`GET /v1/tasks/{task_id}`，同用户API Key。返回URL位于`data.result.images[].url[]`。
-
-| 事件 | 前置 | 字段与空值语义 | 下一状态/输出 | 终态/副作用/复用 |
-|---|---|---|---|---|
-| HTTP202提交 | 未提交 | data.id非空string，object=generation.task，status=pending；poll_url可用 | 保存ID，pending | 独立HTTP请求 |
-| HTTP200兼容提交 | 未提交 | data数组，data[0].task_id非空string、status=submitted | 保存ID，pending | 兼容旧格式 |
-| pending/submitted | 提交后 | status非空；结果可未就绪 | pending | 继续轮询 |
-| processing | pending | progress数值，不能代替终态 | pending | 继续轮询 |
-| completed | pending | result.images须有有效URL；usage/cost可提供实际计费 | completed | 停止轮询并保存结果 |
-| failed | pending | error.message说明原因 | 报错 | 停止轮询，平台退还预留资金 |
-| canceled/cancelled | pending | 查询协议取消终态 | 报错 | 停止轮询 |
-| HTTP400/401/402/429 | 任意请求 | error对象 | 报错 | 不盲重放生成 |
-
-允许重复pending；官方未保证严格状态顺序及断线恢复。SDK取消/超时结束本地等待，不保证远端撤销；空成功拒绝；复用既有provider释放规则。
-官方示例/字段表见 `tests/fixtures/gpt-image-2.5/`；未进行付费请求。
-
-## 原始链接索引
-
-以下无需登录，已实测正文：
-- [官方渠道完整参数、尺寸及输出token表](https://docs.apimart.ai/en/api-reference/images/gpt-image-2.5/generation.md)
-- [Ext完整参数与版本响应](https://docs.apimart.ai/en/api-reference/images/gpt-image-2.5-ext/generation.md)
-- [任务查询](https://docs.apimart.ai/en/api-reference/tasks/status.md)
-- [模型页及两个渠道的实时价格](https://apimart.ai/zh/model/gpt-image-2-5)
-- [实时定价](https://apimart.ai/zh/pricing)
-- [OpenAI费用边界](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare)
+# GPT Image 2.5 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-09-10 |
+| 模态 | 图片；不替换 GPT Image 2 |
+| 官方渠道 | `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` |
+| Ext渠道 | `model=gpt-image-2.5-ext`，`version=flare/sunburst` |
+| 文档/价格 | 公开，无需登录；模型页与Ext Tab均已实际展开 |
+
+## 请求与价格
+
+Base URL `https://api.apimart.ai`；Bearer API Key；JSON `POST /v1/images/generations`。
+共享 provider 已发送 `Idempotency-Key` 和 `X-APIMart-Response-Version: 2026-07-27`，无需为模型另建协议。
+`prompt` 必填非空；`image_urls: string[]` 最多16张，有图即编辑；`n` 为整数1–4，默认1。
+官方渠道只接受公开HTTP(S)参考图，使用官方 `POST /v1/uploads/images` 上传；Ext还接受data URL。
+
+| 参数 | 官方渠道 | Ext渠道 |
+|---|---|---|
+| 版本 | 编码进model | version=flare/sunburst，默认flare |
+| size | auto、1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、21:9、9:21、3:1、1:3或像素 | auto、1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5、21:9 |
+| resolution | 1k/2k/4k，默认1k；像素size时忽略 | 1K/2K/4K，默认1K |
+| quality | auto/low/medium/high/xhigh/max，API默认auto | 未定义，不发送 |
+| background | auto/opaque/transparent | 未定义，不发送 |
+| moderation | auto/low，服务默认low | 未定义，不发送 |
+| output_format | png/jpeg/webp，默认png | 未定义 |
+| output_compression | 0–100，仅jpeg/webp | 未定义 |
+
+产品一个入口，渠道先于版本；默认Ext、Flare、智能比例、1K、1张；官方质量使用medium（与平台playground初始值一致）。
+智能比例本地计算，无图1:1。output_format/output_compression/moderation/seed不展示、不发送；默认PNG允许透明背景。
+新版官方文档未定义mask，不沿用2的mask字段。Ext不能显示质量和背景。
+
+Ext实时基础价两个版本相同：1K $0.0085、2K $0.014、4K $0.021/张，参考图不额外收费。
+官方渠道实际公开价每百万token：文本输入$4、缓存$1、图片输入$6.4、缓存$1.6、图片输出$24。
+API正文$5/$1.25/$8/$2/$30是OpenAI原价；按实时价格页20%折扣采用上述平台价，不与充值优惠混淆。
+官方页面提供不同尺寸的输出token参考表；估算按size/resolution/quality/n计算输出部分，不含提示词及参考图输入；auto保守按max。
+1024方图low/medium/high/xhigh/max分别196/439/1756/3122/7024输出token。
+两版token单价一致不保证旧版与新版每张费用一致；官方文档说明2.5 medium/high输出token约为2同名档四分之一。
+
+## 任务状态契约
+
+`GET /v1/tasks/{task_id}`，同用户API Key。返回URL位于`data.result.images[].url[]`。
+
+| 事件 | 前置 | 字段与空值语义 | 下一状态/输出 | 终态/副作用/复用 |
+|---|---|---|---|---|
+| HTTP202提交 | 未提交 | data.id非空string，object=generation.task，status=pending；poll_url可用 | 保存ID，pending | 独立HTTP请求 |
+| HTTP200兼容提交 | 未提交 | data数组，data[0].task_id非空string、status=submitted | 保存ID，pending | 兼容旧格式 |
+| pending/submitted | 提交后 | status非空；结果可未就绪 | pending | 继续轮询 |
+| processing | pending | progress数值，不能代替终态 | pending | 继续轮询 |
+| completed | pending | result.images须有有效URL；usage/cost可提供实际计费 | completed | 停止轮询并保存结果 |
+| failed | pending | error.message说明原因 | 报错 | 停止轮询，平台退还预留资金 |
+| canceled/cancelled | pending | 查询协议取消终态 | 报错 | 停止轮询 |
+| HTTP400/401/402/429 | 任意请求 | error对象 | 报错 | 不盲重放生成 |
+
+允许重复pending；官方未保证严格状态顺序及断线恢复。SDK取消/超时结束本地等待，不保证远端撤销；空成功拒绝；复用既有provider释放规则。
+官方示例/字段表见 `tests/fixtures/gpt-image-2.5/`；未进行付费请求。
+
+## 原始链接索引
+
+以下无需登录，已实测正文：
+- [官方渠道完整参数、尺寸及输出token表](https://docs.apimart.ai/en/api-reference/images/gpt-image-2.5/generation.md)
+- [Ext完整参数与版本响应](https://docs.apimart.ai/en/api-reference/images/gpt-image-2.5-ext/generation.md)
+- [任务查询](https://docs.apimart.ai/en/api-reference/tasks/status.md)
+- [模型页及两个渠道的实时价格](https://apimart.ai/zh/model/gpt-image-2-5)
+- [实时定价](https://apimart.ai/zh/pricing)
+- [OpenAI费用边界](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare)