@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/Nano-Banana-Pro/Nano-Banana-Pro_Fal.md

@@ -0,0 +1,89 @@
+# Nano Banana Pro · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `fal-ai/nano-banana-pro`、`fal-ai/nano-banana-pro/edit` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议（Fal 通用）
+
+- **鉴权**：`Authorization: Key $FAL_KEY`
+- **同步**：`POST https://fal.run/<endpoint-id>`；**队列**：`POST https://queue.fal.run/<endpoint-id>`，`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）、`GET .../requests/{id}`
+- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
+
+## 2. 能力清单
+
+| 能力 | endpoint id |
+|---|---|
+| 文生图 | `fal-ai/nano-banana-pro` |
+| 图像编辑 | `fal-ai/nano-banana-pro/edit` |
+
+> 与 Nano Banana 2 的 `edit` 不同，**Pro 的 `edit` 没有 `video_url` / `audio_url` / `pdf_url` 上下文输入**。
+
+## 3. 请求参数
+
+### 3.1 两个端点共有
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 生成 / 编辑描述 |
+| `num_images` | integer | 可选 | `1` | 1–4 |
+| `seed` | integer | 可选 | 随机 | **本项目规则：绝对不显示**，不下发 |
+| `aspect_ratio` | string | 可选 | 文生图 **`1:1`**；编辑 **`auto`** | `auto`、`21:9`、`16:9`、`3:2`、`4:3`、`5:4`、`1:1`、`4:5`、`3:4`、`2:3`、`9:16`（11 个，**无极端比例**） |
+| `output_format` | string | 可选 | `png` | `jpeg` / `png` / `webp` |
+| `safety_tolerance` | string | 可选 | `"4"` | `"1"`（最严）~ `"6"`（最松） |
+| `sync_mode` | boolean | 可选 | `false` | `true` 时以 data URI 返回且不入请求历史 |
+| `system_prompt` | string | 可选 | `""` | 系统指令，作为 system instruction 下发给 Gemini |
+| `resolution` | string | 可选 | `1K` | `1K` / `2K` / `4K`（**无 0.5K**，Nano Banana 2 有） |
+| `limit_generations` | boolean | 可选 | **`true`** | 实验性参数：限制每轮提示只出 1 张，**忽略 prompt 中关于生成数量的指令** |
+| `enable_web_search` | boolean | 可选 | `false` | 联网搜索最新信息辅助生成 |
+
+> Pro **没有 `thinking_level`**（Nano Banana 2 有）。
+
+### 3.2 仅 `edit` 有
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_urls` | string[] | **必填** | 用于图生图 / 图像编辑的输入图 URL 列表 |
+
+## 4. 响应结构
+
+```json
+{ "images": [ { "url": "https://...", "content_type": "image/png", "width": 1024, "height": 1024 } ],
+  "description": "（模型对生成图像的描述）" }
+```
+
+## 5. 价格
+
+来源：两个端点的 `llms.txt`（2026-08-22 读取）。Fal 标注 **Pricing may change in the future**。
+
+| 项 | 价格 |
+|---|---|
+| 基础（1K / 2K） | **$0.15 / 张**（$1.00 可跑 7 次） |
+| 4K | 标准价 × **2** = $0.30 / 张 |
+| `enable_web_search` | 额外 **+$0.015** |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**有 `seed`**（不下发），无负面提示词字段。
+- `output_format`、`sync_mode` 不展示、不请求。
+- `aspect_ratio` 的默认值在两个端点上不同（文生图 `1:1`、编辑 `auto`），若要统一行为必须显式下发。
+- `limit_generations` 默认 `true`，会忽略 prompt 中的数量指令。
+- Fal 是四家里最贵的 Nano Banana Pro 渠道（$0.15/张 vs KIE $0.09、APIMart $0.03），成本敏感场景需要注意。
+- `edit` 的 `image_urls` 是必填。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生图模型页 | https://fal.ai/models/fal-ai/nano-banana-pro | 否 |
+| 文生图 schema + 价格 | https://fal.ai/models/fal-ai/nano-banana-pro/llms.txt | 否 |
+| 编辑模型页 | https://fal.ai/models/fal-ai/nano-banana-pro/edit | 否 |
+| 编辑 schema + 价格 | https://fal.ai/models/fal-ai/nano-banana-pro/edit/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |

package/docs/model-adaptation/Nano-Banana-Pro/Nano-Banana-Pro_Grsai.md

@@ -0,0 +1,82 @@
+# Nano Banana Pro · Grsai
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-26 |
+| 模态 | 图片 |
+| 供应商 | Grsai（聚合中转，详见 [Grsai 基础文档](../供应商/Grsai.md)） |
+| 平台模型 ID（渠道） | `nano-banana-pro`、`nano-banana-pro-vt`、`nano-banana-pro-cl`、`nano-banana-pro-vip`、`nano-banana-pro-4k-vip` |
+| 接口形态 | 提交 `POST /v1/api/generate` + 轮询 `GET /v1/api/result`（新版统一接口，`replyType` 三选一） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录（dashboard「模型列表」页） |
+| 项目当前状态 | 已接入，[catalog/grsai/nano-banana-pro.model.ts](../../../src/catalog/grsai/nano-banana-pro.model.ts)，`canonicalModelId: nano-banana-pro` |
+
+> 与 Nano Banana 2 类似，Pro 也拆成 5 个渠道，价差可达 **10 倍**（`nano-banana-pro` ¥0.09 起 vs `nano-banana-pro-4k-vip` 最高 ¥1.8）。特别之处：`nano-banana-pro` 与 `nano-banana-pro-vt` 的积分消耗、价格区间、支持分辨率**完全相同**，大概率是两条互为备份的后端线路，而不是能力差异——这点与 Nano Banana 2 的 `-lite`/`-fast` 重复现象类似。代码里没有假定二者等价并合并成一个选项，而是把 `vt` 保留为独立渠道（标签标注「备用线路」），接入前的实测仍然有价值，但即使证实等价也只是删掉一个选项，不影响其余实现。
+
+## 1. 请求参数（新版统一接口）
+
+`POST /v1/api/generate`：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `model` | string | 必填 | 五个渠道枚举之一，见下表 |
+| `prompt` | string | 必填 | 提示词 |
+| `images` | array\<string\> | 可选 | 参考图，base64 或 URL 混填，无需单独上传 |
+| `aspectRatio` | string | 可选 | 见 1.1 |
+| `imageSize` | string | 可选 | `1K` / `2K` / `4K`，具体渠道支持哪些档见第 2 节表格 |
+| `replyType` | string | 可选 | `json` / `stream` / `async` |
+
+### 1.1 `aspectRatio` 取值
+
+通用 11 档：`auto`、`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`5:4`、`4:5`、`21:9`
+
+API 文档把「额外支持 `1:4`/`4:1`/`1:8`/`8:1`」明确标注为「nano-banana-2 系列额外支持」，字面上不包含 Pro 系列——**Pro 系列大概率不支持这四档极端比例，但文档没有反向明确写「Pro 不支持」，接入前需要实测确认**。
+
+## 2. 五个渠道对照
+
+来源：[dashboard 模型列表](https://grsai.com/zh/dashboard/models)（2026-08-26 实测，未登录可见）。价格区间由「积分消耗 × 积分单价区间」得出，下限对应 ¥999 最高档充值套餐（约 5 折），上限对应无优惠单价，详见 [Grsai 基础文档 §5.1](../供应商/Grsai.md)。
+
+| 渠道 | 积分消耗 | 价格区间 | 支持分辨率 | 相对基准倍率 |
+|---|---|---|---|---|
+| `nano-banana-pro` | 1800/次 | ¥0.09~¥0.18/次 | 1K / 2K / 4K | 1×（基准） |
+| `nano-banana-pro-vt` | 1800/次 | ¥0.09~¥0.18/次 | 1K / 2K / 4K | 1×（与基准渠道完全相同，见上方说明） |
+| `nano-banana-pro-cl` | 10000/次 | ¥0.5~¥1/次 | 1K | 5.6× |
+| `nano-banana-pro-vip` | 10000/次 | ¥0.5~¥1/次 | 1K / 2K | 5.6× |
+| `nano-banana-pro-4k-vip` | 18000/次 | ¥0.9~¥1.8/次 | 4K | 10× |
+
+`nano-banana-pro-cl` 与 `nano-banana-pro-vip` 积分消耗和价格区间也完全相同，唯一差异是 `vip` 多支持 2K——即「同价位下 vip 覆盖的分辨率范围更大」，`cl` 目前只保留 1K 档（2026-06-24 公告显示这是调整后的结果，此前 `cl` 支持的分辨率范围更宽，因渠道成本上升被收窄，见第 4 节历史）。
+
+## 3. 响应
+
+结构、状态枚举、结果链接有效期等公共部分见 [Grsai 基础文档](../供应商/Grsai.md) 第 3、8 节，五个渠道共用同一套响应格式，不在本文件重复。
+
+## 4. 价格变动历史（公告原文摘录，供判断渠道稳定性参考）
+
+- 2026-04-14：因 Gemini 官方缩减算力，`cl` 与 `vip` 系渠道被迫更换后端线路，成本上升，两类渠道当日集体涨价
+- 2026-05-20：`nano-banana-2`、`nano-banana-pro` 因谷歌大更新算法变动导致调用失败，数小时后修复恢复
+- 2026-06-19：香蕉系列 2K/4K 分辨率一度因谷歌官方 BUG 无法出图；同日 `nano-banana-pro-vip` 的 2K/4K 分辨率也单独出现过短暂下线又恢复
+- 2026-06-24：「cl 渠道模型」分辨率与价格调整，公告原文点名 `nano-banana-pro-cl` 的分辨率支持范围被收窄（调整后即当前表格里的「仅 1K」）
+- 2026-06-28：「cl 渠道模型」二次调价，公告原文「近期风控严峻导致成本骤升……目前仍处于亏损状态」
+- 2026-07-10 / 2026-08-11：`nano-banana-pro` 与 `nano-banana-2` 因谷歌官方策略/算法变动，各发生过一次数小时到近一天的整体维护/异常，与渠道无关，是模型家族级别的不稳定
+
+`cl` 渠道半年内经历了「分辨率被收窄」+「两次调价」，是本次调研中稳定性证据最弱的渠道；`vip` 渠道价格与 `cl` 相同但保留了更宽的分辨率范围，更贵的 `4k-vip` 与更便宜的基准渠道都发生过官方级别的整体维护，说明「贵=稳」不是绝对规律，只是 `cl` 渠道在公告里被单独点名调整的次数明显更多。
+
+## 5. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。五个渠道文档都没有这两个字段。
+- 五个渠道共享同一套请求/响应结构，做成模型内的「渠道」下拉：字段名按项目约定走 `sharedFieldText('apiChannel')` 并声明 `role: 'channel'`（统一显示「渠道」），选项文案由模型自定义为「标准 / VT（备用线路）/ CL·1K / VIP / VIP·4K」——项目不约束渠道选项文案。
+- 分辨率参数只在「标准/VT/VIP」三个渠道可见，且用 `filterOptions` + `autoSwitch` 联动把 VIP 渠道的可选分辨率收窄到 1K/2K（用户已经选了 4K 时切到 VIP 会自动回退到 2K）；`cl` 与 `4k-vip` 分辨率固定，不显示该控件。
+- `cl` 渠道的分辨率支持范围历史上被官方收窄过一次（2026-06-24），代码按当前 dashboard 页面的「仅 1K」实现，不是假定「支持所有分辨率」；后续官方再调整需要同步改 `channelToModel` 映射表。
+- Pro 系列的比例下拉只暴露 11 档基础比例，**没有**加入 `1:4`/`4:1`/`1:8`/`8:1` 四档极端比例——文档没有反向明确写「Pro 不支持」，但也没写「支持」，按不确定不暴露处理；确认支持后再补选项比确认不支持后再删选项风险更低。
+- `pricing.calculator` 按渠道返回区间上限（无优惠价）：标准/VT ¥0.18，CL·1K/VIP ¥1，VIP·4K ¥1.8。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 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 公告（渠道调价与模型上下架历史） | https://grsai.com/zh/dashboard/announcements | 否 |
+| API Key 管理 | https://grsai.ai/zh/dashboard/api-keys | **是** |

package/docs/model-adaptation/Nano-Banana-Pro/Nano-Banana-Pro_KIE.md

@@ -0,0 +1,64 @@
+# Nano Banana Pro · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `nano-banana-pro` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> KIE 的文档标题是「Nano Banana Pro 图生图」，路径在 `market/google/pro-image-to-image`，但 `image_input` 是**可选**的——同一个 model 同时承载文生图与图生图。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "nano-banana-pro", callBackUrl?, input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`
+
+## 2. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 最多 **10000** 字符（Nano Banana 2 是 20000） |
+| `input.image_input` | array | 可选 | — | 输入图。**最多 8 张**（比 APIMart / Fal 的 14 张少）。字段名是 `image_input`。传上传后的文件 URL；支持 `image/jpeg`、`image/png`、`image/webp`；单张 ≤ 30 MB |
+| `input.aspect_ratio` | string | 可选 | **`1:1`** | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`、`auto`（11 个，无极端比例） |
+| `input.resolution` | string | 可选 | `1K` | `1K` / `2K` / `4K` |
+| `input.output_format` | string | 可选 | `png` | `png` / `jpg`（注意是 `jpg` 不是 `jpeg`） |
+
+## 3. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`。
+
+## 4. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `nano banana pro`；1 Credit = $0.005）。
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| 1/2K | 18.0 /张 | **$0.09/张** | $0.15 | 40% |
+| 4K | 24.0 /张 | **$0.12/张** | $0.3 | 60% |
+
+## 5. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
+- `output_format` 默认不显示、不请求；取值是 `jpg` 不是 `jpeg`。
+- **参考图上限只有 8 张**，是所有 Nano Banana Pro 供应商里最少的；跨供应商的上传上限要按供应商取值。
+- 图片字段名是 `image_input`（不是 `image_urls`）。
+- `aspect_ratio` 默认 `1:1`，而 APIMart / Fal 的编辑端点默认 `auto`。
+- 提示词上限 10000 字符。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Nano Banana Pro（图生图页，同时承载文生图） | https://docs.kie.ai/cn/market/google/pro-image-to-image | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `nano banana pro`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |

package/docs/model-adaptation/Pixelcut-/350/203/214/346/231/257/347/247/273/351/231/244/Pixelcut-/350/203/214/346/231/257/347/247/273/351/231/244_Fal.md

@@ -0,0 +1,79 @@
+# Pixelcut 背景移除（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Pixelcut Background Remover |
+| API endpoint ID | `pixelcut/background-removal` |
+| 模态 | JPEG/PNG 单图 → 透明背景 PNG |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/pixelcut-background-removal` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
+| 价格 | `$0.016 / image` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+## 1. 能力与输出模式
+
+Pixelcut 端点支持三种 `output_format`：
+
+- `rgba`：完整 RGBA 结果，返回 `image.url`。
+- `alpha`：单独 alpha 结果，返回 `image.url`。
+- `zip`：返回 `file.url`。
+
+项目对新模型不显示、不发送 `output_format`，因此该工具使用官方默认 `rgba`，产品契约只接收透明背景图的 `image.url`。`alpha` 和 `zip` 不进入首版。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/pixelcut/background-removal`
+- 队列提交：`POST https://queue.fal.run/pixelcut/background-removal`
+- 状态：`GET https://queue.fal.run/pixelcut/background-removal/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/pixelcut/background-removal/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/pixelcut/background-removal/requests/{request_id}/cancel`
+- 首版结果路径：`image.url`
+
+队列状态仅有 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` / `request_id` 必填。结果 schema 的 `image` 和 `file` 都是可选且可空，所以 `COMPLETED` 后必须取结果并对当前 RGBA 契约严格校验非空 `image.url`；空对象不能当作成功。其余复用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_url` | string | 是 | 只明确支持 JPEG / PNG；官方未公布尺寸和文件大小上限 | 恰好 1 张已有素材，经 Fal CDN 上传；提交前校验 MIME/extension |
+| `output_format` | enum | 否 | `rgba`；`rgba` / `alpha` / `zip` | 不展示、不发送，使用默认 `rgba` |
+| `sync_mode` | boolean | 否 | `true` | **不展示但固定发送 `false`** |
+
+`sync_mode` 是本批工具中必须覆盖官方默认的例外：官方说明 `true` 会返回 data URL，而 Henji-AI 的持久队列和媒体落盘需要 CDN URL。请求 builder 必须固定发送 `sync_mode: false`，不能只依赖平台默认。
+
+## 4. 请求与响应示例
+
+```json
+{
+  "image_url": "https://v3.fal.media/files/.../product.jpg",
+  "sync_mode": false
+}
+```
+
+```json
+{
+  "image": {
+    "url": "https://cdn3.pixelcut.app/fal/background-remover/result.png"
+  }
+}
+```
+
+## 5. 计价与未知项
+
+- 实时 `llms.txt` 标价 `$0.016 / image`，静态估价为 `$0.016 / 次`。
+- 输入文档只写 JPEG / PNG，未说明是否完整保留 EXIF/色彩配置，也未给大小、尺寸、最大主体数、延迟 SLA 和 CDN 保留期。
+- 付费验收要覆盖头发/半透明物体、珠宝反射、多主体、白色商品和输入 PNG 透明通道。
+- 结果 URL 使用 Pixelcut CDN 而不一定是 `fal.media`，结果解析不能按域名过滤。
+
+## 6. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/pixelcut/background-removal | 否 | 2026-08-29 |
+| 实时字段、枚举、示例与价格 | https://fal.ai/models/pixelcut/background-removal/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（输出可空性、必填与枚举） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=pixelcut/background-removal | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |
+| Fal 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） | 2026-08-29 |

package/docs/model-adaptation/Qwen-Image-3.0/Qwen-Image-3.0_APIMart.md

@@ -0,0 +1,117 @@
+# Qwen Image 3.0 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `qwen-image-3.0`（标准）、`qwen-image-3.0-pro`（Pro） |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/images/generations` → `{ "code": 200, "data": [{ "status": "submitted", "task_id": "..." }] }`
+- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
+- **轮询建议**：每 **3–5 秒**一次，超时约 **3 分钟**（2K + 多张更慢）
+- **结果存储**：图片已镜像到平台 CDN，文档称**返回地址长期可用**
+
+## 2. 支持的模型
+
+| 模型名 | 说明 | 最大张数 | 分辨率 |
+|---|---|---|---|
+| `qwen-image-3.0` | 指令理解清晰，文字渲染稳定，常规出图更划算 | 6 张 | 1K / 2K |
+| `qwen-image-3.0-pro` | 内容更丰实，适合报纸、分镜、菜单、试卷等密集排版 | 6 张 | 1K / 2K |
+
+> 排版密集、字多的场景优先用 `-pro`。**模型名与 2.0 系列不兼容互换。**
+
+## 3. 能力清单
+
+| 能力 | 触发方式 |
+|---|---|
+| 文生图 | 只传 `prompt` |
+| 图生图 / 图像编辑（1–3 张参考图） | `image_urls` |
+| 提示词智能改写 | `prompt_extend: true` + `prompt_extend_mode` |
+| 多张输出 | `n`（1–6） |
+| 反向提示词 | `negative_prompt` |
+
+## 4. 请求参数（Body）
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | `qwen-image-3.0` / `qwen-image-3.0-pro` |
+| `prompt` | string | 必填 | — | 最长约 **4.5k token** |
+| `image_urls` | string[] | 可选 | — | **1–3 张**。公网 `http(s)://` URL 或 `data:image/png;base64,...`（base64 会先转存）。格式 JPG/JPEG/PNG/BMP/TIFF/WEBP/GIF；单张 ≤ 10 MB；宽高建议 384–2048 px |
+| `resolution` | string | 可选 | `1K` | `1K`（兼容小写）/ `2K`。也可跳过档位在 `size` 中直接写像素；**直接给像素时，面积 > 225 万像素按 2K 档计费** |
+| `size` | string | 可选 | `1:1` | 比例 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`；兼容 `16x9` 写法；或直接像素 `1024x1024`。自定义像素时**宽与高各自**须在 512–2048，宽高比 1:8 ~ 8:1。**不传 `size` 也不传 `resolution` 时固定出 1024×1024** |
+| `n` | integer | 可选 | `1` | **1–6，超过 6 自动截断为 6** |
+| `negative_prompt` | string | 可选 | — | 反向提示词。**本项目规则：绝对不显示**，不下发 |
+| `prompt_extend` | boolean | 可选 | **`false`** | 提示词智能改写。APIMart **默认关闭**（官方百炼默认是开启），以保证结果可预测 |
+| `prompt_extend_mode` | string | 可选 | — | 仅 3.0 系列，且需 `prompt_extend: true`。`direct`（T2I/I2I 都可）/ `agent`（**仅文生图**，改写更激进）。取值非法时忽略该字段 |
+| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审提示词与输入图 |
+
+### 尺寸对照表（`resolution` 档位 × `size` 比例）
+
+| 分辨率 | 1:1 | 4:3 | 3:4 | 16:9 | 9:16 | 3:2 | 2:3 |
+|---|---|---|---|---|---|---|---|
+| 1K | 1024×1024 | 1152×864 | 864×1152 | 1280×720 | 720×1280 | 1248×832 | 832×1248 |
+| 2K | 2048×2048 | 2048×1536 | 1536×2048 | 2048×1152 | 1152×2048 | 2048×1360 | 1360×2048 |
+
+> APIMart 的比例集合**没有 `21:9`**（KIE 有），也没有 `2:1` / `1:2`。
+
+## 5. 限制汇总（文档明列）
+
+| 项 | 限制 |
+|---|---|
+| 提示词 | ≤ 4.5k token |
+| 输出尺寸 | 自定义像素时宽、高各自 512–2048；宽高比 1:8 ~ 8:1 |
+| 出图张数 | 1–6（超出自动截断） |
+| 参考图数量 | 1–3 张 |
+| 参考图格式 | JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF |
+| 参考图大小 | ≤ 10 MB，宽高建议 384–2048 px |
+
+常见 400 错误：自定义 `size` 宽或高不在 512–2048、比例越界、`agent` 用在图生图、参考图不可访问或超 10 MB。限流返回 429。
+
+## 6. 响应结构
+
+提交返回 `{ code, data: [{ status: "submitted", task_id }] }`；轮询 `GET /v1/tasks/{task_id}` 读 `result.images`（`url` 为数组，多张时一个任务含多个结果）。
+
+## 7. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)（2026-08-22 读取，1 Credit ≈ $0.1）。
+
+**QWEN-IMAGE-3.0**（3 个档位，默认/1K/2K 同价）
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 / 1K / 2K | 0.205712 Credits/张 ≈ **$0.0205712/张** | $0.025714/张 | 20% |
+
+**QWEN-IMAGE-3.0-PRO**
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 / 1K | 0.285712 Credits/张 ≈ **$0.0285712/张** | $0.035714/张 | 20% |
+| 2K | 0.571432 Credits/张 ≈ **$0.0571432/张** | $0.071429/张 | 20% |
+
+计费规则（文档）：按实际出图张数 × 分辨率档位计费；档位按**实际像素面积**判定（> 225 万像素为 2K）。`qwen-image-3.0` 的 1K/2K 同价；`-pro` 的 2K 为 1K 的两倍。**任务失败全额退款；参考图不额外收费。**
+
+## 8. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口**有 `negative_prompt`**，必须主动不注册、不下发（无 `seed` 字段）。
+- `prompt_extend` 在 APIMart 默认 `false`，与百炼官方默认 `true` 相反；跨供应商同一模型的默认行为不一致，需在 schema 层显式指定。
+- 比例集合仅 7 个（无 `21:9`），与 KIE 的 8 个不一致；`n > 6` 会**静默截断**而非报错。
+- 不传 `size` 与 `resolution` 时固定 1024×1024，不是「模型自动推荐」——与百炼官方行为不同。
+- `output_format` 该接口未提供，无需处理。
+
+## 9. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Qwen Image 3.0 图像生成 API | https://docs.apimart.ai/cn/api-reference/images/qwen-image-3.0/generation | 否 |
+| 同页纯 Markdown | https://docs.apimart.ai/cn/api-reference/images/qwen-image-3.0/generation.md | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（搜 QWEN-IMAGE-3.0 / QWEN-IMAGE-3.0-PRO） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

package/docs/model-adaptation/Qwen-Image-3.0/Qwen-Image-3.0_Fal.md

@@ -0,0 +1,84 @@
+# Qwen Image 3.0 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 模态 | 图片 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `alibaba/qwen-image-3/text-to-image`、`alibaba/qwen-image-3/edit` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> Fal 上只有一个 Qwen Image 3 系列端点，未区分标准版 / Pro 版。价格档位（1K $0.04、2K $0.075）与百炼 Pro 的档位结构一致，但 Fal 未标注具体对应哪个上游 model id。
+
+## 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 |
+|---|---|
+| 文生图 | `alibaba/qwen-image-3/text-to-image` |
+| 图像编辑（1–3 张参考图） | `alibaba/qwen-image-3/edit` |
+
+## 3. 请求参数（两个端点共有）
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 支持中英文，最长 5000 字符 |
+| `negative_prompt` | string | 可选 | `""` | 最长 500 字符。**本项目规则：绝对不显示**，不下发 |
+| `image_size` | 枚举或对象 | 可选 | 文生图 `square_hd`；编辑**无默认**（不传时模型自动决定） | 枚举 `square_hd`、`square`、`portrait_4_3`、`portrait_16_9`、`landscape_4_3`、`landscape_16_9` 等，或 `{ width, height }`。总像素须在 512×512 ~ 2048×2048 |
+| `enable_prompt_expansion` | boolean | 可选 | **`true`** | LLM 自动改写提示词 |
+| `seed` | integer | 可选 | 随机 | `[0, 2147483647]`。**本项目规则：绝对不显示**，不下发 |
+| `enable_safety_checker` | boolean | 可选 | `true` | 关闭需账号授权 |
+| `sync_mode` | boolean | 可选 | `false` | `true` 时以 data URI 返回且不入请求历史 |
+| `num_images` | integer | 可选 | `1` | 1–6 |
+| `output_format` | string | 可选 | `png` | `jpeg` / `png` / **`webp`**（比其他供应商多一个 webp） |
+
+**仅 `edit` 有：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_urls` | string[] | 必填 | **1–3 张，必填**。顺序有意义——在 prompt 中以 'image 1' / 'image 2' / 'image 3' 引用。每边 384–2048 px；单张 ≤ 10 MB；格式 JPEG、JPG、**PNG（不能带 alpha）**、WEBP |
+
+## 4. 响应结构
+
+```json
+{ "images": [ { "url": "https://v3b.fal.media/files/b/.../xxx.png" } ], "seed": 42 }
+```
+
+`images` 与 `seed` 都是必返回字段。输出里的 `seed` 只是回传，不暴露成可编辑参数。
+
+## 5. 价格
+
+来源：两个端点的 `llms.txt`（2026-08-22 读取），两端点同价。
+
+| 输出分辨率 | 单价 |
+|---|---|
+| 1K | **$0.04 / 张** |
+| 2K | **$0.075 / 张** |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**两个字段都存在**，必须主动不注册、不下发。
+- `output_format`、`sync_mode` 不展示、不请求。
+- `edit` 的 `image_urls` 是**必填**（不像 Seedream 的 edit 可省），且 PNG 不允许带 alpha 通道——透明图需先合成背景。
+- `edit` 的 `image_size` 没有默认值，不传就由模型决定，与文生图行为不同。
+- `enable_prompt_expansion` 默认 `true`，会改变出图结果。
+- SDK 固定比例覆盖通用 10 档并提供显式 `1MP` 请求档；`1MP` 文生图发送约 1024²、16 对齐的对象，编辑分支按官方契约省略 `image_size`。旧默认仍是 1K + 提示词扩写开启；需要复刻插件旧结果时 adapter 必须显式传 `falQwenImage30Resolution: '1MP'` 与 `falQwenImage30PromptExpansion: false`。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生图模型页 | https://fal.ai/models/alibaba/qwen-image-3/text-to-image | 否 |
+| 文生图 schema + 价格 | https://fal.ai/models/alibaba/qwen-image-3/text-to-image/llms.txt | 否 |
+| 编辑模型页 | https://fal.ai/models/alibaba/qwen-image-3/edit | 否 |
+| 编辑 schema + 价格 | https://fal.ai/models/alibaba/qwen-image-3/edit/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |

package/docs/model-adaptation/Qwen-Image-3.0/Qwen-Image-3.0_KIE.md

@@ -0,0 +1,103 @@
+# Qwen Image 3.0 · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | 标准版 `qwen3/text-to-image`、`qwen3/image-to-image`；Pro 版 `qwen3-pro/text-to-image`、`qwen3/pro-image-to-image` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> ⚠️ **文档不一致，接入前必须实测确认**：Pro 文生图页面的 `model` 字段中，`enum` 写的是 `qwen3-pro/text-to-image`，而 `default` 与描述文字写的是 `qwen3/pro-text-to-image`；Pro 图生图页面则统一为 `qwen3/pro-image-to-image`。
+
+## 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: [...] }`；失败读 `failCode` / `failMsg`
+
+## 2. 能力清单
+
+| 能力 | model |
+|---|---|
+| 标准版 文生图 | `qwen3/text-to-image` |
+| 标准版 图生图 | `qwen3/image-to-image` |
+| Pro 版 文生图 | `qwen3-pro/text-to-image`（见上方不一致提示） |
+| Pro 版 图生图 | `qwen3/pro-image-to-image` |
+
+> KIE 上 Qwen Image 3.0 **没有多张输出参数**（无 `n` / `num_images`），一次任务出 1 张。
+
+## 3. 请求参数（四个端点共有）
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 0–5000 字符，支持中英文 |
+| `input.resolution` | string | 可选 | `1K` | `1K` / `2K` |
+| `input.image_size` | string | 可选 | **`16:9`** | `1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`。注意**默认不是 1:1** |
+| `input.output_format` | string | 可选 | `png` | `png` / `jpeg` |
+| `input.prompt_extend` | boolean | 可选 | **`true`**（推荐） | 智能提示词改写 |
+| `input.nsfw_checker` | boolean | 可选 | `false` | `false` 时关闭内容过滤，结果直接返回 |
+| `input.negative_prompt` | string | 可选 | — | 0–5000 字符。**本项目规则：绝对不显示**，不下发 |
+| `input.seed` | integer | 可选 | `1` | `[0, 2147483647]`。**本项目规则：绝对不显示**，不下发 |
+
+**图生图端点额外必填：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `input.image_urls` | array | 必填 | **1–3 张**。传上传后的文件 URL。支持 `image/jpeg`、`image/png`、`image/webp`、`image/bmp`、`image/tiff`、`image/gif`；每张 ≤ 10 MB |
+
+> KIE 没有 `prompt_extend_mode`（百炼与 APIMart 有 `direct` / `agent`）。
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`。
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `qwen image 3`；1 Credit = $0.005）。
+
+**Qwen image 3.0**
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 |
+|---|---|---|---|
+| 文生图 1K | 4.8 /张 | **$0.024/张** | $0.03 |
+| 文生图 2K | 4.8 /张 | **$0.024/张** | $0.03 |
+| 输出 1K / 2K | 4.8 /张 | **$0.024/张** | $0.03 |
+| 输入图 1K / 2K | 0.5 /张 | **$0.0025/张** | $0.003 |
+
+**Qwen image 3.0 Pro**
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 |
+|---|---|---|---|
+| 文生图 1K | 6.4 /张 | **$0.032/张** | $0.04 |
+| 文生图 2K | 12 /张 | **$0.06/张** | $0.075 |
+| 输出 1K | 6.4 /张 | **$0.032/张** | $0.04 |
+| 输出 2K | 12 /张 | **$0.06/张** | $0.075 |
+| 输入图 1K / 2K | 0.5 /张 | **$0.0025/张** | $0.003 |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口**两个字段都存在**，必须主动不注册、不下发。
+- `image_size` 默认 `16:9`，与其他供应商的 `1:1` 默认不同；若产品语义是「默认方形」，必须显式下发 `1:1`。
+- 比例集合含 `21:9`（APIMart 没有）。
+- `prompt_extend` 默认 `true`，与 APIMart（`false`）相反。
+- Pro 端点的 model 字符串在官方文档中自相矛盾，接入时先用两种写法各打一次任务确认。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Qwen3 文生图 | https://docs.kie.ai/cn/market/qwen3/text-to-image | 否 |
+| Qwen3 图生图 | https://docs.kie.ai/cn/market/qwen3/image-to-image | 否 |
+| Qwen3 Pro 文生图 | https://docs.kie.ai/cn/market/qwen3-pro/text-to-image | 否 |
+| Qwen3 Pro 图生图 | https://docs.kie.ai/cn/market/qwen3-pro/image-to-image | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `qwen image 3`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |