@henjicc/ai-sdk 0.2.8 → 0.4.0

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

@@ -1,137 +1,137 @@
-# 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-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 | **是** |

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

@@ -1,93 +1,93 @@
-# 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-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 | **是** |

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

@@ -0,0 +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)

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

@@ -0,0 +1,55 @@
+# GPT Image 2.5 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-09-10 |
+| 模型路由 | `openai/gpt-image-2.5/{flare,sunburst}/{text-to-image,edit}` |
+| 文档/价格 | 公开，无需登录；四份端点实时llms.txt已核对 |
+
+## 请求与计费
+
+`POST https://queue.fal.run/<路由>`，`Authorization: Key <key>`，JSON。
+Flare/Sunburst显式选择，无图文生图、有图edit；默认Flare、智能比例、1K、high、1张、auto背景。
+
+| 字段 | 类型 | 约束 |
+|---|---|---|
+| prompt | string，必填 | 生成/编辑说明 |
+| image_urls | string[]，编辑必填 | 最多16张；文生图不发送 |
+| mask_url | string，编辑可选 | 遮罩；复用应用内绘制/编辑和官方上传 |
+| image_size | object或枚举 | {width,height}，16倍数、边≤3840、比例≤3、面积655360–8294400；文生图API默认landscape_4_3，编辑auto |
+| quality | string | auto/low/medium/high/xhigh/max；API默认high |
+| background | string | auto/transparent/opaque；默认auto |
+| num_images | integer | 1–10，默认1（旧2为1–4） |
+| output_format | string | jpeg/png/webp，默认png；产品不展示、不请求 |
+| output_compression | integer | 0–100；仅jpeg/webp，产品不请求 |
+| sync_mode | boolean | 默认false；产品采用队列、不请求 |
+
+尺寸选项用合法像素明确提交；不把smart/auto直传。遮罩基于第一张参考图，通过共享派生媒体契约创建、继续编辑和源图变化失效。
+token基础价与2相同：文本输入$5/M、缓存$1.25/M；图片输入$8/M、缓存$2/M、输出$30/M。Fal端点页另写文本输出$10/M，但图像模型无文本输出。
+Fal公开实测1024方图low/medium/high约$0.0060/$0.0133/$0.0528（编辑单参考图约$0.0142/$0.0215/$0.0610）；不是固定每张价格。
+计价仅给输出参考估算，采用APIMart公开同型号尺寸/token参考表乘Fal输出单价，明确跨来源参考而非Fal报价；输入token另计，auto按max。不沿用2旧high=$0.211。
+
+## 队列契约
+
+| 事件/状态 | 前置 | 字段与空值 | 下一状态/输出 | 终态/副作用/复用 |
+|---|---|---|---|---|
+| 提交 | 未提交 | request_id非空，status_url/response_url/cancel_url由服务返回 | 保存ID和同源URL，pending | 独立HTTP |
+| IN_QUEUE | 提交后 | status必需；queue_position可选 | pending | 继续轮询 |
+| IN_PROGRESS | pending | status必需；logs可为空 | pending | 继续轮询 |
+| COMPLETED | pending | 状态完成仍需读取response_url | 读取images | 不把状态响应当图片 |
+| 结果 | COMPLETED后 | images数组，ImageFile.url必须有效 | completed/images | 停止轮询 |
+| 请求/任务错误 | 任意 | HTTP错误或错误响应 | 报错 | 停止等待 |
+
+重复处理中事件允许；官方未保证严格顺序。取消API为PUT cancel_url；本次沿用SDK现有本地取消，不新增远端取消动作。取消/超时释放本地等待，不承诺退费。空结果拒绝；复用既有Fal同源URL校验、轮询与取消测试。
+官方字面示例与字段表位于 `tests/fixtures/gpt-image-2.5/`；无付费真网证据。
+
+## 原始链接索引
+
+均公开无需登录：
+- [Flare文生图](https://fal.ai/models/openai/gpt-image-2.5/flare/text-to-image/llms.txt)
+- [Flare编辑](https://fal.ai/models/openai/gpt-image-2.5/flare/edit/llms.txt)
+- [Sunburst文生图](https://fal.ai/models/openai/gpt-image-2.5/sunburst/text-to-image/llms.txt)
+- [Sunburst编辑](https://fal.ai/models/openai/gpt-image-2.5/sunburst/edit/llms.txt)
+- [Fal实测价格表](https://fal.ai/gpt-image-2.5)
+- [队列协议](https://fal.ai/docs/documentation/model-apis/inference/queue)
+- [同型号尺寸与输出token参考表](https://docs.apimart.ai/en/api-reference/images/gpt-image-2.5/generation.md)