@henjicc/ai-sdk 0.2.8 → 0.4.0

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

@@ -1,172 +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 | 是 |
+# Fal · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-09-10 |
+| 供应商类型 | 模型 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-2511-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

@@ -1,121 +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 | **是** |
+# 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 | **是** |