@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206/Grsai.md

@@ -0,0 +1,217 @@
+# Grsai · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-26 |
+| 供应商类型 | 聚合中转（转发 Google Nano Banana 系列、OpenAI GPT Image 系列等第三方模型，非模型原厂） |
+| 项目内 providerId | `grsai` |
+| 控制台域名 | `grsai.ai` 与 `grsai.com` 两个域名，页面结构、数据、API 域名完全一致（互为镜像，可视为同一站点） |
+| API 域名 | 全球节点 `grsaiapi.com`；国内直连节点 `grsai.dakka.com.cn`，已接入连通性探测 + 自动切换 |
+| 鉴权 | `Authorization: Bearer <API Key>` |
+| 任务模型 | 提交接口按 `replyType` 三选一：`json`（同步返回结果）/ `stream`（SSE 流）/ `async`（返回 `task_id`，另起轮询）。本项目在发送边界统一强制 `async`，走轮询模式 |
+| 文档可见性 | 公开，无需登录（Apifox 文档站与 dashboard「模型列表」页均可匿名访问） |
+| 价格可见性 | 公开，无需登录（dashboard「模型列表」页直接给出每个模型的价格区间） |
+| 项目当前状态 | **已接入 SDK runtime**（[src/providers/grsai.ts](../../../src/providers/grsai.ts)），已适配 GPT-Image-2 / Nano Banana 2 / Nano Banana 2 Lite / Nano Banana Pro 四个模型的全部渠道，见第 9 节「项目对照」 |
+
+> Grsai 的核心特点是**同一个模型家族在其内部又拆成多个「渠道」**（官方叫法，如 `-cl`、`-vip`、`-vt`、`-lite` 后缀），渠道之间价格差异可达 10 倍以上，越便宜的渠道官方公告历史上出现过越多次限流 / 维护 / 降级事件（见第 8 节）。接入时建议把「渠道」做成模型内的顶层可选参数，而不是把每个渠道拆成独立模型卡片——具体取舍见各模型文档「适配要点」。**本项目只适配 Nano Banana 第 2 代与 Nano Banana Pro 两个家族，初代 Nano Banana 相关的平台模型名已被明确排除，见第 7 节。**
+
+## 1. 端点
+
+### 1.1 Base URL 与节点
+
+官方文档在每个接口页面都重复给出两条节点：
+
+| 节点 | 地址 | 定位 |
+|---|---|---|
+| 全球节点 | `https://grsaiapi.com` | 海外访问 |
+| 国内节点 | `https://grsai.dakka.com.cn` | 国内直连 |
+
+与 APIMart 的「主线路 + 大陆备用域名」不同，Grsai 官方文档没有说明这两条线路是否共享同一套账号 / 任务数据、是否只在故障时切换——**两条线路的关系未实测确认**，接入前需要用同一个 API Key 分别探测两条线路的可用性与数据一致性，再决定是走 APIMart 式「连通性探测 + 记忆」还是简单固定一条。
+
+### 1.2 API 端点一览
+
+**新版统一接口（Apifox 文档站给出，官方在公告中标注为「新文档」，推荐新对接使用）**
+
+| 用途 | 方法与路径 | 说明 |
+|---|---|---|
+| 生成 | `POST /v1/api/generate` | 图片（文档目录标注含视频，但当前 dashboard 定价列表未见任何视频模型，见第 8 节）统一生成入口，`model` 字段决定具体模型与渠道 |
+| 查询结果 | `GET /v1/api/result?id=<task_id>` | 统一异步结果查询，返回结构与生成接口一致 |
+
+**旧版分模型接口（官方声明「永久有效」，字段集合与新接口不完全一致，见第 3.5 节差异）**
+
+| 用途 | 方法与路径 | 说明 |
+|---|---|---|
+| Nano Banana 系列生成 | `POST /v1/draw/nano-banana` | 早于统一接口的专用入口 |
+| GPT Image 系列生成 | `POST /v1/draw/completions` | 多一个新接口没有的 `quality` 参数，见第 3.5 节 |
+| Veo3 视频生成 | `POST /v1/video/veo` | 仅在 dashboard 文档导航「Veo API」下出现，未见于「模型大全」定价列表，可用性 / 计费未知，见第 8 节 |
+| 旧接口统一结果查询 | `POST /v1/draw/result` | 与 `/v1/api/result` 平行存在，两套接口不要混用 |
+
+**OpenAI 兼容接口（面向能直接换 `base_url` 接入的客户端，文档未详细展开字段，仅作为备选记录）**
+
+| 用途 | 方法与路径 | 说明 |
+|---|---|---|
+| 对话 / 多模态 | `POST /v1/chat/completions` | 文档写「支持所有模型」；示例模型为纯文本 LLM（`gemini-3.1-pro` 等），不在本项目图片/视频/音频生成范围内 |
+| 图片生成 | `POST /v1/images/generations` | 文档写「支持所有图片生成模型」，`model` 传 `gpt-image-2` 等即可，参数与新版统一接口的 `aspectRatio`/`imageSize` 近似但字段名不同（`image`/`size`/`response_format`） |
+
+**账户与状态接口（旧版，路径不带 `base_url` 前缀，直接挂在控制台域名下）**
+
+| 用途 | 方法与路径 | 说明 |
+|---|---|---|
+| 查询 API Key 积分余额 | `POST /client/openapi/getAPIKeyCredits` | 返回 `data.credits`；文档正文未列出请求体字段，**鉴权方式未确认**（是否走 `Authorization: Bearer` 还是账户登录 `token`），接入前需登录控制台用「生成代码」示例核实 |
+| 查询账户积分余额 | `POST /client/openapi/getCredits` | 同上，字段与鉴权方式待确认 |
+| 查询模型状态 | `GET /client/common/getModelStatus?model=<modelName>` | 返回 `data.status`（布尔）与 `data.error`（异常时的说明文本） |
+
+## 2. 鉴权
+
+```
+Authorization: Bearer <API Key>
+```
+
+生成与查询接口的 `Authorization` 头在 OpenAPI 定义里标了 `required: false`，但示例与说明都指向「不带 Key 用不了」，按必填处理。API Key 在 https://grsai.ai/zh/dashboard/api-keys 创建（**需登录**）。
+
+## 3. 提交、轮询与结果（新版统一接口）
+
+### 3.1 提交 `POST /v1/api/generate`
+
+请求体（图片，具体 `model` 枚举见各模型文档）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `model` | string | 必填 | 模型名（含渠道后缀，如 `nano-banana-2-cl`） |
+| `prompt` | string | 必填 | 提示词 |
+| `images` | array\<string\> | 可选 | 参考图，**支持 base64 与 URL 混填，没有独立上传接口**——图片直接以 base64 或已公开 URL 塞进请求体即可 |
+| `aspectRatio` | string | 可选 | 比例，取值集合因模型而异，见各模型文档 |
+| `imageSize` | string | 可选 | `1K` / `2K` / `4K`，是否可用取决于渠道，见各模型文档 |
+| `replyType` | string | 可选 | `json`（同步等待结果）/ `stream`（SSE 流）/ `async`（立即返回 `task_id`，走轮询）。本项目按 Electron 轮询模式，接入时固定传 `async` |
+
+### 3.2 响应（`json` / `async` 首包共用结构）
+
+```json
+{
+  "id": "14-5f3cf761-a4bb-486a-8016-77f490998f80",
+  "status": "succeeded",
+  "progress": 100,
+  "results": [{ "url": "https://file1.aitohumanize.com/file/....png" }],
+  "error": null
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `id` | 任务 id，`async` 模式下用它调 `/v1/api/result` |
+| `status` | `running`（进行中）/ `violation`（违规，独立终态）/ `succeeded`（成功）/ `failed`（失败） |
+| `progress` | 0–100 |
+| `results[].url` | 图片 / 视频链接 |
+| `error` | 仅失败 / 违规时出现的报错信息 |
+
+`violation` 是与 `failed` 平级的独立终态（内容审核不通过），轮询逻辑要把它当终态处理，不能只判断 `succeeded`/`failed` 两种。公告原文提到「当生成失败时，会返还积分」，`violation` 是否同样返还未在文档中写明。
+
+### 3.3 轮询 `GET /v1/api/result?id=<id>`
+
+参数只有 `id`（query）与 `Authorization`（header），响应结构与 3.2 完全一致，`400` 时同样返回 `{id, status, error}`。
+
+### 3.4 结果链接有效期
+
+新版接口文档未写有效期。旧版 GPT Image 专用接口（`/v1/draw/completions`）文档明确写「结果图片的 URL（有效期为 2 小时）」。两套接口是否共用同一套文件存储、有效期是否一致未验证——**建议按 2 小时保守处理，接入前用真实任务实测确认**。
+
+### 3.5 新旧接口字段差异
+
+| 差异点 | 新版 `/v1/api/generate` | 旧版 `/v1/draw/completions`（仅 GPT Image） |
+|---|---|---|
+| `quality` 参数 | **没有** | 有：`auto` / `low` / `medium` / `high` |
+| `webHook` 回调 | 文档未提及 | 有：不轮询时可用 `webHook` 收异步回调，传 `"-1"` 则立即返回 `id` 转轮询 |
+| `shutProgress` | 无 | 有：关闭进度中间态，只回最终结果 |
+| 结果字段 `url` | 只在 `results[]` 数组里 | 额外在顶层保留 `url`（等价 `results[0].url`，标注「旧参数，不会废弃」） |
+
+桌面端没有公网回调地址，`webHook` 用不上；`quality` 的缺失是新接口一个实打实的能力缺口，若后续要接 GPT Image 的画质档位，需要用旧接口或等新接口补齐，**接入前需二次确认**。
+
+## 4. 文件上传
+
+**没有独立的图片上传接口。** 生成请求的 `images`（新接口）/ `urls`（旧接口）参数直接接受 base64 编码字符串或已公开的 URL，由 Grsai 服务端自己处理，不需要供应商级别的预上传步骤。这点与 APIMart / KIE 都不同，接入时公共媒体预处理层对 Grsai 可以走「本地图转 base64 直接塞进请求体」，不必调用上传 API。
+
+## 5. 计价与余额
+
+### 5.1 积分与充值折扣
+
+Grsai 用积分计费，dashboard「充值」页给出六档套餐（¥10 起，最高¥999），充值金额越大赠送比例越高：
+
+| 充值金额 | 到账积分（含赠送） |
+|---|---|
+| ¥10 | 100,000（送 25%） |
+| ¥20 | 250,000（送 50%） |
+| ¥49 | 750,000（送 60%） |
+| ¥99 | 1,600,000（送 80%） |
+| ¥499 | 9,000,000（送 100%） |
+| ¥999 | 20,000,000 |
+
+据此换算，积分单价区间约为 **¥0.0001/积分（无优惠，小额充值）到 ¥0.00005/积分（¥999 档，约 5 折）**。dashboard「模型列表」页给每个模型标注的价格区间（如 gpt-image-2 的「¥0.03~¥0.06/次」）就是「积分消耗 × 积分单价区间」算出来的，是最权威的价格来源，本轮各模型文档的价格表都来自这里（2026-08-26 实测，未登录可见）。
+
+### 5.2 余额查询
+
+`POST /client/openapi/getAPIKeyCredits` 返回 `{ code, msg, data: { credits } }`；请求体字段与鉴权方式文档正文未写全，**接入前需要登录控制台核实**（见第 1.2 节表格备注）。
+
+## 6. 错误与状态
+
+- 任务状态枚举：`running` / `violation` / `succeeded` / `failed`
+- 错误信息在 `error` 字段（string），没有结构化的 `code` / `type` 分类
+- 部分接口在失败时返回 HTTP `400`，body 结构与 200 成功响应类似（`{id, status, error}`）
+- 文档未提供限流（429）相关说明
+
+## 7. 明确排除的模型（不适配，容易与在售渠道混淆）
+
+| 平台模型名 | 状态 | 排除原因 |
+|---|---|---|
+| `nano-banana` | 已下架（2026-07-01 公告：谷歌官方下架其底层模型 `gemini-2.5-flash-image`，Grsai 随即下架该模型名） | 属于最早期的「香蕉 1」世代，官方已停售，本来就没有可适配的意义 |
+| `nano-banana-fast` | 当前 dashboard「模型列表」页仍在售，**本项目不适配** | 同属「香蕉 1」世代衍生出的命名，2026-07-01 公告显示它在 `nano-banana` 下架后「切换底层模型」，此后实际跑在新的 Gemini 3.1 Lite 底层上。它的积分消耗（440/次）、价格区间（¥0.022~¥0.044/次）与 `nano-banana-2-lite` **完全相同**，两个名字长得像、报价一样，极易在选型或写 schema 时混进来 |
+
+本项目适配范围只有 **Nano Banana 2**（[Nano-Banana-2_Grsai.md](../Nano-Banana-2/Nano-Banana-2_Grsai.md)）、**Nano Banana 2 Lite**（[Nano-Banana-2-Lite_Grsai.md](../Nano-Banana-2-Lite/Nano-Banana-2-Lite_Grsai.md)）、**Nano Banana Pro**（[Nano-Banana-Pro_Grsai.md](../Nano-Banana-Pro/Nano-Banana-Pro_Grsai.md)）三个家族，`nano-banana` 与 `nano-banana-fast` 不在其中，不要在渠道枚举、价格对照或 schema 里出现这两个名字。以后如果 Grsai dashboard 上出现新的「香蕉 1」世代衍生渠道（例如再切换底层模型后改个新名字），按同样理由排除，不需要重新讨论。
+
+## 8. 已知不确定项
+
+以下几项在真机核实前仍是假设，不代表官方已确认；代码里已按标注的方式处理，未来发现假设不成立时优先改文档、再改代码。
+
+1. **国内节点与全球节点的关系**：是同账号双活线路，还是各自独立环境，未实测。**处理方式**：已实现连通性探测 + 进程内记忆（[endpoints/grsai.ts](../../../src/providers/endpoints/grsai.ts)，与 APIMart 同款策略），只在能证明尚未建立连接时切换，不重放已建立连接后的失败；底层数据是否互通仍未验证。
+2. **新版接口结果 URL 有效期**：旧接口写 2 小时，新接口未写，两者是否一致未知。**处理方式**：项目在任务完成时立即把结果下载转存到本地（`saveMediaFromUrl`），不依赖长期持有远程链接，实际风险已被规避。
+3. **`replyType: async` 首包与轮询响应字段是否完全一致**：示例数据看起来一致，但没有逐字段的官方说明。**处理方式**：`execute()` 对提交响应做了防御性判断——如果 `status` 已经是 `succeeded` 且带 `results`，直接按完成态返回，不强制走一次多余的轮询。
+4. **`getAPIKeyCredits` / `getCredits` 的鉴权方式**：走生成用的 `Authorization: Bearer`，还是账户登录 `token` 字段，文档正文没写清楚。**处理方式**：本轮**没有**接入余额探测（`provider-connection.ts` 的 `PROVIDER_PROBES` 里没有 `grsai` 条目），保持"已保存未校验"，避免拿不确定契约误判用户 Key 状态；接口方法也对不上（余额是 POST，探测框架统一用 GET）。
+5. **Veo3（`veo3.1-fast`）是否可用**：只出现在「在线体验/文档」导航的「Veo API」旧版文档里，**没有出现在 dashboard「模型列表」的定价清单中**，说明它可能是未正式计价 / 未上线 / 已下线的状态，不作为可接入模型，仅存档以免下次调研重复发现。
+6. **`violation`（违规）终态是否返还积分**：公告只写了 `failed` 会返还，`violation` 未提及，不影响本项目实现（两种状态在轮询里都按终止性失败处理）。
+
+## 9. 项目对照
+
+| 层级 | 位置 |
+|---|---|
+| 生成执行 / 轮询 | [src/providers/grsai.ts](../../../src/providers/grsai.ts) |
+| 双线路探测 | [src/providers/endpoints/grsai.ts](../../../src/providers/endpoints/grsai.ts) |
+| Provider 分发注册 | [src/providers/index.ts](../../../src/providers/index.ts) |
+| Key 存储 | [electron/main/services/keystore.ts](../../../../../electron/main/services/keystore.ts) → `KNOWN_AI_PROVIDER_IDS` |
+| 启动预热 | [electron/main/index.ts](../../../../../electron/main/index.ts)（仅在已配置 Key 时触发，不阻塞启动） |
+| 前端 Key 元信息 | [src/core/config/providers.ts](../../../../../src/core/config/providers.ts) |
+| 本地图片上传策略 | [src/upload/preprocess.ts](../../../src/upload/preprocess.ts)（内联 base64，无独立上传接口） |
+| 模型定义 | `packages/ai-sdk/src/catalog/grsai/{gpt-image-2,nano-banana-2,nano-banana-2-lite,nano-banana-pro}.model.ts` |
+| 国际化 | `src/i18n/locales/{zh-CN,en-US}/models-grsai.json`、`settings.json` 的 `apiKeys.providers.grsai` |
+| 测试 | `packages/ai-sdk/tests/providers/endpoints/grsai.test.ts`、`packages/ai-sdk/tests/providers/grsai.test.ts`、`packages/ai-sdk/tests/catalog/grsai.test.ts` |
+
+已知欠账（记录在案，不阻塞当前交付）：
+
+- 余额查询未接入（见第 8 节第 4 项），设置页无法显示 Grsai 账户余额，只能显示"已保存"状态。
+- 未做真实 API Key 下的端到端联调（本地没有可用的 Grsai Key），当前实现完全基于文档与单元测试验证，接入前建议先用真实任务跑一轮 `npm run assistant:cli` 或手动生成核实请求/响应字段。
+
+## 10. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Apifox 文档总索引（llms.txt） | https://qmy27nhsd9.apifox.cn/llms.txt | 否 |
+| nano-banana 接口（新版统一生成，含全部图片模型枚举） | https://qmy27nhsd9.apifox.cn/452392911e0 | 否 |
+| gpt-image-2 接口（新版统一生成） | https://qmy27nhsd9.apifox.cn/452409160e0 | 否 |
+| 异步生成结果查询接口 | https://qmy27nhsd9.apifox.cn/452409577e0 | 否 |
+| OpenAI 兼容 `/v1/chat/completions` | https://qmy27nhsd9.apifox.cn/452418916e0 | 否 |
+| OpenAI 兼容 `/v1/images/generations` | https://qmy27nhsd9.apifox.cn/452417029e0 | 否 |
+| dashboard 公告（渠道调价 / 模型上下架历史） | https://grsai.com/zh/dashboard/announcements | 否 |
+| dashboard 模型大全（当前权威价格与可用性） | https://grsai.com/zh/dashboard/models（同 `grsai.ai/zh/dashboard/models`） | 否 |
+| dashboard 充值套餐（积分折扣档位） | https://grsai.com/zh/dashboard/billing | 否 |
+| Nano Banana API 旧版文档（`/v1/draw/nano-banana`） | https://grsai.ai/zh/dashboard/documents/nano-banana | 否 |
+| GPT Image API 旧版文档（`/v1/draw/completions`，含 `quality` 参数） | https://grsai.ai/zh/dashboard/documents/gpt-image | 否 |
+| Veo API 旧版文档（`veo3.1-fast`，未出现在定价列表） | https://grsai.ai/zh/dashboard/documents/veo | 否 |
+| 其他接口（账户 / API Key 管理，含余额与模型状态查询） | https://grsai.ai/zh/dashboard/documents/other | 否 |
+| API Key 管理 | https://grsai.ai/zh/dashboard/api-keys | **是** |

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206/KIE.md

@@ -0,0 +1,131 @@
+# KIE · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 供应商类型 | 聚合中转（非模型原厂） |
+| 项目内 `providerId` | `kie` |
+| 生成 Base URL | `https://api.kie.ai` |
+| 上传 Base URL | `https://kieai.redpandaai.co` |
+| 鉴权 | `Authorization: Bearer <API Key>` |
+| 任务模式 | Market 模型统一异步任务 |
+| 文档/价格可见性 | 公开，无需登录；API Key 和账单需登录 |
+
+## 1. 基础端点
+
+| 用途 | 方法与路径 | 说明 |
+|---|---|---|
+| 创建 Market 任务 | `POST /api/v1/jobs/createTask` | body 为 `model` + `input`，可选 `callBackUrl` |
+| 查询 Market 任务 | `GET /api/v1/jobs/recordInfo?taskId=...` | 所有 Market 模型的统一查询入口 |
+| 查询剩余积分 | `GET /api/v1/chat/credit` | 返回 `data` 整数积分 |
+| 换取生成文件下载链 | `POST /api/v1/common/download-url` | 仅接受 KIE 生成文件 URL |
+| 文件流上传 | `POST https://kieai.redpandaai.co/api/file-stream-upload` | multipart，适合本地文件 |
+| URL 转存 | `POST https://kieai.redpandaai.co/api/file-url-upload` | JSON，从远程 URL 下载并转存 |
+| Base64 上传 | `POST https://kieai.redpandaai.co/api/file-base64-upload` | JSON，适合小文件 |
+
+KIE 还有 Suno、4o Image、Runway 等历史/专用 API。新的 Market 模型优先使用统一 `jobs` 契约；只有官方文档明确不走 Market 时才新增专用分支。
+
+## 2. 提交和查询
+
+### 2.1 创建任务
+
+```json
+{
+  "model": "<market-model-id>",
+  "callBackUrl": "https://your-server.example/callback",
+  "input": { "prompt": "..." }
+}
+```
+
+成功时返回 `data.taskId`。`callBackUrl` 为可选项；桌面端没有稳定公网回调地址，Henji-AI 使用轮询。
+
+### 2.2 轮询
+
+`GET https://api.kie.ai/api/v1/jobs/recordInfo?taskId=<taskId>`
+
+| 字段 | 含义 |
+|---|---|
+| `data.state` | `waiting` / `queuing` / `generating` / `success` / `fail` |
+| `data.resultJson` | 成功后的 JSON 字符串，必须再次解析 |
+| `data.failCode` / `data.failMsg` | 失败码和可见原因 |
+| `data.progress` | 部分模型返回进度 |
+| `data.creditsConsumed` | 该任务实际消耗的积分 |
+
+最常见的成功结果：
+
+```json
+{
+  "data": {
+    "state": "success",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "creditsConsumed": 50
+  }
+}
+```
+
+`resultJson` 不只有 `resultUrls`；个别模型返回 `images`、`videos`、`resultObject`、`firstFrameUrl` 或 `lastFrameUrl`。公共运行时已覆盖这些媒体 URL 形态，模型文档仍必须记录例外结构。
+
+## 3. 文件上传
+
+### 3.1 本地文件
+
+```bash
+curl -X POST https://kieai.redpandaai.co/api/file-stream-upload \
+  -H "Authorization: Bearer $KIE_KEY" \
+  -F "uploadPath=henji-uploads" \
+  -F "fileName=reference.png" \
+  -F "file=@/path/reference.png"
+```
+
+返回值历史上出现过两种字段，适配时兼容：
+
+- `data.fileUrl`
+- `data.downloadUrl`
+
+项目上传时不主动指定远端 `fileName`，由 KIE 生成唯一文件名，避免同名覆盖后的 CDN 缓存短暂返回旧内容。
+
+### 3.2 有效期冲突
+
+KIE 官方快速开始和页面提醒写“24 小时后删除”，文件流 OpenAPI 的描述/示例又出现“3 天”。在官方消除冲突前，项目以 **24 小时** 作为保守上限，以实际返回 `expiresAt` 为准。
+
+## 4. 获取和保存结果
+
+- `resultJson.resultUrls[]` 通常可直接下载。
+- 如果生成 URL 是 KIE 内部临时地址，可调用 `POST /api/v1/common/download-url` 换取下载链。
+- 该换链接口不接受外部 URL，传入非 KIE 文件会返回 `422`。
+- 媒体结果必须及时转存，不把供应商临时 URL 当永久资产。
+
+## 5. 计价和余额
+
+| 来源 | 用途 |
+|---|---|
+| `https://kie.ai/pricing` | 当前公开价格；按模型、模式、分辨率、时长等分行 |
+| 模型 API 文档 | 请求 schema 和模型级计费描述 |
+| `data.creditsConsumed` | 已完成任务的实际积分消耗，对账优先级最高 |
+| `GET /api/v1/chat/credit` | 当前剩余积分，返回 `{ code, msg, data }` |
+
+定价页的 `/client/v1/model-pricing/*` 是站点内部数据源，并非公开开发者稳定契约，项目不直接依赖。
+
+## 6. 项目当前实现
+
+| 能力 | 状态 | 位置 |
+|---|---|---|
+| Market 任务提交 | 已接入 | `providers/kie.ts` |
+| 统一轮询 | 已接入 | `providers/kie.ts` |
+| `resultJson` 解析 | 已接入 | `providers/kie.ts` |
+| 文件流上传 | 已接入 | `upload-providers.ts` |
+| 余额/连接检测 | 已接入 | `provider-connection.ts` |
+| 换取下载链 | 未作为通用必经步骤 | 只在结果 URL 确实不可直下时再接入 |
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| 文档总索引 | https://docs.kie.ai/llms.txt | 否 |
+| Market 统一任务查询 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 文件上传快速开始 | https://docs.kie.ai/cn/file-upload-api/quickstart | 否 |
+| 文件流上传 | https://docs.kie.ai/cn/file-upload-api/upload-file-stream | 否 |
+| 获取剩余积分 | https://docs.kie.ai/cn/common-api/get-account-credits | 否 |
+| 换取生成文件下载链 | https://docs.kie.ai/cn/common-api/download-url | 否 |
+| 定价页 | https://kie.ai/pricing | 否 |
+| API Key | https://kie.ai/api-key | 是 |

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//345/200/231/351/200/211/344/276/233/345/272/224/345/225/206/350/260/203/347/240/224-/345/233/276/347/211/207/345/267/245/345/205/267.md

@@ -0,0 +1,151 @@
+# 图片工具候选供应商调研
+
+> 状态：调研完成，尚未适配
+> 核验日期：2026-08-29
+> 范围：高清放大、重打光、图片视角变化、扩图、照片修复、背景移除，以及图片/视频/音频生成、价格优惠和中国内地访问条件。
+
+## 结论
+
+推荐顺序：
+
+1. **Segmind（P0）**：目标图片工具覆盖最完整，异步协议统一，适合先做完整 provider。
+2. **WaveSpeedAI（P0）**：模型池最大、公开折扣最明显，多角度/放大/重打光/修复/抠图均有明确独立入口。
+3. **PiAPI（P1）**：放大、抠图、扩图价格低，提供简体中文站和 USDT 优惠，适合作为低价补充。
+4. **Replicate（P2）**：长尾能力强，但社区模型版本、许可证、下架风险和结果落盘时限需要额外治理。
+5. **Novita AI（P3）**：多模态齐全，但当前没有足够独立图片工具覆盖，本轮暂缓。
+
+公开资料不足以把任何一家写成“已确认中国内地友好”。正式选型前必须从中国移动、联通、电信网络分别测试 API 域名和结果媒体域名；DNS/TLS/未鉴权请求可先做零费用探测，付费生成另行授权。
+
+## 能力矩阵
+
+| 供应商 | 高清放大 | 重打光 | 图片视角 | 背景移除 | 图片扩图 | 照片修复 | 图片生成 | 视频生成 | 音频生成 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| Segmind | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| WaveSpeedAI | ✅ | ✅ | ✅ | ✅ | 待确认独立图片端点 | ✅ | ✅ | ✅ | ✅ |
+| PiAPI | ✅ | 未发现 | 未发现 | ✅ | ✅ | 未发现 | ✅ | ✅ | ✅ |
+| Replicate | ✅ | 社区模型 | 社区模型 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Novita AI | 生成参数内置 | 未发现 | 未发现 | 未发现 | 未发现 | 人脸修复开关 | ✅ | ✅ | ✅ |
+
+## 1. Segmind（P0）
+
+### 已核验能力
+
+- 多角度：[Qwen Image Edit Plus Multiple Angles](https://www.segmind.com/models/qwen-image-edit-plus-multiple-angle)，支持镜头移动、旋转和远近控制。
+- 重打光：[Segmind Relighting V2](https://www.segmind.com/models/segmind-relighting-v2)，支持方向、类型、颜色和强度控制。
+- 高清放大：[Bria Increase Resolution](https://www.segmind.com/models/bria-increase-resolution)，支持 2×/4× 与 Alpha。
+- 扩图：[Flux Fill Pro](https://www.segmind.com/models/flux-fill-pro)。
+- 背景移除：[Bria RMBG 2.0](https://www.segmind.com/models/bria-remove-background)。
+- 照片修复：[SUPIR](https://www.segmind.com/models/supir)。
+- 另有独立的[视频模型目录](https://www.segmind.com/models/all/best-video-models)和[音频模型目录](https://www.segmind.com/models/all/text-to-speech-models)。
+
+### 公共协议
+
+- Base URL：`https://api.segmind.com`
+- 鉴权：`x-api-key`，见[官方鉴权文档](https://docs.segmind.com/docs/get-started/authentication)。
+- 同步：`POST /v1/{model-slug}`。
+- 异步：`POST /v2/{model-slug}`；提交返回 `request_id`、`status_url`、`response_url`。
+- 查询：`GET /v2/requests/{id}/status`、`GET /v2/requests/{id}`。
+- 终态：`COMPLETED` / `FAILED`。多角度请求形状见其[官方 API 页面](https://www.segmind.com/models/qwen-image-edit-plus-multiple-angle/api)。
+
+### 价格、优惠与内地访问
+
+- [官方价格页](https://www.segmind.com/pricing)明确提供 volume discounts，并写有“The more you buy, the more you save”。
+- 公开计划存在月付积分溢价和企业年付折扣；最终适配必须按模型页实时价格逐项记录。
+- 未发现中国内地节点、备案域名、本地支付或网络 SLA；示例媒体依赖云存储域名，访问结论为**未知、待实测**。
+
+### 建议首批
+
+多角度、Relighting V2、Bria Increase Resolution、Flux Fill Pro、Bria RMBG 2.0、SUPIR。v2 公共轮询层只实现一次，各模型保持独立 schema。
+
+## 2. WaveSpeedAI（P0）
+
+### 已核验能力
+
+- 多角度：[Qwen Image Edit Multiple Angles](https://wavespeed.ai/models/wavespeed-ai/qwen-image/edit-multiple-angles)。
+- 重打光：[Bria Fibo Relight](https://wavespeed.ai/models/bria/fibo/relight)。
+- 高清放大：[Clarity Pro Upscaler](https://wavespeed.ai/models/clarity-ai/pro-upscaler)、[WaveSpeed Image Upscaler](https://wavespeed.ai/models/wavespeed-ai/image-upscaler)。
+- 背景移除：[WaveSpeed Background Remover](https://wavespeed.ai/models/wavespeed-ai/image-background-remover)。
+- 照片修复：[Bria Fibo Restore](https://wavespeed.ai/models/bria/fibo/restore)。
+- 官方目录已发现视频扩图，但尚未核到明确的独立**图片** outpaint endpoint，因此不得用泛化编辑能力替代确认。
+
+### 公共协议
+
+- Base URL：`https://api.wavespeed.ai/api/v3`
+- 鉴权：`Authorization: Bearer ...`，见[鉴权文档](https://wavespeed.ai/docs/api-authentication)。
+- 提交：`POST /api/v3/{model_id}`，见[提交文档](https://wavespeed.ai/docs/submit-task)。
+- 查询：`GET /api/v3/predictions/{task-id}/result`，见[结果查询](https://wavespeed.ai/docs/get-result)。
+- 终态：`completed`；失败类终态包括 `failed`、`cancelled`、`timeout`、`deleted`。
+- 支持 webhook，部分模型支持同步模式。
+
+### 价格、优惠与内地访问
+
+- 官方模型目录直接展示 5%–50% OFF，且[价格页](https://wavespeed.ai/pricing)提供企业 volume discounts。
+- 官网提供中文版本提示，但未发现中国节点、内地 API SLA 或支付宝/微信支付证据；访问结论仍为**未知、待实测**。
+
+### 建议首批
+
+多角度、Fibo Relight、Image Upscaler、Background Remover、Fibo Restore；图片 Outpaint 等官方确认独立端点后再加入。
+
+## 3. PiAPI（P1）
+
+### 已核验能力
+
+- 高清放大：[Super Resolution API](https://piapi.ai/docs/image-editing-api/super-resolution-api)，支持 2/4/8×与人脸增强。
+- 背景移除：[Remove Background API](https://piapi.ai/docs/image-editing-api/remove-background-api)，支持 RMBG-1.4、RMBG-2.0、BEN2。
+- 扩图：[Flux Outpaint](https://piapi.ai/docs/flux-redux-fill-variation-inpaint-outpaint)。
+- 当前官方文档索引未发现独立重打光、照片修复或图片多角度；[WanX Camera Control](https://piapi.ai/docs/wanx-api/camera-control.md)是视频镜头控制，不能计入图片视角能力。
+
+### 公共协议
+
+- Base URL：`https://api.piapi.ai`
+- 鉴权：`x-api-key`
+- 统一提交：`POST /api/v1/task`
+- 统一查询：`GET /api/v1/task/{task_id}`
+- 请求主体统一为 `model`、`task_type`、`input`，支持 webhook。见[Quickstart](https://piapi.ai/docs/quickstart)和[统一 API schema](https://piapi.ai/docs/unified-api-schema)。
+
+### 价格、优惠与内地访问
+
+- 放大和背景移除页面公开价均很低；落地前仍需按实际输出 MP 与任务返回账单校对。
+- [Benefits](https://piapi.ai/benefits)公开 USDT 大额充值 5%/8%/11%/15% 赠送档位，部分模型另有活动折扣。
+- 有[简体中文站](https://piapi.ai/zh-CN)且支持 USDT，支付可达性线索最好；但没有中国备用 API 域名、内地节点或 SLA，网络访问仍需实测。
+
+## 4. Replicate（P2）
+
+### 已核验能力
+
+- 高清放大：[Recraft Crisp Upscale](https://replicate.com/recraft-ai/recraft-crisp-upscale)、[Google Upscaler](https://replicate.com/google/upscaler)。
+- 重打光：[IC-Light Background](https://replicate.com/zsxkib/ic-light-background)（社区模型）。
+- 多视角：[Zero123++](https://replicate.com/jd7h/zero123plusplus)（社区模型）。
+- 背景移除：[Bria Remove Background](https://replicate.com/bria/remove-background)。
+- 扩图：[FLUX Fill Pro](https://replicate.com/black-forest-labs/flux-fill-pro)。
+- 照片修复：[Microsoft Old Photos](https://replicate.com/microsoft/bringing-old-photos-back-to-life)。
+- 图片、视频、音频均有大规模目录，例如 [Seedance 2.0](https://replicate.com/bytedance/seedance-2.0) 与 [Stable Audio 2.5](https://replicate.com/stability-ai/stable-audio-2.5)。
+
+### 公共协议与风险
+
+- Base URL：`https://api.replicate.com/v1`，Bearer 鉴权。
+- 官方模型：`POST /v1/models/{owner}/{name}/predictions`；社区模型：`POST /v1/predictions` 并固定 version hash。
+- 查询：`GET /v1/predictions/{id}`；状态为 `starting`、`processing`、`succeeded`、`failed`、`canceled`。见[HTTP API](https://replicate.com/docs/reference/http)和[预测说明](https://replicate.com/docs/topics/predictions/create-a-prediction)。
+- 预测输入、输出和日志默认在一小时后清理；结果域名 `replicate.delivery` / `*.replicate.delivery` 必须纳入媒体下载白名单并及时落盘。
+- 社区模型必须锁定 version、审计许可证并处理作者更新/下架，不应首版开放任意 owner。
+
+### 价格与内地访问
+
+- [价格页](https://replicate.com/pricing)按输出或 GPU 秒计费，[企业方案](https://replicate.com/enterprise)提供 volume discounts，个别模型有临时折扣。
+- 无中文站、中国节点或内地 SLA；API 与结果媒体域名都需要实测。
+
+## 5. Novita AI（P3）
+
+- 官方 [llms.txt](https://novita.ai/llms.txt)显示其覆盖图片、视频、音频和 LLM。
+- Base URL：`https://api.novita.ai`，Bearer 鉴权；v3 异步任务通过 [`GET /v3/async/task-result`](https://novita.ai/docs/api-reference/model-apis-task-result)统一查询。
+- 统一状态包括 `TASK_STATUS_QUEUED/PROCESSING/SUCCEED/FAILED`，结果可包含 images/videos/audios。
+- 当前目录未核到独立 relight、图片视角、背景移除、outpaint 或完整照片修复 endpoint；[V2→V3 迁移文档](https://novita.ai/docs/guides/model-apis-v2-to-v3-migration)中的 `hires_fix.upscaler`、`restore_faces` 只是生成参数，不等于独立图片工具。
+- 媒体图片工具未核到稳定折扣，中国内地访问条件同样未知。因此本轮暂缓。
+
+## 适配前置验证清单
+
+1. 从中国移动、联通、电信分别测试主 API 域名的 DNS、TLS、首包时间与失败率。
+2. 同时测试上传域名和结果媒体域名；只测官网不能代表生成链路可用。
+3. 用不产生模型费用的鉴权失败/模型列表请求先验证网络和错误结构。
+4. 获得付费授权后，每家只选择 1 个低价工具做提交、轮询、取消、失败、落盘和实扣金额验证。
+5. 按真实结果再决定 Segmind 与 WaveSpeedAI 的先后顺序；PiAPI 作为价格/支付补充，不替代多角度和重打光主供应商。

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//345/277/253/351/200/237/351/200/202/351/205/215/344/276/233/345/272/224/345/225/206.md

@@ -0,0 +1,65 @@
+# 快速适配供应商
+
+> 目标：在写第一个模型文件前，先把供应商的稳定公共契约接好。后续模型适配只处理模型 ID、路由选择、参数和计价，不再重复写鉴权、上传、轮询与结果解析。
+>
+> 最后更新：2026-08-26
+
+## 1. 先判定供应商是否已适配
+
+不要因为设置页能保存 API Key，就宣称供应商已适配。至少要核对下列公共契约：
+
+| 层级 | 必须确认 |
+|---|---|
+| 地址 | Base URL、区域/备用线路、相对路由拼接规则 |
+| 鉴权 | Header 格式、Key 类型、是否与区域/业务空间绑定 |
+| 提交 | 同步/异步、提交方法、任务 ID 路径、是否可安全重试 |
+| 查询 | 轮询端点、进行中/成功/失败状态、失败消息路径 |
+| 结果 | 图片/视频/音频 URL 路径、string/string[]、JSON 字符串嵌套、有效期 |
+| 上传 | 本地路径、Data URI、Base64、公网 URL、官方临时存储的转换规则 |
+| 价格 | 公开价格页、可编程价格 API、任务实际扣费字段的优先级 |
+| 余额 | 是否可用同一枚生成 API Key 查询；若需云账号 AK/SK，不混入生成适配 |
+
+只有“当前已接入模型的必需分支”全部可运行，才标记为“已适配”。供应商未来可能支持、但当前没有模型使用的协议，记录在文档中，不预先造运行时分支。
+
+## 2. 供应商基础文档模板
+
+每家供应商在本目录保留一份 `<供应商>.md`，固定按下列顺序编写：
+
+1. 摘要：`providerId`、类型、鉴权、同步/异步、文档与价格登录状态。
+2. Base URL：主线、区域、备用线路与 Key 绑定关系。
+3. 生成端点：只记公共路由；模型专属路由留在模型文档。
+4. 提交、轮询与回调：任务 ID、状态、结果、错误的精确字段路径。
+5. 文件上传：上传方法、限制、返回值、有效期与生成请求需要的额外 Header。
+6. 结果保存：是否需要二次换取下载链接，以及链接有效期。
+7. 计价和余额：官方价格页、API、任务实际扣费字段；余额只记同 Key 可安全查询的方案。
+8. 项目对照：已接入文件、已覆盖能力、明确欠账。
+9. 原始链接索引：每个链接标注提供的信息与登录要求。
+
+## 3. 代码接入顺序
+
+1. 在 `packages/ai-sdk/src/providers/<provider>.ts` 实现提交、轮询和结果解析。
+2. 在 `providers/index.ts` 注册生成与续轮询分发。
+3. 如需官方上传，只在 `upload-providers.ts` 实现协议，由 `upload.ts` 统一选择；禁止模型或 UI 自己上传。
+4. 在 `keystore.ts`、`src/core/config/providers.ts`、`settingsStore.ts` 补齐 Key 与供应商元信息。
+5. 先用一个最小模型验证完整链路，再批量增加模型定义。
+
+供应商代码不得引用 UI，模型定义不得自行发起 `fetch()`。
+
+## 4. 最小验收
+
+- 提交测试：断言 URL、方法、鉴权和请求体。
+- 轮询测试：覆盖进行中、成功、明确失败和查询暂时失败。
+- 结果测试：覆盖单 URL、URL 数组和嵌套 JSON 字符串。
+- 上传测试：覆盖成功、缺少 URL、鉴权失败和超限。
+- 收尾：按 [testing.md](../../../../../docs/rules/testing.md) 选择精确测试与对应 TypeScript 工程，不默认跑全量。
+
+## 5. 当前供应商速查
+
+| 供应商 | 基础文档 | 当前生成运行时 |
+|---|---|---|
+| APIMart | [APIMart.md](APIMart.md) | 已接入异步提交、轮询、图片上传、余额与大陆备用线路受控切换 |
+| KIE | [KIE.md](KIE.md) | 已接入统一 Market 任务、轮询、上传与余额 |
+| Fal | [Fal.md](Fal.md) | 已接入直连/队列、轮询与结果解析 |
+| 百炼 | [百炼.md](百炼.md) | 已接入当前同步图片模型；区域、临时上传和异步契约见文档 |
+| 火山引擎 | [火山引擎.md](火山引擎.md) | 已接入当前同步图片模型；Files API 不视为生成通用上传 |
+| Grsai | [Grsai.md](Grsai.md) | 已接入统一生成接口、轮询、双线路探测；余额查询未接入（鉴权方式未确认，见文档第 8 节第 4 项） |