@henjicc/ai-sdk 0.8.0 → 0.10.0

package/docs/model-adaptation/Nano-Banana-2-Lite/Nano-Banana-2-Lite_APIMart.md

@@ -1,79 +1,79 @@
-# Nano Banana 2 Lite · APIMart
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-28 |
-| 模态 | 图片 |
-| 供应商 | APIMart（聚合平台） |
-| 平台模型 ID | `gemini-3.1-flash-lite-image`（官方渠道）/ `gemini-3.1-flash-lite-image-ext`（常规 EXT 渠道） |
-| 接口形态 | **异步任务** |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-| 项目对照 | [catalog/apimart/nano-banana-2-lite.model.ts](../../../src/catalog/apimart/nano-banana-2-lite.model.ts)，`canonicalModelId: 'nano-banana-2-lite'`，与 [Nano Banana 2](../Nano-Banana-2/Nano-Banana-2_APIMart.md) 是**两个独立的产品模型**，不是同一模型下的渠道/分辨率选项 |
-
-> Nano Banana 2 Lite 是 Gemini 3.1 系列里**最快、最便宜**的图像模型，走 Developer API 的 `interactions` 端点，主打规模化低成本出图。它与 Nano Banana 2 主模型共享同一份 API 文档页（`generation-lite` 是主文档页的姊妹页），但**能力集合、限制、计费方式都不同**，本项目在代码里已经把它拆成独立模型（`canonicalModelId: nano-banana-2-lite`），本文件把它对应拆成独立文档，不再挂在 Nano Banana 2 文件里。
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.apimart.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /v1/images/generations` → `{ code, data: [{ status: "submitted", task_id }] }`
-- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
-- **回调**：支持 `webhook` 参数（base 地址，平台回调 `webhook + /callback`），桌面端不用，走轮询
-
-## 2. 与 Nano Banana 2 主模型的能力差异（文档明列）
-
-| 项 | 主模型（Nano Banana 2） | Lite |
-|---|---|---|
-| 分辨率 | 0.5K / 1K / 2K / 4K | **仅 1K**。传 2K/4K/0.5K 会**静默降级为 1K，不报错**，前端不应暴露分辨率选项 |
-| 比例 | 15 个（含 1:4 / 4:1 / 1:8 / 8:1 极端比例） | **11 个**（`auto`、`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`16:9`、`9:16`、`5:4`、`4:5`、`21:9`），**无极端比例** |
-| `n` | 只能 1 | **1–4**（`n>1` 后端并发多次上游请求，按实际成功张数计费；文档建议前端固定传 1） |
-| `google_search` / `google_image_search` | 支持 | **不支持**。上游未开放 Search 工具（会返回 "Search as tool is not enabled for this model"），平台适配器也不下发。**传了不报错、照常出图，但没有任何搜索增强效果** |
-| `official_fallback` | 支持 | **不支持**，且无 `-official` 变体 |
-| 计费 | 按张固定价 | **按 token** |
-| `mask_url` 局部重绘 | 不支持 | 不支持（Gemini 系列走 aspect ratio + 参考图，不走蒙版） |
-
-## 3. 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `model` | string | 必填 | `gemini-3.1-flash-lite-image` | 官方渠道；常规渠道使用 EXT 别名 `gemini-3.1-flash-lite-image-ext` |
-| `prompt` | string | 必填 | — | 图像生成描述 |
-| `size` | string | 可选 | — | 11 个比例（见第 2 节），无极端比例；`auto` 行为与主模型一致，建议始终显式指定 |
-| `n` | integer | 可选 | `1` | 1–4，建议前端固定传 1 |
-| `image_urls` | array | 可选 | — | 参考图，最多 **14 张**；单张 ≤ 10 MB；格式 jpeg/png/webp；支持公网 URL 或完整 Data URI |
-| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审 |
-| `webhook` | string | 可选 | — | 回调基址，桌面端不使用 |
-
-## 4. 价格
-
-来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)与[Nano Banana 2 模型页的 Lite 档](https://apimart.ai/zh/model/nano-banana-3-api)（2026-08-28，1 Credit ≈ $0.1）。
-
-| 计费口径 | 我们的价格 | 官方价 | 节省 |
-|---|---|---|---|
-| `NANO-BANANA-2-LITE-EXT`（按张，1K） | 0.125 Credits/张 ≈ **$0.0125/张** | $0.015625 | 20% |
-| `NANO-BANANA-2-LITE`（官方渠道，按 token）文本/图片输入 | 2 Credits/M ≈ $0.2/M | — | — |
-| `NANO-BANANA-2-LITE`（官方渠道，按 token）文本输出 | 12 Credits/M ≈ $1.2/M | — | — |
-| `NANO-BANANA-2-LITE`（官方渠道，按 token）图片输出 | 240 Credits/M ≈ **$24/M** | — | — |
-
-SDK 对官方渠道采用模型页当前估算 **$0.032/张**；实际账单仍按 token 结算。
-
-## 5. 水印
-
-所有 Lite 生成的图片含 Google **SynthID** 隐形水印（上游行为，**无法关闭**）。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。本模型没有这两个字段。
-- **必须与 Nano Banana 2 主模型分开建模**：分辨率档位、比例集合、`n` 上限、搜索增强、计费方式全都不同，这点在代码里已经落实（`nano-banana-2-lite.model.ts` 独立文件、独立 `canonicalModelId`），文档现在也拆开，避免下次调研时把两者当成同一模型的参数分支去理解。
-- 「传高分辨率静默降级」和「传 `google_search` 静默无效」两处是**沉默失败**，UI 上不要暴露这些开关，否则用户会以为生效了。
-- SDK 用首位 `apimartNanoBanana2LiteChannel` 参数表达双渠道，默认 `standard` 保持 0.1.5 的 EXT 请求；`official` 精确映射到无 `-official` 后缀的 `gemini-3.1-flash-lite-image`，估价同步切换为 token 模型页单张估算。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Nano Banana Lite 图像生成 | https://docs.apimart.ai/cn/api-reference/images/gemini-3.1-flash/generation-lite | 否 |
-| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
-| 定价中心（搜 NANO-BANANA-2-LITE-EXT / NANO-BANANA-2-LITE） | https://apimart.ai/zh/pricing | 否 |
-| API Key 管理 | https://apimart.ai/keys | **是** |
+# Nano Banana 2 Lite · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `gemini-3.1-flash-lite-image`（官方渠道）/ `gemini-3.1-flash-lite-image-ext`（常规 EXT 渠道） |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 项目对照 | [catalog/apimart/nano-banana-2-lite.model.ts](../../../src/catalog/apimart/nano-banana-2-lite.model.ts)，`canonicalModelId: 'nano-banana-2-lite'`，与 [Nano Banana 2](../Nano-Banana-2/Nano-Banana-2_APIMart.md) 是**两个独立的产品模型**，不是同一模型下的渠道/分辨率选项 |
+
+> Nano Banana 2 Lite 是 Gemini 3.1 系列里**最快、最便宜**的图像模型，走 Developer API 的 `interactions` 端点，主打规模化低成本出图。它与 Nano Banana 2 主模型共享同一份 API 文档页（`generation-lite` 是主文档页的姊妹页），但**能力集合、限制、计费方式都不同**，本项目在代码里已经把它拆成独立模型（`canonicalModelId: nano-banana-2-lite`），本文件把它对应拆成独立文档，不再挂在 Nano Banana 2 文件里。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/images/generations` → `{ code, data: [{ status: "submitted", task_id }] }`
+- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
+- **回调**：支持 `webhook` 参数（base 地址，平台回调 `webhook + /callback`），桌面端不用，走轮询
+
+## 2. 与 Nano Banana 2 主模型的能力差异（文档明列）
+
+| 项 | 主模型（Nano Banana 2） | Lite |
+|---|---|---|
+| 分辨率 | 0.5K / 1K / 2K / 4K | **仅 1K**。传 2K/4K/0.5K 会**静默降级为 1K，不报错**，前端不应暴露分辨率选项 |
+| 比例 | 15 个（含 1:4 / 4:1 / 1:8 / 8:1 极端比例） | **11 个**（`auto`、`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`16:9`、`9:16`、`5:4`、`4:5`、`21:9`），**无极端比例** |
+| `n` | 只能 1 | **1–4**（`n>1` 后端并发多次上游请求，按实际成功张数计费；文档建议前端固定传 1） |
+| `google_search` / `google_image_search` | 支持 | **不支持**。上游未开放 Search 工具（会返回 "Search as tool is not enabled for this model"），平台适配器也不下发。**传了不报错、照常出图，但没有任何搜索增强效果** |
+| `official_fallback` | 支持 | **不支持**，且无 `-official` 变体 |
+| 计费 | 按张固定价 | **按 token** |
+| `mask_url` 局部重绘 | 不支持 | 不支持（Gemini 系列走 aspect ratio + 参考图，不走蒙版） |
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | `gemini-3.1-flash-lite-image` | 官方渠道；常规渠道使用 EXT 别名 `gemini-3.1-flash-lite-image-ext` |
+| `prompt` | string | 必填 | — | 图像生成描述 |
+| `size` | string | 可选 | — | 11 个比例（见第 2 节），无极端比例；`auto` 行为与主模型一致，建议始终显式指定 |
+| `n` | integer | 可选 | `1` | 1–4，建议前端固定传 1 |
+| `image_urls` | array | 可选 | — | 参考图，最多 **14 张**；单张 ≤ 10 MB；格式 jpeg/png/webp；支持公网 URL 或完整 Data URI |
+| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审 |
+| `webhook` | string | 可选 | — | 回调基址，桌面端不使用 |
+
+## 4. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)与[Nano Banana 2 模型页的 Lite 档](https://apimart.ai/zh/model/nano-banana-3-api)（2026-08-28，1 Credit ≈ $0.1）。
+
+| 计费口径 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| `NANO-BANANA-2-LITE-EXT`（按张，1K） | 0.125 Credits/张 ≈ **$0.0125/张** | $0.015625 | 20% |
+| `NANO-BANANA-2-LITE`（官方渠道，按 token）文本/图片输入 | 2 Credits/M ≈ $0.2/M | — | — |
+| `NANO-BANANA-2-LITE`（官方渠道，按 token）文本输出 | 12 Credits/M ≈ $1.2/M | — | — |
+| `NANO-BANANA-2-LITE`（官方渠道，按 token）图片输出 | 240 Credits/M ≈ **$24/M** | — | — |
+
+SDK 对官方渠道采用模型页当前估算 **$0.032/张**；实际账单仍按 token 结算。
+
+## 5. 水印
+
+所有 Lite 生成的图片含 Google **SynthID** 隐形水印（上游行为，**无法关闭**）。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。本模型没有这两个字段。
+- **必须与 Nano Banana 2 主模型分开建模**：分辨率档位、比例集合、`n` 上限、搜索增强、计费方式全都不同，这点在代码里已经落实（`nano-banana-2-lite.model.ts` 独立文件、独立 `canonicalModelId`），文档现在也拆开，避免下次调研时把两者当成同一模型的参数分支去理解。
+- 「传高分辨率静默降级」和「传 `google_search` 静默无效」两处是**沉默失败**，UI 上不要暴露这些开关，否则用户会以为生效了。
+- SDK 用首位 `apimartNanoBanana2LiteChannel` 参数表达双渠道，默认 `standard` 保持 0.1.5 的 EXT 请求；`official` 精确映射到无 `-official` 后缀的 `gemini-3.1-flash-lite-image`，估价同步切换为 token 模型页单张估算。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Nano Banana Lite 图像生成 | https://docs.apimart.ai/cn/api-reference/images/gemini-3.1-flash/generation-lite | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（搜 NANO-BANANA-2-LITE-EXT / NANO-BANANA-2-LITE） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

package/docs/model-adaptation/Nano-Banana-2-Lite/Nano-Banana-2-Lite_Grsai.md

@@ -1,65 +1,65 @@
-# Nano Banana 2 Lite · Grsai
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-26 |
-| 模态 | 图片 |
-| 供应商 | Grsai（聚合中转，详见 [Grsai 基础文档](../供应商/Grsai.md)） |
-| 平台模型 ID（渠道） | `nano-banana-2-lite`（只有这一个渠道，见下方排除说明） |
-| 接口形态 | 提交 `POST /v1/api/generate` + 轮询 `GET /v1/api/result`（新版统一接口，`replyType` 三选一） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录（dashboard「模型列表」页） |
-| 项目当前状态 | 已接入，[catalog/grsai/nano-banana-2-lite.model.ts](../../../src/catalog/grsai/nano-banana-2-lite.model.ts)，`canonicalModelId: nano-banana-2-lite` |
-
-> 本项目把 Nano Banana 2 Lite 当作独立产品模型（`canonicalModelId: nano-banana-2-lite`），与 [Nano Banana 2](../Nano-Banana-2/Nano-Banana-2_Grsai.md) 主模型分开建档，这个 Grsai 平台模型名原本记录在 Nano Banana 2 的 Grsai 文档里，现拆分到本文件，与 APIMart / KIE 的文档结构保持一致。
-
-## 1. `nano-banana-fast` 已被明确排除，不要与本模型混淆
-
-dashboard「模型列表」页还有一个 `nano-banana-fast`，积分消耗（440/次）、价格区间（¥0.022~¥0.044/次）、能力标签都与 `nano-banana-2-lite` **完全相同**，非常容易被当成同一个模型的两个入口收进 schema。
-
-**它不是 Nano Banana 2 Lite，本项目不适配它**：`nano-banana-fast` 属于最早期「香蕉 1」世代的命名——2026-07-01 公告显示，谷歌官方下架 `gemini-2.5-flash-image`（香蕉 1）后，Grsai 下架了 `nano-banana`，`nano-banana-fast` 这个名字保留了下来并「切换底层模型」，此后实际跑在新的 Gemini 3.1 Lite 底层上，只是名字还留着旧世代的痕迹。本项目适配范围只到 Nano Banana 第 2 代与 Nano Banana Pro，不包含初代「香蕉」体系的任何遗留命名。完整排除记录见 [Grsai 基础文档 §7](../供应商/Grsai.md)。
-
-后续调研如果发现价格/规格与 `nano-banana-2-lite` 一样接近的新名字，先去 Grsai 基础文档 §7 确认是否已经记录过，不要重复讨论是否该收进来。
-
-## 2. 请求参数（新版统一接口）
-
-`POST /v1/api/generate`：
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `model` | string | 必填 | `nano-banana-2-lite` |
-| `prompt` | string | 必填 | 提示词 |
-| `images` | array\<string\> | 可选 | 参考图，base64 或 URL 混填，无需单独上传 |
-| `aspectRatio` | string | 可选 | 通用 11 档（`auto`/`1:1`/`16:9`/`9:16`/`4:3`/`3:4`/`3:2`/`2:3`/`5:4`/`4:5`/`21:9`）；极端比例（`1:4`/`4:1`/`1:8`/`8:1`）文档标注为「nano-banana-2 系列额外支持」，Lite 是否包含在内未逐渠道验证 |
-| `replyType` | string | 可选 | `json` / `stream` / `async` |
-
-代码没有为本模型注册 `imageSize` 参数、也不发送该字段——dashboard 页面未给这个渠道标注分辨率档位标签，类比 APIMart/KIE 的 Lite 均固定 1K，选择不暴露而不是猜一个可能报错的值。若后续证实 Grsai 这一档确实支持可选分辨率，再补参数。
-
-## 3. 价格
-
-来源：[dashboard 模型列表](https://grsai.com/zh/dashboard/models)（2026-08-26 实测，未登录可见）。价格区间由「积分消耗 × 积分单价区间」得出，详见 [Grsai 基础文档 §5.1](../供应商/Grsai.md)。
-
-| 渠道 | 积分消耗 | 价格区间 | 支持分辨率 |
-|---|---|---|---|
-| `nano-banana-2-lite` | 440/次 | ¥0.022~¥0.044/次 | 未标注（推断仅默认档） |
-
-作为对照，同为 Lite 定位的其他供应商价格：APIMart EXT 渠道 **$0.0125/张**（约¥0.09，2026-08-22 汇率粗算）、KIE **$0.02/张**（约¥0.14）。Grsai 的 ¥0.022~¥0.044 区间在同类里明显更低，与「渠道更便宜」的定位一致。
-
-## 4. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。本渠道没有这两个字段。
-- **不要把 `nano-banana-fast` 收进本模型的渠道枚举**，它属于已排除的初代「香蕉」命名，见第 1 节与 [Grsai 基础文档 §7](../供应商/Grsai.md)。
-- 代码没有暴露分辨率参数（见第 2 节），本渠道上分辨率参数的真实行为（报错 / 静默降级 / 直接忽略）未实测，接入前建议先用真实任务核实是否真的可以传 `imageSize` 拿到更高分辨率。
-- `pricing.calculator` 固定返回区间上限（无优惠价）¥0.044。
-- 与 [Nano Banana 2 主模型的 Grsai 文档](../Nano-Banana-2/Nano-Banana-2_Grsai.md) 共享同一套响应结构、状态枚举、结果链接有效期等不确定项，见 [Grsai 基础文档](../供应商/Grsai.md) 第 3、8 节，不在本文件重复。
-
-## 5. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| nano-banana 接口（新版统一生成，含渠道枚举与比例说明） | https://qmy27nhsd9.apifox.cn/452392911e0 | 否 |
-| 异步生成结果查询接口 | https://qmy27nhsd9.apifox.cn/452409577e0 | 否 |
-| Nano Banana API 旧版文档 | https://grsai.ai/zh/dashboard/documents/nano-banana | 否 |
-| dashboard 模型列表（当前权威价格） | https://grsai.com/zh/dashboard/models | 否 |
-| dashboard 公告（`nano-banana-fast` 排除依据的来源公告） | https://grsai.com/zh/dashboard/announcements | 否 |
-| API Key 管理 | https://grsai.ai/zh/dashboard/api-keys | **是** |
+# Nano Banana 2 Lite · Grsai
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-26 |
+| 模态 | 图片 |
+| 供应商 | Grsai（聚合中转，详见 [Grsai 基础文档](../供应商/Grsai.md)） |
+| 平台模型 ID（渠道） | `nano-banana-2-lite`（只有这一个渠道，见下方排除说明） |
+| 接口形态 | 提交 `POST /v1/api/generate` + 轮询 `GET /v1/api/result`（新版统一接口，`replyType` 三选一） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录（dashboard「模型列表」页） |
+| 项目当前状态 | 已接入，[catalog/grsai/nano-banana-2-lite.model.ts](../../../src/catalog/grsai/nano-banana-2-lite.model.ts)，`canonicalModelId: nano-banana-2-lite` |
+
+> 本项目把 Nano Banana 2 Lite 当作独立产品模型（`canonicalModelId: nano-banana-2-lite`），与 [Nano Banana 2](../Nano-Banana-2/Nano-Banana-2_Grsai.md) 主模型分开建档，这个 Grsai 平台模型名原本记录在 Nano Banana 2 的 Grsai 文档里，现拆分到本文件，与 APIMart / KIE 的文档结构保持一致。
+
+## 1. `nano-banana-fast` 已被明确排除，不要与本模型混淆
+
+dashboard「模型列表」页还有一个 `nano-banana-fast`，积分消耗（440/次）、价格区间（¥0.022~¥0.044/次）、能力标签都与 `nano-banana-2-lite` **完全相同**，非常容易被当成同一个模型的两个入口收进 schema。
+
+**它不是 Nano Banana 2 Lite，本项目不适配它**：`nano-banana-fast` 属于最早期「香蕉 1」世代的命名——2026-07-01 公告显示，谷歌官方下架 `gemini-2.5-flash-image`（香蕉 1）后，Grsai 下架了 `nano-banana`，`nano-banana-fast` 这个名字保留了下来并「切换底层模型」，此后实际跑在新的 Gemini 3.1 Lite 底层上，只是名字还留着旧世代的痕迹。本项目适配范围只到 Nano Banana 第 2 代与 Nano Banana Pro，不包含初代「香蕉」体系的任何遗留命名。完整排除记录见 [Grsai 基础文档 §7](../供应商/Grsai.md)。
+
+后续调研如果发现价格/规格与 `nano-banana-2-lite` 一样接近的新名字，先去 Grsai 基础文档 §7 确认是否已经记录过，不要重复讨论是否该收进来。
+
+## 2. 请求参数（新版统一接口）
+
+`POST /v1/api/generate`：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `model` | string | 必填 | `nano-banana-2-lite` |
+| `prompt` | string | 必填 | 提示词 |
+| `images` | array\<string\> | 可选 | 参考图，base64 或 URL 混填，无需单独上传 |
+| `aspectRatio` | string | 可选 | 通用 11 档（`auto`/`1:1`/`16:9`/`9:16`/`4:3`/`3:4`/`3:2`/`2:3`/`5:4`/`4:5`/`21:9`）；极端比例（`1:4`/`4:1`/`1:8`/`8:1`）文档标注为「nano-banana-2 系列额外支持」，Lite 是否包含在内未逐渠道验证 |
+| `replyType` | string | 可选 | `json` / `stream` / `async` |
+
+代码没有为本模型注册 `imageSize` 参数、也不发送该字段——dashboard 页面未给这个渠道标注分辨率档位标签，类比 APIMart/KIE 的 Lite 均固定 1K，选择不暴露而不是猜一个可能报错的值。若后续证实 Grsai 这一档确实支持可选分辨率，再补参数。
+
+## 3. 价格
+
+来源：[dashboard 模型列表](https://grsai.com/zh/dashboard/models)（2026-08-26 实测，未登录可见）。价格区间由「积分消耗 × 积分单价区间」得出，详见 [Grsai 基础文档 §5.1](../供应商/Grsai.md)。
+
+| 渠道 | 积分消耗 | 价格区间 | 支持分辨率 |
+|---|---|---|---|
+| `nano-banana-2-lite` | 440/次 | ¥0.022~¥0.044/次 | 未标注（推断仅默认档） |
+
+作为对照，同为 Lite 定位的其他供应商价格：APIMart EXT 渠道 **$0.0125/张**（约¥0.09，2026-08-22 汇率粗算）、KIE **$0.02/张**（约¥0.14）。Grsai 的 ¥0.022~¥0.044 区间在同类里明显更低，与「渠道更便宜」的定位一致。
+
+## 4. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。本渠道没有这两个字段。
+- **不要把 `nano-banana-fast` 收进本模型的渠道枚举**，它属于已排除的初代「香蕉」命名，见第 1 节与 [Grsai 基础文档 §7](../供应商/Grsai.md)。
+- 代码没有暴露分辨率参数（见第 2 节），本渠道上分辨率参数的真实行为（报错 / 静默降级 / 直接忽略）未实测，接入前建议先用真实任务核实是否真的可以传 `imageSize` 拿到更高分辨率。
+- `pricing.calculator` 固定返回区间上限（无优惠价）¥0.044。
+- 与 [Nano Banana 2 主模型的 Grsai 文档](../Nano-Banana-2/Nano-Banana-2_Grsai.md) 共享同一套响应结构、状态枚举、结果链接有效期等不确定项，见 [Grsai 基础文档](../供应商/Grsai.md) 第 3、8 节，不在本文件重复。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| nano-banana 接口（新版统一生成，含渠道枚举与比例说明） | https://qmy27nhsd9.apifox.cn/452392911e0 | 否 |
+| 异步生成结果查询接口 | https://qmy27nhsd9.apifox.cn/452409577e0 | 否 |
+| Nano Banana API 旧版文档 | https://grsai.ai/zh/dashboard/documents/nano-banana | 否 |
+| dashboard 模型列表（当前权威价格） | https://grsai.com/zh/dashboard/models | 否 |
+| dashboard 公告（`nano-banana-fast` 排除依据的来源公告） | https://grsai.com/zh/dashboard/announcements | 否 |
+| API Key 管理 | https://grsai.ai/zh/dashboard/api-keys | **是** |

package/docs/model-adaptation/Nano-Banana-2-Lite/Nano-Banana-2-Lite_KIE.md

@@ -1,64 +1,64 @@
-# Nano Banana 2 Lite · KIE
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-26 |
-| 模态 | 图片 |
-| 供应商 | KIE.ai（聚合平台） |
-| 平台模型 ID | `nano-banana-2-lite` |
-| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-| 项目对照 | [catalog/kie/nano-banana-2-lite.model.ts](../../../src/catalog/kie/nano-banana-2-lite.model.ts)，`canonicalModelId: 'nano-banana-2-lite'`，与 [Nano Banana 2](../Nano-Banana-2/Nano-Banana-2_KIE.md) 是**两个独立的产品模型**，不是同一模型下的分辨率选项 |
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.kie.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: 'nano-banana-2-lite', input }`
-- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
-- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`
-
-## 2. 与 Nano Banana 2 主模型的差异
-
-| 字段 | 主模型（`nano-banana-2`） | Lite（`nano-banana-2-lite`） |
-|---|---|---|
-| 参考图字段名 | `input.image_input` | **`input.image_urls`**（字段名不同，容易写错） |
-| 参考图数量上限 | 14 张 | **10 张** |
-| `input.resolution` | 支持（`1K`/`2K`/`4K`） | **没有** |
-| `input.output_format` | 支持（`jpg`/`png`） | **没有** |
-| `input.aspect_ratio` 必填性 | 可选，默认 `auto` | **必填**，默认 `auto` |
-
-## 3. 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `input.prompt` | string | 必填 | — | 最多 20000 字符 |
-| `input.aspect_ratio` | string | **必填** | `auto` | 15 个取值：`1:1`、`2:3`、`3:2`、`1:4`、`4:1`、`3:4`、`4:3`、`4:5`、`5:4`、`1:8`、`8:1`、`9:16`、`16:9`、`21:9`、`auto`（含极端比例，与主模型一致） |
-| `input.image_urls` | array | 可选 | `[]` | 最多 **10 张**。纯文生图可传空数组或不传。支持 `image/jpeg`、`image/png`、`image/webp`；单张 ≤ 30 MB |
-
-## 4. 响应结构
-
-`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`，与主模型完全一致。
-
-## 5. 价格
-
-来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `nano banana`；1 Credit = $0.005）。定价页**未单独列出 `nano-banana-2-lite` 条目**，当前代码固定价 **$0.02/张**（见 [catalog/kie/nano-banana-2-lite.model.ts](../../../src/catalog/kie/nano-banana-2-lite.model.ts) 的 `pricing.calculator`），这个数字未在定价页找到直接对应来源，接入前建议用真实任务核实一次实际扣费。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。本模型没有这两个字段。
-- **参考图字段名与主模型不同**（`image_urls` vs `image_input`），数量上限也不同（10 vs 14），是最容易写错的一处。
-- 没有 `resolution`、没有 `output_format`，不要照抄主模型的参数面板。
-- `aspect_ratio` 在 Lite 上是必填（虽然有默认值 `auto`），建模时仍要按必填处理请求体拼装。
-- `resultJson` 是 JSON 字符串，必须二次 parse，与主模型一致。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Nano Banana 2 Lite | https://docs.kie.ai/cn/market/google/nano-banana-2-lite | 否 |
-| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
-| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
-| 定价页（搜 `nano banana`，未见独立 Lite 条目） | https://kie.ai/pricing | 否 |
-| API Key 管理 | https://kie.ai/api-key | **是** |
+# Nano Banana 2 Lite · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-26 |
+| 模态 | 图片 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `nano-banana-2-lite` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 项目对照 | [catalog/kie/nano-banana-2-lite.model.ts](../../../src/catalog/kie/nano-banana-2-lite.model.ts)，`canonicalModelId: 'nano-banana-2-lite'`，与 [Nano Banana 2](../Nano-Banana-2/Nano-Banana-2_KIE.md) 是**两个独立的产品模型**，不是同一模型下的分辨率选项 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: 'nano-banana-2-lite', input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`
+
+## 2. 与 Nano Banana 2 主模型的差异
+
+| 字段 | 主模型（`nano-banana-2`） | Lite（`nano-banana-2-lite`） |
+|---|---|---|
+| 参考图字段名 | `input.image_input` | **`input.image_urls`**（字段名不同，容易写错） |
+| 参考图数量上限 | 14 张 | **10 张** |
+| `input.resolution` | 支持（`1K`/`2K`/`4K`） | **没有** |
+| `input.output_format` | 支持（`jpg`/`png`） | **没有** |
+| `input.aspect_ratio` 必填性 | 可选，默认 `auto` | **必填**，默认 `auto` |
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 最多 20000 字符 |
+| `input.aspect_ratio` | string | **必填** | `auto` | 15 个取值：`1:1`、`2:3`、`3:2`、`1:4`、`4:1`、`3:4`、`4:3`、`4:5`、`5:4`、`1:8`、`8:1`、`9:16`、`16:9`、`21:9`、`auto`（含极端比例，与主模型一致） |
+| `input.image_urls` | array | 可选 | `[]` | 最多 **10 张**。纯文生图可传空数组或不传。支持 `image/jpeg`、`image/png`、`image/webp`；单张 ≤ 30 MB |
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`，与主模型完全一致。
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `nano banana`；1 Credit = $0.005）。定价页**未单独列出 `nano-banana-2-lite` 条目**，当前代码固定价 **$0.02/张**（见 [catalog/kie/nano-banana-2-lite.model.ts](../../../src/catalog/kie/nano-banana-2-lite.model.ts) 的 `pricing.calculator`），这个数字未在定价页找到直接对应来源，接入前建议用真实任务核实一次实际扣费。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。本模型没有这两个字段。
+- **参考图字段名与主模型不同**（`image_urls` vs `image_input`），数量上限也不同（10 vs 14），是最容易写错的一处。
+- 没有 `resolution`、没有 `output_format`，不要照抄主模型的参数面板。
+- `aspect_ratio` 在 Lite 上是必填（虽然有默认值 `auto`），建模时仍要按必填处理请求体拼装。
+- `resultJson` 是 JSON 字符串，必须二次 parse，与主模型一致。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Nano Banana 2 Lite | https://docs.kie.ai/cn/market/google/nano-banana-2-lite | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `nano banana`，未见独立 Lite 条目） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |

package/docs/model-adaptation/Nano-Banana-2.1/Nano-Banana-2.1_APIMart.md

@@ -0,0 +1,35 @@
+# Nano Banana 2.1 — APIMart
+
+采集日期：2026-10-12。BrowserOS neo 公开页面，只读；没有登录、读取凭据或发起生成。
+
+## 请求与计价契约
+
+Base URL `https://api.apimart.ai`；POST `/v1/images/generations`，Bearer 鉴权。官方 model `gemini-nano-banana-2.1`、Ext `gemini-nano-banana-2.1-ext`。`prompt` 必填 string；`size` 可选，默认 auto，支持 1:1/2:3/3:2/1:4/4:1/3:4/4:3/4:5/5:4/1:8/8:1/9:16/16:9/21:9；`resolution` 1K（默认）/2K/4K。Ext 的 1:4/4:1/1:8/8:1 仅 1K。`n` 官方整数 1–4（默认1），Ext 仅1；`image_urls` 可选 string[]，数量未声明，单张20MB，Ext总计50MB。`official_fallback` Ext可选 boolean，默认false，开启后转官方须按Token计费；本实现固定false，避免渠道切换与估价失配。`webhook` 未接入，使用正式共享轮询服务。
+
+价格：https://apimart.ai/zh/model/nano-banana-2-1 。Ext 1K/2K/4K 为 $0.020/$0.025/$0.030 每张。官方按实际Token结算，模型卡金卡档输出图像参考 $0.02688/$0.04032/$0.09072；仅作输出估算，输入与思考另计，不能承诺按张固定价或把会员折扣推成全账号价格。每个输出都即时下载；营销页72小时与任务字段`expires_at`/接口24小时有差异，以实际有效期字段为准。
+
+## 事件契约矩阵
+
+| 事件/状态 | 传输形态 | 前置状态 | 字段路径与类型（必需性） | 缺省/空值语义 | 合法下一状态 | 应用输出 | 副作用与终态 | 连接生命周期 |
+|---|---|---|---|---|---|---|---|---|
+| 提交响应 | POST /v1/images/generations；GET /v1/tasks/{id} | 未提交 | task_id:string（提交必需）；status:string（查询必需）；result.images[].url:string[]（成功必需） | 缺标识且缺有效媒体明确报错；不自动重提 | pending/processing/completed | pending任务标识或有效同步结果 | 保存可恢复查询的标识；仅提交一次 | 单次HTTP结束 |
+| pending | 状态查询JSON | 同一任务已提交/待处理 | task_id:string（提交必需）；status:string（查询必需）；result.images[].url:string[]（成功必需） | 成功结果必需；未完成可省略result，不能用缺结果判断失败 | pending/processing/completed/failed | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| processing | 状态查询JSON | 同一任务已提交/待处理 | task_id:string（提交必需）；status:string（查询必需）；result.images[].url:string[]（成功必需） | 成功结果必需；未完成可省略result，不能用缺结果判断失败 | pending/processing/completed/failed | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| completed | 状态查询JSON | 同一任务已提交/待处理 | task_id:string（提交必需）；status:string（查询必需）；result.images[].url:string[]（成功必需） | 成功结果必需；未完成可省略result，不能用缺结果判断失败；空成功终态是负例，不是合法成功 | 终态 | 全部结果URL，不裁剪 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+| failed | 失败结果JSON/HTTP错误 | 同一任务已提交/待处理 | 错误字段文案可省略；失败状态/结果错误必须明确 | 可无媒体；错误文案缺省使用供应商失败说明 | 终态 | 统一错误，无媒体 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+
+不变量：提交必须获得有效任务标识或同步有效结果。仅任务标识不能充当有效final；结果数量不擅自裁剪。重复待处理状态合法；乱序、终态后修改、先终态后另发结果的官方保证未说明。可凭原任务标识重新查询，不自动重提扣费请求。取消使用本地AbortSignal释放轮询与监听；除Fal官方队列取消接口外，供应商是否停止云端扣费未说明，本批不改远端取消实现。网络断开及查询超时使用已有统一错误/重试与恢复机制，不写第二套轮询或日志。
+
+## Fixture 与验证
+
+`tests/fixtures/nano-banana-2.1/`按页面JSON示例留存官方字面内容（URL/ID不可联网替换），字段表构造另标，负例独立标synthetic-negative。请求、枚举、数量边界、价格及四渠道全部结果/空终态/错误/取消由精确测试覆盖；断牙验证临时移除APIMart空结果拒绝不变量并确认失败后恢复。
+
+## 选型与能力覆盖
+
+复用现有供应商adapter、共享轮询和上传服务；无新网络库或自研协议。模型差异写catalog，中文/英文与渠道联动写presentation；现有通用模型发现与生成操作覆盖本批，属于已有能力的数据扩充，无需专用Agent工具。
+
+## 原始链接索引
+
+- [请求契约](https://docs.apimart.ai/cn/api-reference/images/gemini-nano-banana-2.1/generation.md)：无需登录。
+- [轮询/队列契约](https://docs.apimart.ai/cn/api-reference/tasks/status)：无需登录。
+- 本文内模型页/公告/价格链接：无需登录；真实生成与账单另需用户授权，未验。

package/docs/model-adaptation/Nano-Banana-2.1/Nano-Banana-2.1_Fal.md

@@ -0,0 +1,37 @@
+# Nano Banana 2.1 — Fal
+
+采集日期：2026-10-12。BrowserOS neo 公开页面，只读；没有登录、读取凭据或发起生成。
+
+## 请求与计价契约
+
+Base URL `https://queue.fal.run`，POST `/google/nano-banana-2.1`（生成）或 `/google/nano-banana-2.1/edit`（编辑），`Authorization: Key ...`。编辑官方schema：https://fal.ai/models/google/nano-banana-2.1/edit/llms.txt 。`prompt`必填string；`num_images`整数1–4、默认1；`aspect_ratio`默认auto，14种比例同APIMart；`resolution`默认1K，1K/2K/4K；`output_format`png（默认）/jpeg/webp；`safety_tolerance`字符串1–6、默认4（本实现省略使用默认）；`sync_mode`默认false（省略，使用queue）；`system_prompt`可选string默认空；`limit_generations`默认true；`enable_web_search`默认false；`thinking_level`minimal/medium（默认）/high，不能发送off。
+
+编辑额外接受`image_urls` string[]，官方未给数量上限；有`video_url`或`pdf_url`时可以不传图。视频单份15MB、PDF单份15MB；PDF走file-upload与官方供应商上传，不提供URL输入框。没有audio_url。无素材走生成；图片、视频或PDF任一种即编辑。
+
+价格与官方折算：https://fal.ai/models/google/nano-banana-2.1 。每百万输入文本/图片Token $1.764，文字/思考输出$8.823，图像输出$35.294；图像输出约1120/1680/3780Token。官方代表性成本（100Token短提示词、medium思考）1K/2K/4K约$0.040/$0.059/$0.134；两张1K参考图增加约$0.004。calculator用该官方代表值及每参考图约$0.002，不作为固定单张账单。搜索、思考没有固定附加费，只改变实际Token。视频/PDF、长提示词、搜索与high思考可能超出代表估价，实际usage为准。
+
+## 事件契约矩阵
+
+| 事件/状态 | 传输形态 | 前置状态 | 字段路径与类型（必需性） | 缺省/空值语义 | 合法下一状态 | 应用输出 | 副作用与终态 | 连接生命周期 |
+|---|---|---|---|---|---|---|---|---|
+| 提交响应 | POST queue端点；GET status_url；完成后GET response_url | 未提交 | request_id或status_url:string（提交至少其一）；status:string（查询必需）；images[].url:string（成功结果必需） | 缺标识且缺有效媒体明确报错；不自动重提 | IN_QUEUE/IN_PROGRESS/COMPLETED | pending任务标识或有效同步结果 | 保存可恢复查询的标识；仅提交一次 | 单次HTTP结束 |
+| IN_QUEUE | 状态查询JSON | 同一任务已提交/待处理 | request_id或status_url:string（提交至少其一）；status:string（查询必需）；images[].url:string（成功结果必需） | 状态完成不等于有效图像；需要额外结果请求。FAILED/ERROR只属共享parser防御分支，官方队列文档未列为状态 | IN_QUEUE/IN_PROGRESS/COMPLETED/COMPLETED后结果错误/HTTP错误 | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| IN_PROGRESS | 状态查询JSON | 同一任务已提交/待处理 | request_id或status_url:string（提交至少其一）；status:string（查询必需）；images[].url:string（成功结果必需） | 状态完成不等于有效图像；需要额外结果请求。FAILED/ERROR只属共享parser防御分支，官方队列文档未列为状态 | IN_QUEUE/IN_PROGRESS/COMPLETED/COMPLETED后结果错误/HTTP错误 | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| COMPLETED | 状态查询JSON与额外结果JSON | 同一任务已提交/待处理 | request_id或status_url:string（提交至少其一）；status:string（查询必需）；images[].url:string（成功结果必需） | 状态完成不等于有效图像；需要额外结果请求。FAILED/ERROR只属共享parser防御分支，官方队列文档未列为状态；空成功终态是负例，不是合法成功 | 终态 | 全部结果URL，不裁剪 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+| COMPLETED后结果错误/HTTP错误 | 失败结果JSON/HTTP错误 | 同一任务已提交/待处理 | 错误字段文案可省略；失败状态/结果错误必须明确 | 可无媒体；错误文案缺省使用供应商失败说明 | 终态 | 统一错误，无媒体 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+
+不变量：提交必须获得有效任务标识或同步有效结果。仅任务标识不能充当有效final；结果数量不擅自裁剪。重复待处理状态合法；乱序、终态后修改、先终态后另发结果的官方保证未说明。Fal COMPLETED需另取结果，不把状态请求自身当图像。可凭原任务标识重新查询，不自动重提扣费请求。取消使用本地AbortSignal释放轮询与监听；除Fal官方队列取消接口外，供应商是否停止云端扣费未说明，本批不改远端取消实现。网络断开及查询超时使用已有统一错误/重试与恢复机制，不写第二套轮询或日志。
+
+## Fixture 与验证
+
+`tests/fixtures/nano-banana-2.1/`按页面JSON示例留存官方字面内容（URL/ID不可联网替换），字段表构造另标，负例独立标synthetic-negative。请求、枚举、数量边界、价格及四渠道全部结果/空终态/错误/取消由精确测试覆盖；断牙验证临时移除APIMart空结果拒绝不变量并确认失败后恢复。
+
+## 选型与能力覆盖
+
+复用现有供应商adapter、共享轮询和上传服务；无新网络库或自研协议。模型差异写catalog，中文/英文与渠道联动写presentation；现有通用模型发现与生成操作覆盖本批，属于已有能力的数据扩充，无需专用Agent工具。
+
+## 原始链接索引
+
+- [请求契约](https://fal.ai/models/google/nano-banana-2.1/llms.txt)：无需登录。
+- [轮询/队列契约](https://fal.ai/docs/documentation/model-apis/inference/queue)：无需登录。
+- 本文内模型页/公告/价格链接：无需登录；真实生成与账单另需用户授权，未验。

package/docs/model-adaptation/Nano-Banana-2.1/Nano-Banana-2.1_Grsai.md

@@ -0,0 +1,35 @@
+# Nano Banana 2.1 — Grsai
+
+采集日期：2026-10-12。BrowserOS neo 公开页面，只读；没有登录、读取凭据或发起生成。
+
+## 请求与计价契约
+
+Base URL `https://grsaiapi.com`，国内`https://grsai.dakka.com.cn`。POST `/v1/api/generate`，Bearer鉴权。model `nano-banana-2.1`由2026-10-07官方公告确认：https://grsai.ai/zh/dashboard/announcements ，公告明确接口不变，只替换model（旧接口枚举尚未列新版，记录该滞后，不拿旧模型能力推断新版）。`prompt`必填；`images`可选string[]，URL/base64，数量未声明；`aspectRatio`默认省略/auto，10种常规比例与Nano2系列4种极端比例；`imageSize`1K/2K/4K。`replyType`json/stream/async，本宿主共享provider固定async，GET `/v1/api/result?id=...`恢复查询。
+
+价格：https://grsai.ai/zh/dashboard/models ：各分辨率1200积分/次，页面套餐参考汇率20000积分/元约¥0.06；沿既有基础充值档10000积分/元估算¥0.12，不将优惠套餐价格当作所有账号实扣。原API文档同步成功例用于parser对照；async提交running与400 failed也按官方折叠响应页补采字面样本；多结果状态链另按字段表构造，不冒充真实生成。
+
+## 事件契约矩阵
+
+| 事件/状态 | 传输形态 | 前置状态 | 字段路径与类型（必需性） | 缺省/空值语义 | 合法下一状态 | 应用输出 | 副作用与终态 | 连接生命周期 |
+|---|---|---|---|---|---|---|---|---|
+| 提交响应 | POST /v1/api/generate；GET /v1/api/result?id=... | 未提交 | id:string（提交必需）；status:string（查询必需）；results[].url:string（成功必需） | 缺标识且缺有效媒体明确报错；不自动重提 | running/succeeded | pending任务标识或有效同步结果 | 保存可恢复查询的标识；仅提交一次 | 单次HTTP结束 |
+| running | 状态查询JSON | 同一任务已提交/待处理 | id:string（提交必需）；status:string（查询必需）；results[].url:string（成功必需） | 未完成可省略results；成功必须有非空媒体URL，空结果明确失败 | running/succeeded/failed/violation | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| succeeded | 状态查询JSON | 同一任务已提交/待处理 | id:string（提交必需）；status:string（查询必需）；results[].url:string（成功必需） | 未完成可省略results；成功必须有非空媒体URL，空结果明确失败；空成功终态是负例，不是合法成功 | 终态 | 全部结果URL，不裁剪 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+| failed | 失败结果JSON/HTTP错误 | 同一任务已提交/待处理 | 错误字段文案可省略；失败状态/结果错误必须明确 | 可无媒体；错误文案缺省使用供应商失败说明 | 终态 | 统一错误，无媒体 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+| violation | 审核违规结果JSON | 同一任务已提交/待处理 | 错误字段文案可省略；失败状态/结果错误必须明确 | 可无媒体；错误文案缺省使用供应商失败说明 | 终态 | 统一错误，无媒体 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+
+不变量：提交必须获得有效任务标识或同步有效结果。仅任务标识不能充当有效final；结果数量不擅自裁剪。重复待处理状态合法；乱序、终态后修改、先终态后另发结果的官方保证未说明。可凭原任务标识重新查询，不自动重提扣费请求。取消使用本地AbortSignal释放轮询与监听；除Fal官方队列取消接口外，供应商是否停止云端扣费未说明，本批不改远端取消实现。网络断开及查询超时使用已有统一错误/重试与恢复机制，不写第二套轮询或日志。
+
+## Fixture 与验证
+
+`tests/fixtures/nano-banana-2.1/`按页面JSON示例留存官方字面内容（URL/ID不可联网替换），字段表构造另标，负例独立标synthetic-negative。请求、枚举、数量边界、价格及四渠道全部结果/空终态/错误/取消由精确测试覆盖；断牙验证临时移除APIMart空结果拒绝不变量并确认失败后恢复。
+
+## 选型与能力覆盖
+
+复用现有供应商adapter、共享轮询和上传服务；无新网络库或自研协议。模型差异写catalog，中文/英文与渠道联动写presentation；现有通用模型发现与生成操作覆盖本批，属于已有能力的数据扩充，无需专用Agent工具。
+
+## 原始链接索引
+
+- [请求契约](https://qmy27nhsd9.apifox.cn/452392911e0)：无需登录。
+- [轮询/队列契约](https://qmy27nhsd9.apifox.cn/452409577e0)：无需登录。
+- 本文内模型页/公告/价格链接：无需登录；真实生成与账单另需用户授权，未验。

package/docs/model-adaptation/Nano-Banana-2.1/Nano-Banana-2.1_KIE.md

@@ -0,0 +1,36 @@
+# Nano Banana 2.1 — KIE
+
+采集日期：2026-10-12。BrowserOS neo 公开页面，只读；没有登录、读取凭据或发起生成。
+
+## 请求与计价契约
+
+Base URL `https://api.kie.ai`；POST `/api/v1/jobs/createTask`，Bearer鉴权；model `nano-banana-2-1`，`input` object。`prompt` 必填string，最多20000字符，超长明确报错，不截断。`image_input` 可选string[]，最多10张，jpeg/png/webp，单张30MB。`aspect_ratio` 默认auto，14种比例同APIMart；`resolution` 默认1K，1K/2K/4K；`output_format` 默认jpg，jpg/png。没有n、搜索、思考、遮罩字段，营销介绍的mask能力不能凭介绍新增请求字段。`callBackUrl` 可选但宿主不使用，复用轮询。
+
+价格：https://kie.ai/nano-banana-2-1 ：1K/2K/4K 分别4/6/9 credits，即 $0.020/$0.030/$0.045 每张。GET `/api/v1/jobs/recordInfo?taskId=...`，HTTP200仍须检查code；成功`data.resultJson`为JSON字符串，媒体位于`resultUrls`数组。结果保留14天，宿主即时下载。
+
+## 事件契约矩阵
+
+| 事件/状态 | 传输形态 | 前置状态 | 字段路径与类型（必需性） | 缺省/空值语义 | 合法下一状态 | 应用输出 | 副作用与终态 | 连接生命周期 |
+|---|---|---|---|---|---|---|---|---|
+| 提交响应 | POST /api/v1/jobs/createTask；GET /api/v1/jobs/recordInfo?taskId=... | 未提交 | data.taskId:string（提交必需）；data.state:string（查询必需）；data.resultJson:string（成功必需，内含resultUrls:string[]） | 缺标识且缺有效媒体明确报错；不自动重提 | waiting/queuing/generating/success | pending任务标识或有效同步结果 | 保存可恢复查询的标识；仅提交一次 | 单次HTTP结束 |
+| waiting | 状态查询JSON | 同一任务已提交/待处理 | data.taskId:string（提交必需）；data.state:string（查询必需）；data.resultJson:string（成功必需，内含resultUrls:string[]） | 失败时resultJson可为null或空串；成功时必须解析出非空结果 | waiting/queuing/generating/success/fail | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| queuing | 状态查询JSON | 同一任务已提交/待处理 | data.taskId:string（提交必需）；data.state:string（查询必需）；data.resultJson:string（成功必需，内含resultUrls:string[]） | 失败时resultJson可为null或空串；成功时必须解析出非空结果 | waiting/queuing/generating/success/fail | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| generating | 状态查询JSON | 同一任务已提交/待处理 | data.taskId:string（提交必需）；data.state:string（查询必需）；data.resultJson:string（成功必需，内含resultUrls:string[]） | 失败时resultJson可为null或空串；成功时必须解析出非空结果 | waiting/queuing/generating/success/fail | pending，无媒体输出 | 继续同一任务查询，非终态 | 每次HTTP结束，间隔后重查 |
+| success | 状态查询JSON | 同一任务已提交/待处理 | data.taskId:string（提交必需）；data.state:string（查询必需）；data.resultJson:string（成功必需，内含resultUrls:string[]） | 失败时resultJson可为null或空串；成功时必须解析出非空结果；空成功终态是负例，不是合法成功 | 终态 | 全部结果URL，不裁剪 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+| fail | 失败结果JSON/HTTP错误 | 同一任务已提交/待处理 | 错误字段文案可省略；失败状态/结果错误必须明确 | 可无媒体；错误文案缺省使用供应商失败说明 | 终态 | 统一错误，无媒体 | 停止轮询，释放计时器/abort监听 | HTTP结束 |
+
+不变量：提交必须获得有效任务标识或同步有效结果。仅任务标识不能充当有效final；结果数量不擅自裁剪。重复待处理状态合法；乱序、终态后修改、先终态后另发结果的官方保证未说明。可凭原任务标识重新查询，不自动重提扣费请求。取消使用本地AbortSignal释放轮询与监听；除Fal官方队列取消接口外，供应商是否停止云端扣费未说明，本批不改远端取消实现。网络断开及查询超时使用已有统一错误/重试与恢复机制，不写第二套轮询或日志。
+
+## Fixture 与验证
+
+`tests/fixtures/nano-banana-2.1/`按页面JSON示例留存官方字面内容（URL/ID不可联网替换），字段表构造另标，负例独立标synthetic-negative。请求、枚举、数量边界、价格及四渠道全部结果/空终态/错误/取消由精确测试覆盖；断牙验证临时移除APIMart空结果拒绝不变量并确认失败后恢复。
+
+## 选型与能力覆盖
+
+复用现有供应商adapter、共享轮询和上传服务；无新网络库或自研协议。模型差异写catalog，中文/英文与渠道联动写presentation；现有通用模型发现与生成操作覆盖本批，属于已有能力的数据扩充，无需专用Agent工具。
+
+## 原始链接索引
+
+- [请求契约](https://docs.kie.ai/market/google/nanobanana-2-1.md)：无需登录。
+- [轮询/队列契约](https://docs.kie.ai/market/common/get-task-detail.md)：无需登录。
+- 本文内模型页/公告/价格链接：无需登录；真实生成与账单另需用户授权，未验。