@henjicc/ai-sdk 0.2.8

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

@@ -0,0 +1,238 @@
+# APIMart · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 供应商类型 | 聚合中转（非模型原厂） |
+| 项目内 providerId | `apimart` |
+| 主域名 | `apimart.ai`（海外主站） |
+| 中国大陆友好域名 | `apib.ai` / `aiuxu.com` / `aishuch.com`（**本目录中唯一提供大陆备用线路的供应商**） |
+| 鉴权 | `Authorization: Bearer <API Key>` |
+| 任务模型 | 异步为主（提交拿 `task_id` → 轮询 / Webhook） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 端点
+
+### 1.1 Base URL 与备用域名
+
+官方文档只写了一个地址：
+
+```
+https://api.apimart.ai
+```
+
+但 APIMart 站点在登录页顶部提供了**备用访问域名**面板，原文：「网络访问受限时，请使用支持中国大陆的域名，建议收藏备用。」
+
+| 站点域名 | 定位 | API 端点 | 上传端点 | 文档站 |
+|---|---|---|---|---|
+| `apimart.ai` | 海外主站 | `https://api.apimart.ai` | `https://upload.apimart.ai` | `https://docs.apimart.ai` |
+| `apib.ai` | 中国大陆可用 | `https://api.apib.ai` | `https://upload.apib.ai` | `https://docs.apib.ai` |
+| `aiuxu.com` | 中国大陆可用 | `https://api.aiuxu.com` | `https://upload.aiuxu.com` | `https://docs.aiuxu.com` |
+| `aishuch.com` | 中国大陆可用 | `https://api.aishuch.com` | `https://upload.aishuch.com` | `https://docs.aishuch.com` |
+
+**实测结论（2026-08-22，未登录 curl）**：四个 `api.*` 主机对 `GET /v1/models` 均返回 `401 {"error":{"message":"API key is required ...","type":"apimart_error"}}`，即**四条线路都是同一套 API，仅域名不同，路径与协议完全一致**；四个 `upload.*` 主机均返回 200。
+
+> 适配含义：Base URL 应当**可配置或有受控备用线路**，而不是只硬编码 `api.apimart.ai`，否则大陆用户在主线路不可达时无法自救。当前代码状态见第 9 节（连通性探测 + 进程内记忆，不做地理位置判断）。
+>
+> 注意：生成结果 URL 与上传返回 URL 用的是**请求时那条线路的 `upload.*` 域名**，切换线路后旧结果链接是否仍可访问未验证，转存时按原域名下载。
+
+### 1.2 API 端点一览
+
+| 用途 | 方法与路径 | 说明 |
+|---|---|---|
+| 图片生成 | `POST /v1/images/generations` | 统一图片入口，模型由 body 的 `model` 决定 |
+| 视频生成 | `POST /v1/videos/generations` | 统一视频入口 |
+| Midjourney 专用 | `POST /v1/midjourney/{action}` | 18 个端点，见 [Midjourney_APIMart.md](../Midjourney/Midjourney_APIMart.md) |
+| 查询任务 | `GET /v1/tasks/{task_id}?language=zh` | 统一任务查询 |
+| MJ 风格查询 | `GET /v1/midjourney/{task_id}` | 额外返回 `buttons[].customId` |
+| 上传图片 | `POST /v1/uploads/images` | multipart |
+| 令牌余额 | `GET /v1/balance`（别名 `GET /balance`） | 单个 API Key 维度 |
+| 用户余额 | `GET /v1/user/balance`（别名 `GET /user/balance`） | 主账号维度 |
+| 模型列表 | `GET /v1/models`（带 `expand` 可返回参数 schema） | 文本模型元数据为主 |
+| 文本模型定价 | `GET /api/pricing/model` | 只对 TokenPricingV2 文本模型有效，**图片/视频模型不走这个** |
+
+## 2. 鉴权
+
+```
+Authorization: Bearer <API Key>
+Content-Type: application/json
+```
+
+API Key 在 https://apimart.ai/keys 创建（**需登录**），可设置额度上限、模型权限白名单、IP 白名单。
+
+## 3. 提交与查询
+
+### 3.1 提交
+
+同步返回 `task_id`，实际生成异步进行。本项目当前额外下发两个请求头（见 `providers/apimart.ts`）：
+
+- `Idempotency-Key: <requestId>`：APIMart 支持幂等键，重放不会重复计费
+- `X-APIMart-Response-Version: 2026-07-27`：锁定响应结构版本，避免上游改结构导致解析失效
+
+> 当前公开快速开始、开发指南和 API 参考中未找到这两个 Header 的稳定契约说明。文档将它们标记为“项目已有行为”，不把它们当作新客户端必须复制的公开协议。
+
+### 3.2 轮询
+
+`GET /v1/tasks/{task_id}?language=zh`
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": "task_01KA040M0HP1GJWBJYZMKX1XS1",
+    "status": "completed",
+    "cost": 0.15,
+    "credits_cost": 1.5,
+    "progress": 100,
+    "result": { "images": [{ "url": ["https://upload.apimart.ai/f/image/...png"], "expires_at": 1763174708 }] },
+    "created": 1763088289,
+    "completed": 1763088308,
+    "estimated_time": 60,
+    "actual_time": 19
+  }
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `status` | `pending` / `processing` / `completed` / `failed` / `cancelled` |
+| `cost` | 本次任务扣费金额（美元） |
+| `credits_cost` | 本次任务扣费积分 |
+| `progress` | 0–100 |
+| `estimated_time` / `actual_time` | 预计 / 实际耗时（秒） |
+| `error` | 仅 `failed` 时存在，含 `code` / `message` / `type` |
+
+**结果字段**：图片在 `data.result.images[]`，视频在 `data.result.videos[]`，音频在 `data.result.audios[]`。
+**注意 `images[].url` 可能是数组**（一次出多张时），解析必须兼容 string 与 string[]。
+
+Midjourney 有一套额外的 MJ 风格状态（`NOT_START` / `SUBMITTED` / `IN_PROGRESS` / `MODAL` / `SUCCESS` / `FAILURE`），其中 `MODAL` 是合法的非终态。
+
+### 3.3 Webhook（可替代轮询）
+
+提交时在 body 里加 `webhook` 字段（**基础地址**，服务端会自动拼 `/callback`）：
+
+| 你填的 `webhook` | 实际 POST 到 |
+|---|---|
+| `https://your-server.com` | `https://your-server.com/callback` |
+| `https://your-server.com/api` | `https://your-server.com/api/callback` |
+
+- 推送内容与 `GET /v1/tasks/{id}` 完全一致，可复用同一套解析
+- 只在终态（`completed` / `failed`）推送，处理中不推
+- 未在 ~10 秒内返回 `2xx` 或返回 `5xx` → 自动重试 **3 次**，间隔约 10s / 30s / 60s；返回 `4xx` 直接放弃
+- 极端情况可能重复推送，**必须按 `id` 做幂等去重**
+- 地址要求：公网可访问（内网地址被拒）、标准端口（80/443）、不能指向 APIMart 自己的域名
+
+> 桌面端没有公网回调地址，本项目用轮询，不使用 Webhook。这里记录是为了说明 `webhook` 字段存在且**不应注册为用户可见参数**。
+
+## 4. 上传文件
+
+`POST /v1/uploads/images`，`multipart/form-data`，字段名 `file`。
+
+| 项目 | 值 |
+|---|---|
+| 支持格式 | JPEG / PNG / WebP / GIF |
+| 最大体积 | 20 MB |
+| 有效期 | **72 小时** |
+| 返回 | `{ "url", "filename", "content_type", "bytes", "created_at" }` |
+| 返回 URL 形态 | `https://upload.apimart.ai/f/image/<id>-<uuid>-<name>.jpg` |
+
+```bash
+curl -X POST https://api.apimart.ai/v1/uploads/images \
+  -H "Authorization: Bearer $APIMART_KEY" \
+  -F 'file=@/path/to/image.jpg'
+```
+
+错误：`400` 缺文件字段 / 格式不支持，`413` 超过 20 MB，`429` 频率限制，`500` 上传失败。
+
+**⚠️ 文档明确写了重要变更**：「为了更好的性能和成本控制，我们不再支持在生成接口中直接传入 base64 图片数据。请使用本接口上传图片，获取 URL 后再调用生成接口。」
+
+本项目已在公共媒体预处理层接入该接口（见第 9 节）：本地图片和 data URI 图片会先上传，再把公网 URL 交给生成接口。
+
+**没有通用的视频/音频上传接口**：只有 Suno、Flow Music 等模型自带的专用上传端点。视频类输入只能传公网 URL。
+
+## 5. 获取结果
+
+- 结果 URL 由 `upload.<域名>` 提供，公开可访问，无需鉴权
+- 有效期由 `result.images[].expires_at`（Unix 时间戳）给出，多数模型 24 小时，Seedream 5.0 系列 72 小时
+- 无二次签名接口，**必须在有效期内转存**
+
+## 6. 计价查询
+
+| 方式 | 位置 | 说明 |
+|---|---|---|
+| 定价中心（权威） | https://apimart.ai/zh/pricing | 公开无需登录，图片/视频模型价格以此为准 |
+| 任务返回值 | `data.cost`（美元）、`data.credits_cost`（积分） | **实际扣费**，最可信 |
+| 文档正文价格 | 各模型 API 文档页 | **经常过期**，与定价中心冲突时以定价中心为准（例：Seedream 5.0 Pro 文档写 $0.045/$0.09，定价中心是 $0.02928/$0.05856） |
+| 定价 API | `GET /api/pricing/model` | **仅文本模型**，图片/视频用不上 |
+
+Nano Banana 2 / Lite / Pro 在同一产品模型内各有「常规 EXT」与「官方」两条渠道，路由和 body schema 相同，以 `model` 精确 ID 区分；前者按张、后者按 token。SDK 以第一顺位 `role: 'channel'` 参数表达，默认常规渠道以保持 0.1.5 兼容，估价必须随渠道同步切换。
+
+## 7. 余额查询
+
+两个端点，返回结构几乎一致：
+
+```bash
+curl https://api.apimart.ai/v1/balance      -H "Authorization: Bearer $KEY"   # 令牌维度
+curl https://api.apimart.ai/v1/user/balance -H "Authorization: Bearer $KEY"   # 用户维度
+```
+
+```json
+{ "success": true, "remain_balance": 10.5, "remain_credits": 105,
+  "used_balance": 2.3, "used_credits": 23, "unlimited_quota": false }
+```
+
+- 无限额度令牌：`unlimited_quota: true`，且 `remain_balance` / `remain_credits` 返回 `-1`
+- 失败时仍返回 HTTP 200，靠 `success: false` + `message` 判断
+- 余额单位取决于系统配置（USD 或积分）
+
+## 8. 错误码
+
+| HTTP | 含义 | 处理 |
+|---|---|---|
+| 400 | 请求参数错误 | 不重试，修参数 |
+| 401 | 认证失败 | 不重试 |
+| 402 | 余额不足 | 不重试，提示充值 |
+| 403 | 无权限 | 不重试 |
+| 429 | 频率限制 | 退避重试 |
+| 500 | 服务器错误 | 退避重试 |
+| 502 | 网关错误 | 退避重试 |
+
+响应体统一为 `{"error": {"code", "message", "type"}}`，`type` 取值如 `invalid_request_error` / `authentication_error` / `payment_required` / `permission_error` / `rate_limit_error` / `server_error` / `bad_gateway`。
+
+## 9. 本项目当前实现与差异
+
+| 项目 | 位置 |
+|---|---|
+| 请求执行 | [src/providers/apimart.ts](../../../src/providers/apimart.ts) |
+| 连接检测 / 余额 | [src/providers/connection.ts](../../../src/providers/connection.ts) → `GET /v1/balance` |
+| 上传改写 | [src/upload/preprocess.ts](../../../src/upload/preprocess.ts) → APIMart 图片走 `uploadToApiMart` |
+| 上传实现 | [src/upload/providers.ts](../../../src/upload/providers.ts) → `POST /v1/uploads/images` |
+| Key / 链接配置 | [src/core/config/providers.ts](../../../../../src/core/config/providers.ts) |
+
+已知差异：
+
+1. Base URL 默认顺序是 `api.apimart.ai` → `api.apib.ai` → `api.aiuxu.com` → `api.aishuch.com`；仅在能证明尚未建立连接的网络故障下受控切换下一个域名，不对已建立连接的失败重放计费请求。不做地理位置判断，改用**连通性探测 + 进程内记忆**：任意一次请求成功命中某个域名后（含应用启动时的后台预热探测），该域名会被记为本次进程运行期间的优先域名，后续请求直接从它开始尝试，其余域名仍留作 fallback；缓存只在内存中，不持久化，应用重启后重新判断。实现见 [src/providers/endpoints/apimart.ts](../../../src/providers/endpoints/apimart.ts)，启动预热调用见 [electron/main/index.ts](../../../../../electron/main/index.ts)（仅在已配置 APIMart Key 时触发，不阻塞启动）
+2. 图片已经接入 `/v1/uploads/images`；APIMart 没有通用视频 / 音频上传端点，公共预处理层会明确拒绝这两类本地文件并提示改用公网 URL，具体模型有专用上传协议时再单独接入
+3. `extractUrls` 已处理 `images[].url` 为数组的情况（`collectDeepUrls` 深挖），无需改
+4. 未使用 Webhook（桌面端合理），不需要改
+
+## 10. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文档总索引（llms.txt） | https://docs.apimart.ai/llms.txt | 否 |
+| 快速开始（Base URL、示例） | https://docs.apimart.ai/cn/quickstart | 否 |
+| 开发指南（轮询、错误码） | https://docs.apimart.ai/cn/development | 否 |
+| 连接与使用问题（端点地址确认） | https://docs.apimart.ai/cn/faqs/connection-usage | 否 |
+| 上传图片 | https://docs.apimart.ai/cn/api-reference/uploads/images | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 任务完成回调（Webhook） | https://docs.apimart.ai/cn/api-reference/tasks/webhook | 否 |
+| 查询令牌余额 | https://docs.apimart.ai/cn/api-reference/account/token-balance | 否 |
+| 查询用户余额 | https://docs.apimart.ai/cn/api-reference/account/user-balance | 否 |
+| 定价中心 | https://apimart.ai/zh/pricing | 否 |
+| **备用访问域名面板**（`apib.ai` / `aiuxu.com` / `aishuch.com`） | https://apimart.ai/zh/login | 否（面板在登录页，但页面本身无需登录即可看到） |
+| API Key 管理 | https://apimart.ai/keys | **是** |
+| 控制台 | https://apimart.ai/overview | **是** |
+
+> 文档站所有页面在 URL 末尾加 `.md` 可直接拿到原始 Markdown，例如 `https://docs.apimart.ai/cn/quickstart.md`。

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

@@ -0,0 +1,172 @@
+# Fal · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 供应商类型 | 模型 API 平台 + Serverless |
+| 项目内 `providerId` | `fal` |
+| 直连 Base URL | `https://fal.run` |
+| 队列 Base URL | `https://queue.fal.run` |
+| 平台 API Base URL | `https://api.fal.ai/v1` |
+| 鉴权 | `Authorization: Key <FAL_KEY>` |
+| 推荐任务模式 | 生产环境使用持久化队列 |
+| 文档/价格可见性 | 公开，无需登录；账户余额和用量需 Key |
+
+## 1. 端点形式
+
+Fal 的 endpoint ID 本身就是路由，例如 `fal-ai/flux/dev`。不要只保存市场展示名。
+
+| 用途 | 方法与 URL |
+|---|---|
+| 直连同步调用 | `POST https://fal.run/<endpoint-id>` |
+| 提交队列 | `POST https://queue.fal.run/<endpoint-id>` |
+| 查询状态 | `GET https://queue.fal.run/<endpoint-id>/requests/<request_id>/status` |
+| 获取结果 | `GET https://queue.fal.run/<endpoint-id>/requests/<request_id>` |
+| 取消 | `PUT https://queue.fal.run/<endpoint-id>/requests/<request_id>/cancel` |
+| 当前价格 | `GET https://api.fal.ai/v1/models/pricing?endpoint_id=...` |
+| 价格预估 | `POST https://api.fal.ai/v1/models/pricing/estimate` |
+| 账户账单/余额 | `GET https://api.fal.ai/v1/account/billing?expand=credits` |
+
+## 2. 队列契约
+
+### 2.1 提交
+
+```bash
+curl -X POST https://queue.fal.run/fal-ai/flux/dev \
+  -H "Authorization: Key $FAL_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"a cat"}'
+```
+
+官方 REST 接口直接发送模型输入对象；JavaScript SDK 的 `{ input: ... }` 是 SDK 调用选项，不能原样作为 HTTP 请求体。Henji-AI provider 已按 REST 契约直接发送 builder 输出。
+
+提交结果：
+
+```json
+{
+  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
+  "response_url": "https://queue.fal.run/.../response",
+  "status_url": "https://queue.fal.run/.../status",
+  "cancel_url": "https://queue.fal.run/.../cancel",
+  "queue_position": 0
+}
+```
+
+保存 `request_id`；也可保存完整 `status_url`，避免续轮询时重建错误路由。SDK 只接受
+`https://queue.fal.run` 同源的 `status_url` / `response_url`，不会把 Fal Key 发送到持久化数据或
+响应中夹带的第三方地址。
+
+### 2.2 状态和结果
+
+| 队列状态 | 含义 |
+|---|---|
+| `IN_QUEUE` | 已持久化，等待 runner |
+| `IN_PROGRESS` | runner 正在处理 |
+| `COMPLETED` | 已终止；需检查 `error` / `error_type`，并获取结果 |
+
+队列状态与 Webhook 状态不同：Webhook 使用 `OK` / `ERROR`。桌面端默认轮询，不要把 Webhook 状态枚举混入轮询解析。
+
+结果结构按模型变化：图片常见 `images[].url`，视频常见 `video.url`，音频常见 `audio_url` 或 `audio.url`。必须以单模型 `llms.txt` 的实时 output schema 为准。
+
+## 3. 文件上传
+
+Fal 模型的通用输入形式是 URL。本地文件推荐先上传到 Fal CDN：
+
+```javascript
+const url = await fal.storage.upload(file)
+```
+
+| 项目 | 说明 |
+|---|---|
+| CDN URL | `https://v3b.fal.media/files/...` |
+| 大文件 | SDK 自动 multipart；JS 通常 90 MB 以上进入分片 |
+| 文件类型 | 上传层不限制，具体模型会限制格式和大小 |
+| 私有 URL | 需自带 Authorization 的 URL 不能直接作模型输入；改用预签名 URL 或 Fal CDN |
+| Data URI | 部分模型接受，但不是全平台通用契约，不适合较大文件 |
+
+SDK 使用与官方客户端相同的单文件 REST 协议：先向
+`POST https://rest.fal.ai/storage/upload/initiate?storage_type=fal-cdn-v3` 发送
+`content_type` / `file_name`，再把原始编码字节以原 MIME `PUT` 到响应中的签名 `upload_url`，最终返回
+`file_url`。两段网络都通过 `RuntimeContext.transport`，共享取消信号与 120 秒 deadline；不调用全局
+`fetch`，不构造 `File`。当前仍未设置 `X-Fal-Object-Lifecycle`，保持既有账户级保留策略。
+
+Fal CDN URL 无需鉴权即可访问。文件保留期由每次上传的 lifecycle 或账户 media expiration 设置控制；账户未配置时可能长期保留。当前生产 `uploadToFal` 没有显式传 lifecycle，依赖账户设置。需要长期保存的输入/输出要及时转存，敏感媒体不能把公开 CDN URL 当成私有存储。
+
+## 4. 计价查询
+
+Fal 是五家中价格 API 最完整的一家。
+
+### 4.1 当前单价
+
+```bash
+curl "https://api.fal.ai/v1/models/pricing?endpoint_id=fal-ai/flux/dev" \
+  -H "Authorization: Key $FAL_KEY"
+```
+
+返回 `prices[]`，关键字段为 `endpoint_id`、`unit_price`、币种和 billing unit。同一账户的专属折扣可反映在查询结果中。
+
+### 4.2 成本预估
+
+`POST /v1/models/pricing/estimate` 支持两种模式：
+
+- `historical_api_price`：根据账户过往调用的历史单次成本预估。
+- `unit_price`：按当前单价 × 预期 billing units 预估。
+
+静态模型定义里的价格用于首屏快速显示；接入前必须再核对单模型 `https://fal.ai/models/<endpoint-id>/llms.txt` 或价格 API。
+
+## 5. 余额与对账
+
+```bash
+curl "https://api.fal.ai/v1/account/billing?expand=credits" \
+  -H "Authorization: Key $FAL_ADMIN_KEY"
+```
+
+返回 `credits.current_balance` 和币种。注意该端点需要 **Admin API Key**，不应假设普通模型调用 Key 一定具有账单权限。
+
+更细对账可使用 `/v1/models/usage` 和 `/v1/models/billing-events`，其中 billing event 可按 `request_id` 查看实际 billing unit、折扣与 `cost_total`。
+
+## 6. 项目当前实现
+
+| 能力 | 状态 | 说明 |
+|---|---|---|
+| `fal.run` 直连 | 已接入 | 模型请求体含 `sync_mode: true` 时使用；该本地路由标记不下发给模型 |
+| `queue.fal.run` 队列 | 已接入 | 默认生成路径；模型级 `sync_mode: false` 会保留下发，供 Pixelcut 等端点强制返回 CDN URL |
+| 状态与结果 | 已接入 | 支持同源 `status_url` 和按 endpoint/request ID 重建；跨域状态/结果 URL 会在请求前拒绝 |
+| 结果 URL 解析 | 已接入 | 递归收集模型结果中的 URL |
+| 本地文件 | Electron 真实 E2E + Transport fixture 已通过 | 119 字节 PNG 的 Range 回读与本地 SHA-256 一致；当前实现使用 REST initiate + signed PUT，并经 `RuntimeContext.transport` 覆盖成功、initiate失败、PUT失败与取消。UXP 真机网络仍由插件集成验证 |
+| 价格/余额 API | 尚未用于连接检测 | 文档已记录；余额需 Admin Key，优先级低 |
+| 自定义图片尺寸 | 已接入 | Seedream 5 Pro/Lite、Qwen Image 3、GPT Image 2、Z-Image 可显式选择约 1MP 的 16 对齐对象；各模型默认仍保持 0.1.5 语义，Lite 低于官方面积下限时由 Fal 自动放大 |
+| 图片放大 | 已接入 | Topaz Precision/Creative/Generative、Topaz Transparent、SeedVR2、Bria Creative、Ideogram；共用 Fal 队列与上传，像素计价统一通过 `pricing.mediaContext` 读取源图尺寸并结合倍率计算，不在节点内复制价格公式 |
+| 图片实用工具 | 已接入 | Image Apps v2 重打光/扩图/商品摄影/照片修复、ControlLight、Pixelcut 背景移除；按需分发，不进入默认模型目录 |
+| 多角度工具 | 已接入 | Qwen Image Edit 2509 Multiple Angles、Image Apps v2 Perspective、FLUX 2 Multiple Angles；受控多结果生成 |
+
+### 6.1 可选图像工具分发集合
+
+`@henjicc/ai-sdk/tool-packs/fal-image-edit-tools` 按需提供 3 个工具端点：
+`fal-ai/flux-pro/v1/erase`、`fal-ai/bria/eraser`、`fal-ai/finegrain-eraser/mask`。
+
+`@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` 按需提供 6 个端点：
+`fal-ai/image-apps-v2/relighting`、`fal-ai/control-light`、`fal-ai/image-apps-v2/outpaint`、
+`fal-ai/image-apps-v2/product-photography`、`fal-ai/image-apps-v2/photo-restoration`、
+`pixelcut/background-removal`。
+
+`@henjicc/ai-sdk/tool-packs/fal-multi-angle-tools` 提供 3 个多角度端点：
+`fal-ai/qwen-image-edit-2509-lora-gallery/multiple-angles`、`fal-ai/image-apps-v2/perspective`、
+`fal-ai/flux-2-lora-gallery/multiple-angles`。
+
+三个 pack 都复用本文件的队列、结果解析和 Fal CDN 上传，不进入默认 105 模型目录，也不进入普通 Fal provider pack。它们只是静态分发集合，执行仍走同一生成客户端。完整字段与价格见对应单模型文档。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| Agent 文档总索引 | https://fal.ai/llms.txt | 否 |
+| 调用方式总览 | https://fal.ai/docs/documentation/model-apis/inference | 否 |
+| 队列提交/查询/结果 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| Fal CDN | https://fal.ai/docs/documentation/model-apis/fal-cdn | 否 |
+| 数据保留与公开访问 | https://fal.ai/docs/documentation/model-apis/media-expiration | 否 |
+| 计价说明 | https://fal.ai/docs/documentation/model-apis/pricing | 否 |
+| 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否 |
+| 成本预估 API | https://fal.ai/docs/platform-apis/v1/models/pricing/estimate | 否 |
+| 账户余额 | https://fal.ai/docs/platform-apis/v1/account/billing | 否（调用需 Admin Key） |
+| API Key | https://fal.ai/dashboard/keys | 是 |

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

@@ -0,0 +1,121 @@
+# Groq · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 供应商 | GroqCloud（与 xAI Grok 无关） |
+| 建议 `providerId` | `groq` |
+| Base URL | `https://api.groq.com/openai/v1` |
+| 鉴权 | `Authorization: Bearer <GROQ_API_KEY>` |
+| 公开能力 | OpenAI 兼容 LLM；同步文件语音转写/英文翻译 |
+| 当前 Say-It 默认模型 | `openai/gpt-oss-20b` |
+| 文档/价格可见性 | 公开，无需登录；API Key、用量和账单需登录 |
+
+## 1. ASR 协议
+
+Groq Speech-to-Text 使用 OpenAI 形状的同步 HTTP 接口：
+
+```text
+POST https://api.groq.com/openai/v1/audio/transcriptions
+POST https://api.groq.com/openai/v1/audio/translations
+Authorization: Bearer <GROQ_API_KEY>
+Content-Type: multipart/form-data
+```
+
+`/audio/transcriptions` 输出原语言转写；`/audio/translations` 将音频翻译为英文，仅
+`whisper-large-v3` 支持，`whisper-large-v3-turbo` 不支持翻译端点。公开 ASR 文档未提供
+WebSocket、SSE 或边传边识别协议；SDK 应按一次请求、一次响应建模。
+
+| 字段 | 要求与官方限制 |
+|---|---|
+| `file` | 与 `url` 二选一；音频文件 |
+| `url` | 与 `file` 二选一；支持普通 URL 和 Base64URL |
+| `model` | 必填；当前两个生产模型见下表 |
+| `language` | 可选 ISO-639-1 语言码；翻译端点目标语言为英文 |
+| `prompt` | 可选，最多 224 tokens |
+| `response_format` | `json` / `verbose_json` / `text`，默认 `json` |
+| `temperature` | `0..1`，默认且官方建议 `0` |
+| `timestamp_granularities[]` | `segment` / `word` / 两者；参数表要求 `verbose_json` |
+
+官方 Speech-to-Text 页存在一处内部冲突：字段表明确说时间戳需
+`response_format=verbose_json`，Python 示例注释却写成需 `json`。适配应以字段表和实际
+API 验证为准，不把该示例注释当成稳定契约。
+
+## 2. ASR 模型、价格与公开限流
+
+| 模型 ID | 转写 | 英文翻译 | 公开价格 | 官方参考速度 | 官方参考 WER | Free Plan | Developer Plan |
+|---|---:|---:|---:|---:|---:|---|---|
+| `whisper-large-v3-turbo` | 是 | 否 | `$0.04 / hour` | 216x real-time | 12% | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD | 400K ASH / 400 RPM |
+| `whisper-large-v3` | 是 | 是 | `$0.111 / hour` | 189x real-time | 10.3% | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD | 200K ASH / 300 RPM |
+
+ASH/ASD 分别是每小时/每日可处理的音频秒数。上表 Free Plan 是当前公开的持续性
+免费计划基线，不是一次性试用金；实际组织额度可不同，官方要求以登录后 Limits 页为准。
+速度和 WER 是官方的模型比较指标，不是对任意网络、语言或音频的延迟/准确率承诺。
+
+## 3. ASR 文件、响应与限制
+
+- 当前公开限制为 Free Tier 最大 25 MB、Developer Tier 最大 100 MB；附件上传最大
+  25 MB，更大输入可走 `url`。Groq Models 表对 `whisper-large-v3` 另列 100 MB，但对
+  Turbo 的单模型文件大小单元格为 `-`；不应把 100 MB 硬编码为 Turbo 的永久模型属性。
+- 支持 `flac/mp3/mp4/mpeg/mpga/m4a/ogg/wav/webm`；多音轨文件只识别第一条音轨。
+- 音频最短 0.01 秒，但每次最少按 10 秒计费。服务端会下采样为 16 kHz 单声道。
+- 长音频官方建议分块；分块边界、上下文提示和结果拼接需由客户端负责。
+- `json` 最小响应包含 `text`；`verbose_json` 可包含 segment/word 时间戳与段级统计。
+
+## 4. ASR 错误与接入复杂度
+
+Groq 通用错误体为 `{ error: { message, type } }`。常见状态包括 400/401/403/404/413/422/429，
+Flex 容量不足为 498，调用方取消为 499，服务端错误为 500/502/503；官方明确服务端
+错误不计费。429 可读 `retry-after`，所有响应带 rate-limit 响应头。
+
+Say-It/SDK 接入属于低复杂度：标准 Bearer Key + `multipart/form-data` JSON/text 响应，无 HMAC、
+无二进制私有帧。客户端仍需负责文件大小校验、长音频分块、`AbortSignal` 下沉和 429/5xx
+的受控重试。中国大陆网络可达性、支付方式和 SLA 未在官方文档承诺，本轮也未发起真实请求。
+
+## 5. OpenAI 兼容 LLM 协议
+
+Groq 支持 OpenAI 兼容 Chat Completions：
+
+```text
+POST https://api.groq.com/openai/v1/chat/completions
+GET  https://api.groq.com/openai/v1/models
+GET  https://api.groq.com/openai/v1/models/{model}
+```
+
+Chat 请求必填 `model` / `messages`，支持 SSE `stream`、tools、`response_format`、
+`max_completion_tokens`、`temperature`、`top_p`、`stop`、`seed`。`n` 只能为 1。
+`logprobs/logit_bias/top_logprobs/messages[].name` 不支持，传入会返回 400。
+
+`GET /models` 需 Bearer Key，返回 `object=list` 与 `data[]`；单项包含
+`id/object/created/owned_by/active/context_window/public_apps`，单模型查询还可返回
+`max_completion_tokens`。动态发现应过滤 `active !== false`，同时保留手动模型 ID 路径。
+
+## 6. GPT-OSS 推理参数与价格
+
+`openai/gpt-oss-20b` 支持 `reasoning_effort=low|medium|high`，默认 `medium`。官方明确
+GPT-OSS 20B/120B **不支持 `reasoning_format`**；默认在 assistant message 的 `reasoning`
+字段返回推理，可传 `include_reasoning=false` 仅返回答案。`include_reasoning` 与
+`reasoning_format` 互斥。
+
+| 项目 | 值 |
+|---|---|
+| 类型 | Production model |
+| 速度 | 约 1000 tokens/s |
+| 上下文 | 131,072 tokens |
+| 最大输出 | 65,536 tokens |
+| Developer Plan 限流 | 250K TPM / 1K RPM |
+| 输入价格 | $0.075 / 1M tokens |
+| 输出价格 | $0.30 / 1M tokens |
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| ASR 端点、参数、文件限制、模型比较 | https://console.groq.com/docs/speech-to-text | 否 |
+| 可用模型、价格、Developer Plan 限流 | https://console.groq.com/docs/models | 否 |
+| Free Plan 限流 | https://console.groq.com/docs/rate-limits | 否 |
+| 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 | **是** |