@henjicc/ai-sdk 0.2.8

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

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

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

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

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

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

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

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

package/docs/model-adaptation/GPT-OSS-20B/GPT-OSS-20B_Groq.md

@@ -0,0 +1,62 @@
+# GPT-OSS 20B · Groq
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 模态 | LLM（文本生成/推理） |
+| 供应商 | GroqCloud（不是 xAI Grok） |
+| 平台模型 ID | `openai/gpt-oss-20b` |
+| Say-It 决策 | 保留为 Groq 默认模型 |
+| 文档/价格 | 公开无需登录；Key/账单需登录 |
+
+## 1. 端点与鉴权
+
+```text
+POST https://api.groq.com/openai/v1/chat/completions
+Authorization: Bearer <GROQ_API_KEY>
+Content-Type: application/json
+```
+
+可复用 OpenAI 兼容 Chat/SSE 传输。必填 `model/messages`，支持 `stream/tools/response_format/max_completion_tokens/temperature/top_p/stop/seed`。`n` 只能为 1；`logprobs/logit_bias/top_logprobs/messages[].name` 会返回 400。
+
+## 2. 模型发现
+
+```text
+GET https://api.groq.com/openai/v1/models
+GET https://api.groq.com/openai/v1/models/openai/gpt-oss-20b
+```
+
+两个端点都需 Bearer Key。列表返回 `data[]`，包含 `id/active/context_window/owned_by`；单模型还可返 `max_completion_tokens`。Say-It 可默认选本模型，同时允许用户从实时模型列表切换。
+
+## 3. 推理参数
+
+- `reasoning_effort`: `low|medium|high`，默认 `medium`。
+- GPT-OSS 20B **不支持 `reasoning_format`**。默认的 reasoning 在 assistant message 的 `reasoning` 字段。
+- 可用 `include_reasoning=false` 隐藏推理；`include_reasoning` 与 `reasoning_format` 互斥。
+
+Say-It 现有为 Groq Qwen3 设置 `reasoning_effort=none/default` 和 `reasoning_format=parsed` 的逻辑不能套到本模型。
+
+## 4. 能力、限制与价格
+
+| 项目 | 官方当前值 |
+|---|---|
+| 状态 | Production |
+| 上下文 | 131,072 tokens |
+| 最大输出 | 65,536 tokens |
+| 速度 | 约 1000 tokens/s |
+| Developer Plan | 250K TPM / 1K RPM |
+| 输入 | $0.075 / 1M tokens |
+| 输出 | $0.30 / 1M tokens |
+
+错误体 `{error:{message,type}}`。对 429/498/500/502/503 进行受控重试，但 400/401/403/404/413/422 不盲目重试；499 归一为用户取消。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| 模型状态/价格/限制 | https://console.groq.com/docs/models | 否 |
+| OpenAI 兼容 | https://console.groq.com/docs/openai | 否 |
+| Chat/Models API | https://console.groq.com/docs/api-reference | 否 |
+| Reasoning | https://console.groq.com/docs/reasoning | 否 |
+| 错误码 | https://console.groq.com/docs/errors | 否 |
+| API Key | https://console.groq.com/keys | **是** |