@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/TeleSpeechASR/TeleSpeechASR_/347/241/205/345/237/272/346/265/201/345/212/250.md

@@ -0,0 +1,72 @@
+# TeleSpeechASR · 硅基流动
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 模态 | ASR（同步文件转写） |
+| 供应商 | SiliconFlow / SiliconCloud |
+| 平台模型 ID | `TeleAI/TeleSpeechASR` |
+| 公开计费 | **未确认**：当前通用价格页未列该 ID |
+| 免费证据 | 官方“说点啥”用例将其列入该客户端的免费服务；不足以证明自有 Key 长期免费 |
+| 文档/价格 | 公开无需登录；Key/实名/用量需登录 |
+
+## 1. 端点与鉴权
+
+```text
+POST https://api.siliconflow.cn/v1/audio/transcriptions
+Authorization: Bearer <SILICONFLOW_API_KEY>
+Content-Type: multipart/form-data
+```
+
+请求仅需两个官方公开字段：
+
+```text
+file=<binary audio file>
+model=TeleAI/TeleSpeechASR
+```
+
+`file` 必须不超过 1 小时、50 MB。官方转写端点明确把该 ID 列为 `model` enum，但未公开
+完整文件格式白名单，也未在端点层公开语言清单、热词、说话人、时间戳或其它模型特性。
+公开协议没有 WebSocket/SSE 实时接口。
+
+## 2. 响应契约
+
+```json
+{
+  "text": "<string>"
+}
+```
+
+响应头包含 `x-siliconcloud-trace-id`。在硅基流动当前公开端点中，两个 ASR model enum 共用同一个
+`text` 响应形状；不得凭模型名称猜测额外字段。
+
+## 3. 价格与免费不确定项
+
+- 2026-08-31 公开通用价格页的语音模型栏未找到 `TeleAI/TeleSpeechASR`，因此无法从价格页确认
+  自有 API Key 调用的单价或免费身份。
+- 官方“说点啥”用例把 TeleSpeechASR 与 SenseVoiceSmall 列为该客户端可选的“免费服务”，
+  但同页又将关闭免费服务后的“自己 API Key”作为另一种路径。这不能等价为所有 SiliconCloud
+  账号下长期 0 费用。
+- SDK 可先记录模型可调用，但在未取得控制台账单证据前，价格不应写 0；发布前需用目标账号复核。
+
+## 4. 错误与适配要点
+
+官方错误体可为 `{code,message,data}` JSON，也可为纯文本。常见状态为 400/401/403/429/
+500/503/504。SDK 的 `provider_http_error` 诊断文本保留 HTTP status、可用的
+`code/message/data`、文本 fallback 和脱敏后的 `x-siliconcloud-trace-id`；当前通用
+`AiRuntimeError` 不提供结构化供应商错误 metadata。
+
+Say-It/SDK 接入是简单 Bearer + multipart HTTP，但只能提交 `file/model`；其它 ASR 参数在官方端点
+未公开时应隐藏。中国大陆使用 `api.siliconflow.cn`；本轮未发起真实请求，可用性、限流与
+计费均需目标账号实测。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| ASR API、模型 ID、输入限制与响应 | https://docs.siliconflow.cn/docs/api/audio-transcriptions-post | 否 |
+| 当前通用价格页（该 ID 未列出） | https://siliconflow.cn/pricing | 否 |
+| 免费模型/实名/Rate Limits 规则 | https://docs.siliconflow.cn/cn/userguide/rate-limits/rate-limit-and-upgradation | 否 |
+| 客户端免费服务证据 | https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-BiBiKeyboard | 否 |
+| 错误处理 | https://docs.siliconflow.cn/cn/faqs/error-code | 否 |
+| API Key | https://cloud.siliconflow.cn/account/ak | **是** |

package/docs/model-adaptation/Topaz-/345/233/276/347/211/207/346/224/276/345/244/247/Topaz-/345/233/276/347/211/207/346/224/276/345/244/247_Fal.md

@@ -0,0 +1,87 @@
+# Topaz 图片放大（Fal）
+
+## 定位
+
+- 端点：`topaz/upscale/image/precision`、`topaz/upscale/image/creative`、`topaz/upscale/image/generative`。
+- 类型：单图输入、单图输出的专业放大工具。
+- 产品边界：精确模式偏忠实放大；创意和生成模式会推断或重建细节，界面不得宣传为“无损”。
+- 官方资料核查日期：2026-08-29；文档公开，无需登录，真实调用需要 Fal API Key。
+
+## 公共协议
+
+| 项目 | 契约 |
+|---|---|
+| Base URL | 队列提交 `https://queue.fal.run/<endpoint-id>` |
+| 鉴权 | `Authorization: Key <FAL_KEY>` |
+| 提交 | `POST /<endpoint-id>`，请求体直接发送模型输入对象 |
+| 查询 | `GET /<endpoint-id>/requests/<request_id>/status` |
+| 结果 | `GET /<endpoint-id>/requests/<request_id>` |
+| 取消 | `PUT /<endpoint-id>/requests/<request_id>/cancel` |
+| 状态 | `IN_QUEUE` → `IN_PROGRESS` → `COMPLETED`；完成后仍需检查错误字段 |
+| 输出 | `image: File`，SDK 复用 Fal 通用 URL 提取与下载链路 |
+
+## 模式与字段
+
+| 模式 | 子模型 | 应用开放字段 | 隐藏或固定字段 |
+|---|---|---|---|
+| Precision | Standard V2、High Fidelity V3/V2、Low Resolution V2、CGI、Text Refine | 模型、2×/4×、人脸增强 | `crop_to_fill=false`；不发送 `output_format`、subject detection、sharpen、denoise 等高级字段 |
+| Creative | Bloom 2、Bloom、Bloom Realism | 模型、2×/4×；Bloom 2 额外开放 creativity 1～9 与颜色保留 | Bloom 2 的 autoprompt 使用 Topaz 默认；不发送 `output_format` |
+| Generative | Wonder 3.5/3/2、Wonder、Recover 3、Standard MAX、Recovery V2/Recovery | 模型、2×/4×、人脸增强；Wonder 3/3.5 开放重建强度 | 不发送 `output_format`、seed、prompt；Redefine 因依赖提示词引导而暂不开放 |
+
+应用默认使用 Precision / High Fidelity V3 / 2×，人脸增强默认关闭。启用人脸增强时固定下发
+`face_enhancement_creativity=0` 与 `face_enhancement_strength=0.8`，优先降低人物身份漂移。
+
+## 请求示例
+
+```json
+{
+  "image_url": "https://example.com/source.jpg",
+  "model": "High Fidelity V3",
+  "upscale_factor": 2,
+  "crop_to_fill": false,
+  "face_enhancement": false
+}
+```
+
+Bloom 2 会按需追加：
+
+```json
+{
+  "creativity": 4,
+  "color_preservation": true
+}
+```
+
+## 价格
+
+Fal 以实际输出像素按“每开始一档”计费，应用在上传前根据源图尺寸与倍率计算预计输出 MP：
+
+| 模式/子模型 | 官方单价 |
+|---|---|
+| Precision | 每开始 24 输出 MP `$0.08` |
+| Creative | 每开始 2 输出 MP `$0.08` |
+| Generative · Wonder 3.5 / Wonder 3 | 每开始 8 输出 MP `$0.08` |
+| Generative · 其他已开放子模型 | 每开始 4 输出 MP `$0.08` |
+
+Topaz 主入口在画布侧限制预计输出不超过 48MP，超过时在上传和创建付费任务前阻止。输入文件沿用应用
+20MiB 安全上限。透明图片改用独立的 Topaz Transparent 或 Bria 模型。
+
+## 适配与验证
+
+- SDK canonical ID：`topaz-image-upscale`；应用模型 ID：`fal-ai-topaz-image-upscale`。
+- 模式通过端点选择器路由，不在宿主或画布 UI 里按模型 ID 拼请求。
+- SDK 通过 `pricing.mediaContext` 声明输入/输出 MP 需求；宿主共享价格层读取源图尺寸并结合倍率计算，生成面板与画布共用，不发送给 Fal。画布执行前预检仍会复核同一输出 MP 与 48MP 上限。
+- 媒体指标尚未读取成功时不显示第一档兜底价，避免 2×/4× 被误报为同价。
+- 已完成端点、请求构建、非法参数回落、单图限制和四种计价档位的离线契约测试；未执行真实付费生成。
+
+## 一手资料
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| Precision API | https://fal.ai/models/topaz/upscale/image/precision/api | 否 |
+| Creative API | https://fal.ai/models/topaz/upscale/image/creative/api | 否 |
+| Generative API | https://fal.ai/models/topaz/upscale/image/generative/api | 否 |
+| Precision OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=topaz/upscale/image/precision | 否 |
+| Creative OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=topaz/upscale/image/creative | 否 |
+| Generative OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=topaz/upscale/image/generative | 否 |
+| API Key | https://fal.ai/dashboard/keys | 是 |

package/docs/model-adaptation/Topaz-/351/200/217/346/230/216/345/233/276/346/224/276/345/244/247/Topaz-/351/200/217/346/230/216/345/233/276/346/224/276/345/244/247_Fal.md

@@ -0,0 +1,34 @@
+# Topaz 透明图放大（Fal）
+
+## 契约
+
+| 项目 | 内容 |
+|---|---|
+| endpoint ID | `topaz/upscale/image/transparent` |
+| 输入 | `image_url`，应用严格要求 1 张图片 |
+| 输出 | 固定 4×、固定 PNG，保留 alpha 通道；`image: File` |
+| 参数 | 无用户参数；官方 `output_format` 固定为 PNG，应用不重复下发 |
+| 价格 | 每开始 24 输出 MP `$0.08`，按实际固定 4× 输出尺寸估价 |
+| 资料核查 | 2026-08-29；公开，无需登录 |
+
+## 队列与鉴权
+
+使用 `Authorization: Key <FAL_KEY>` 调用 `https://queue.fal.run`：提交后轮询
+`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，再从结果中的 `image.url` 获取输出；取消使用 endpoint 与
+`request_id` 组成的 `/cancel` 地址。复用 SDK 现有 Fal 上传、轮询、取消和结果解析，不新增协议分支。
+
+## 适配决策
+
+- canonical ID：`topaz-transparent-upscale`；应用模型 ID：`fal-ai-topaz-transparent-upscale`。
+- 该模型独立于 Topaz 主入口，避免把固定 4× 和透明语义伪装成普通倍率选项。
+- `pricing.mediaContext` 声明固定 4× 的输出面积换算，宿主共享价格层读取源图尺寸后按输出 MP 阶梯估价；媒体指标不可用时不显示伪造兜底价。
+- 画布预检允许透明源图，并按相同的 4× 规则复核输出尺寸与价格；输入文件沿用 20MiB 安全上限。
+- 已完成端点、请求体、固定倍率、alpha 预检与像素阶梯计价的离线测试；未执行真实付费生成。
+
+## 一手资料
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| API 文档 | https://fal.ai/models/topaz/upscale/image/transparent/api | 否 |
+| OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=topaz/upscale/image/transparent | 否 |
+| API Key | https://fal.ai/dashboard/keys | 是 |

package/docs/model-adaptation/Wan-2.5-Preview/Wan-2.5-Preview_/346/264/276/346/254/247/344/272/221.md

@@ -0,0 +1,82 @@
+# Wan 2.5 Preview · 派欧云 PPIO
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-26 |
+| 模态 | 视频 |
+| 供应商 | 派欧云 PPIO |
+| 平台路由 | `/v3/async/wan-2.5-t2v-preview`、`/v3/async/wan-2.5-i2v-preview` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 调用前提 | ⚠️ **需要个人或企业实名认证** |
+
+供应商公共协议见 [供应商/派欧云.md](../供应商/派欧云.md)。
+
+## 1. 能力与价格
+
+**按视频条数计费**：
+
+| 分辨率 | 5 秒 | 10 秒 |
+|---|---|---|
+| 480P | ¥1.5 | ¥3 |
+| 720P | ¥3 | ¥6 |
+| 1080P | ¥5 | ¥10 |
+
+文生视频与图生视频同价。
+
+## 2. 请求体结构
+
+嵌套结构 `{ "input": {...}, "parameters": {...} }`。
+
+### `input`
+
+| 变体 | 字段 | 类型 | 必填 | 约束 |
+|---|---|---|---|---|
+| t2v | `prompt` | string | ✅ | ≤ 2000 |
+| | `negative_prompt` | string | | ≤ 500 |
+| | `audio_url` | string | | wav/mp3，3–30 秒，≤15MB |
+| i2v | `img_url` | string | ✅ | JPEG/JPG/PNG（**不支持带透明通道**）/BMP/WEBP；宽高 [360, 2000]px；≤10MB |
+| | `prompt` | string | | ≤ 2000 |
+| | `negative_prompt` | string | | ≤ 500 |
+| | `audio_url` | string | | 同上 |
+
+### `parameters`
+
+| 字段 | 类型 | 默认 | 约束 |
+|---|---|---|---|
+| `size` | string | `1920*1080` | **仅 t2v**；必须填具体像素，不接受档位名或比例 |
+| `resolution` | string | `1080P` | **仅 i2v**；枚举 `480P` / `720P` / `1080P` |
+| `duration` | integer | `5` | 枚举 `5` / `10` |
+| `prompt_extend` | boolean | `true` | |
+| `watermark` | boolean | `false` | |
+| `audio` | boolean | `true` | **优先级：`audio_url` > `audio`** |
+| `seed` | integer | — | `[0, 2147483647]` |
+
+`size` 合法值（13 个，三档）：
+
+- 480P：`832*480` `480*832` `624*624`
+- 720P：`1280*720` `720*1280` `960*960` `1088*832` `832*1088`
+- 1080P：`1920*1080` `1080*1920` `1440*1440` `1632*1248` `1248*1632`
+
+> **官方默认是 1080P**（`size` 默认 `1920*1080`、`resolution` 默认 `1080P`）。项目当前 `wan-2.5-preview.model.ts` 的默认值是 720P（`DEFAULT_WAN25_SIZE='1280*720'`、`DEFAULT_WAN25_RESOLUTION='720P'`），比官方默认低一档。这不是错误，但用户不主动切换时看到的预估价会比官方默认低，需要确认是有意的省钱默认值还是遗漏。
+
+## 3. 上传要求
+
+`img_url` 与 `audio_url` 都以 `_url` 结尾 → 走 **`public-url` 模式**，需要公网 URL，本项目借用 KIE 上传服务。**未配置 KIE API Key 时图生视频不可用。**
+
+## 4. 适配要点
+
+- **实名认证是硬前提**，未认证用户调用会直接失败，且这个限制不体现在错误码文档里。产品侧需要有对应的错误提示引导。
+- t2v 用 `size`（具体像素）、i2v 用 `resolution`（档位名），计价函数需要按当前模式读不同字段再归档。
+- 计价是查表（分辨率 × 时长），不是按秒线性。
+- `audio_url` 存在时会覆盖 `audio` 开关。
+- 项目默认隐藏 `seed` 与负面提示词，按约定**不显示、不请求**。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 | https://ppio.com/docs/models/reference-wan-2.5-t2v-preview | 否 |
+| 图生视频 | https://ppio.com/docs/models/reference-wan-2.5-i2v-preview | 否 |
+| 定价页（视频 tab） | https://ppio.com/pricing | 否 |

package/docs/model-adaptation/Wan-2.6/Wan-2.6_/346/264/276/346/254/247/344/272/221.md

@@ -0,0 +1,84 @@
+# Wan 2.6 · 派欧云 PPIO
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-26 |
+| 模态 | 视频 |
+| 供应商 | 派欧云 PPIO |
+| 平台路由 | `/v3/async/wan2.6-{t2v,i2v,v2v}` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+供应商公共协议见 [供应商/派欧云.md](../供应商/派欧云.md)。
+
+## 1. 能力与价格
+
+**按视频条数计费**（不是按秒），查表如下：
+
+| 变体 | 路由 | 720P | 1080P |
+|---|---|---|---|
+| 文生视频 | `/v3/async/wan2.6-t2v` | 5s ¥3 / 10s ¥6 / 15s ¥9 | 5s ¥5 / 10s ¥10 / 15s ¥15 |
+| 图生视频 | `/v3/async/wan2.6-i2v` | 同上 | 同上 |
+| 参考生视频 | `/v3/async/wan2.6-v2v` | 5s ¥3 / 10s ¥6 | 5s ¥5 / 10s ¥10 |
+
+**v2v 只支持 5s 和 10s，没有 15s 档。**
+
+## 2. 请求体结构
+
+Wan 2.6 是**嵌套结构** `{ "input": {...}, "parameters": {...} }`，与 Wan 2.5 相同，与 Wan 2.7 的扁平结构不同。
+
+### `input`
+
+| 变体 | 字段 | 类型 | 必填 | 约束 |
+|---|---|---|---|---|
+| t2v | `prompt` | string | ✅ | 0–2000 |
+| | `audio_url` | string | | |
+| | `negative_prompt` | string | | 0–500 |
+| i2v | `img_url` | string | ✅ | URL 或 base64 `data:{MIME};base64,{data}`；[360, 2000]px，≤10MB |
+| | `prompt` | string | | 0–2000 |
+| | `template` | string | | 视频特效模板名 |
+| | `audio_url` | string | | |
+| | `negative_prompt` | string | | 0–500 |
+| v2v | `prompt` | string | ✅ | 0–1500，用 `character1` / `character2` 引用角色 |
+| | `reference_urls` | string[] | ✅ | 长度 1–5；图 0–5 张 + 视频 0–3 个，总数 ≤5；视频 1–30 秒 ≤100MB，图 [240, 8000]px ≤20MB |
+| | `negative_prompt` | string | | 0–500 |
+
+### `parameters`
+
+| 字段 | 类型 | 默认 | 约束 |
+|---|---|---|---|
+| `size` | string | `1920*1080` | **仅 t2v 与 v2v**；具体像素值，10 个枚举（720P/1080P 两档） |
+| `resolution` | string | `1080P` | **仅 i2v**；枚举 `720P` / `1080P` |
+| `duration` | integer | `5` | t2v/i2v 枚举 `5/10/15`；**v2v 只有 `5/10`** |
+| `audio` | boolean | `true` | |
+| `shot_type` | string | — | 枚举 `single` / `multi`；**t2v/i2v 默认 `multi`，v2v 默认 `single`** |
+| `prompt_extend` | boolean | `true` | |
+| `watermark` | boolean | `false` | |
+| `seed` | integer | — | `[0, 2147483647]` |
+
+`size` 枚举：720P `1280*720` `720*1280` `960*960` `1088*832` `832*1088`；1080P `1920*1080` `1080*1920` `1440*1440` `1632*1248` `1248*1632`
+
+> **t2v/v2v 用 `size`、i2v 用 `resolution`** 是 Wan 家族的通用规律，三个版本都一样，最容易踩坑的地方。
+
+## 3. 上传要求
+
+`img_url`、`audio_url`、`reference_urls` 都以 `_url` / `_urls` 结尾 → 走 **`public-url` 模式**，需要公网 URL，本项目借用 KIE 上传服务。**未配置 KIE API Key 时图生视频与参考生视频不可用。**
+
+文档同时说明 `img_url` 接受 base64 data URL，但本项目的 `ppio-media.ts` 按字段名后缀判定为 `public-url`，不会走内联路径。
+
+## 4. 适配要点
+
+- `shot_type` 的默认值按变体不同（t2v/i2v 是 `multi`，v2v 是 `single`），不能写成统一默认值。
+- `duration` 合法集合按变体不同（v2v 无 15s），UI 需按当前模式过滤选项。
+- 计价是查表（分辨率 × 时长），不是线性按秒，与 Wan 2.7 完全不同。
+- 项目默认隐藏 `seed` 与负面提示词，按约定**不显示、不请求**。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 | https://ppio.com/docs/models/reference-wan2.6-t2v | 否 |
+| 图生视频 | https://ppio.com/docs/models/reference-wan2.6-i2v | 否 |
+| 参考生视频 | https://ppio.com/docs/models/reference-wan2.6-v2v | 否 |
+| 定价页（视频 tab） | https://ppio.com/pricing | 否 |

package/docs/model-adaptation/Wan-2.7/Wan-2.7_/346/264/276/346/254/247/344/272/221.md

@@ -0,0 +1,122 @@
+# Wan 2.7 · 派欧云 PPIO
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 视频 |
+| 供应商 | 派欧云 PPIO |
+| 平台路由 | `/v3/async/wan2.7-{t2v,i2v,r2v,videoedit}` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+供应商公共协议见 [供应商/派欧云.md](../供应商/派欧云.md)。
+
+## 1. 能力与价格
+
+| 变体 | 路由 | 价格 |
+|---|---|---|
+| 文生视频 | `/v3/async/wan2.7-t2v` | 720P ¥0.60/秒；1080P ¥1.00/秒 |
+| 图生视频 | `/v3/async/wan2.7-i2v` | 同上 |
+| 参考生视频 | `/v3/async/wan2.7-r2v` | 同上 |
+| 视频编辑 | `/v3/async/wan2.7-videoedit` | 同上 |
+
+**Wan 2.7 全系按秒计费**，与 Wan 2.5 / 2.6 的按视频条数计费不同。输出默认含音频。
+
+## 2. 请求体结构（与 2.5 / 2.6 不同）
+
+Wan 2.7 是**扁平结构**，没有 `{input, parameters}` 嵌套。Wan 2.5 与 2.6 是嵌套结构。**同家族不同版本不能共用 builder。**
+
+### 文生视频 `wan2.7-t2v`
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `prompt` | string | ✅ | — | 0–1500 |
+| `duration` | integer | | `5` | `[2, 15]` |
+| `size` | string | | `1920*1080` | 具体像素值，10 个枚举（720P/1080P 两档） |
+| `audio_url` | string | | — | wav/mp3，3–30 秒，≤15MB；不传则自动生成配乐/音效 |
+| `negative_prompt` | string | | — | 0–500 |
+| `seed` | integer | | — | `[0, 2147483647]` |
+| `watermark` | boolean | | `false` | |
+| `prompt_extend` | boolean | | `true` | |
+
+`size` 枚举：720P `1280*720` `720*1280` `960*960` `1088*832` `832*1088`；1080P `1920*1080` `1080*1920` `1440*1440` `1632*1248` `1248*1632`
+
+### 图生视频 `wan2.7-i2v`
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `image_url` | string | ✅※ | — | 与 `first_clip_url` **二选一至少一个**；[240, 8000]px，宽高比 1:8 ~ 8:1，≤20MB |
+| `first_clip_url` | string | ※ | — | 视频续写用，mp4/mov 2–10 秒，[240, 4096]px，≤100MB |
+| `last_frame_url` | string | | — | 尾帧 |
+| `driving_audio_url` | string | | — | 驱动音频，2–30 秒 ≤15MB，做口型同步 |
+| `prompt` | string | | — | 0–**5000**（比 t2v 宽松得多） |
+| `duration` | integer | | `5` | `[2, 15]` |
+| `resolution` | string | | `1080P` | `720P` / `1080P` |
+| `negative_prompt` | string | | — | 0–500 |
+| `seed` / `watermark` / `prompt_extend` | | | | 同 t2v |
+
+**注意 i2v 用 `resolution` 而不是 `size`**，这是 Wan 家族的通用规律（t2v 用具体像素的 `size`，i2v 用档位名的 `resolution`）。
+
+### 参考生视频 `wan2.7-r2v`
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `media` | **object[]** | ✅ | — | 长度 1–5，见下 |
+| `prompt` | string | ✅ | — | 0–1500，用 `character1` / `character2` 引用角色 |
+| `duration` | integer | | `5` | `[2, 10]` |
+| `size` | string | | `1920*1080` | 同 t2v |
+| `audio` | boolean | | `true` | **影响费用** |
+| `shot_type` | string | | `single` | `single` / `multi` |
+| `negative_prompt` / `seed` / `watermark` | | | | |
+
+`media` 每一项：
+
+```json
+{
+  "url": "...",
+  "type": "reference_image | reference_video | first_frame",
+  "reference_voice": "可选，音色克隆音频 MP3/WAV/FLAC 3-30s"
+}
+```
+
+数量约束：图片 0–5 个、视频 0–3 个、**总数 ≤ 5**。
+
+### 视频编辑 `wan2.7-videoedit`
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `video_url` | string | ✅ | — | mp4/mov，2–10 秒，[240, 4096]px，≤100MB |
+| `prompt` | string | | — | 0–5000，编辑指令 |
+| `duration` | integer | | `0` | **`0` = 沿用原视频时长**；范围 `[0, 10]`。此时估价读取宿主探测出的输入视频真实时长。 |
+| `resolution` | string | | `1080P` | `720P` / `1080P` |
+| `ratio` | string | | — | `16:9` / `9:16` / `1:1` / `4:3` / `3:4`；不传则近似原比例 |
+| `audio_setting` | string | | `auto` | `auto` / `origin` |
+| `reference_image_url` / `_2` / `_3` | string | | — | 最多 3 张，[240, 8000]px ≤20MB |
+| `negative_prompt` / `seed` / `watermark` / `prompt_extend` | | | | |
+
+## 3. 上传要求
+
+本模型几乎所有媒体字段都以 `_url` 结尾（`image_url`、`video_url`、`audio_url`、`first_clip_url`、`last_frame_url`、`driving_audio_url`、`reference_image_url`），r2v 的 `media[].url` 与 `media[].reference_voice` 也在白名单里 → **全部走 `public-url` 模式**，需要公网 URL。
+
+本项目借用 KIE 上传服务实现，因此 **Wan 2.7 的全部图生/参考生/视频编辑能力都依赖用户配置 KIE API Key**，只配 PPIO Key 会直接失败。这是 Wan 2.7 相比其他 PPIO 模型最重的前置依赖。
+
+`upload.ts` 里有针对 `/async/wan2.7-r2v` 的专门预处理（`preprocessPpioWan27ReferenceMediaObject`），按 `media[].type` 判断素材类型再上传。
+
+## 4. 适配要点
+
+- 四个变体的参数集合差异很大（`media` 数组 vs 扁平 URL 字段、`duration` 上限 15/10/10、`size` vs `resolution` vs `ratio`），建议用显式 `mode` 参数而不是自动路由。
+- `prompt` 长度上限在四个变体里是 1500 / 5000 / 1500 / 5000，不统一。
+- r2v 的 `audio` 字段影响费用，必须接入计价。
+- `videoedit` 的 `duration=0` 是有意义的默认值（沿用原时长），不能当成「未设置」处理。SDK 估价优先读取 `__videoDurationSeconds`，其次读取 `__totalVideoDurationSeconds`，并兼容旧字段 `__firstVideoDurationSeconds`；这些仅是运行时计价字段，不进入供应商请求。视频元数据不可读时才使用 5 秒兜底估计。
+- 项目默认隐藏 `seed` 与负面提示词，按约定**不显示、不请求**。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 | https://ppio.com/docs/models/reference-wan2.7-t2v | 否 |
+| 图生视频 | https://ppio.com/docs/models/reference-wan2.7-i2v | 否 |
+| 参考生视频 | https://ppio.com/docs/models/reference-wan2.7-r2v | 否 |
+| 视频编辑 | https://ppio.com/docs/models/reference-wan2.7-videoedit | 否 |
+| 定价页（视频 tab） | https://ppio.com/pricing | 否 |

package/docs/model-adaptation/Whisper-Large-v3/Whisper-Large-v3_Groq.md

@@ -0,0 +1,76 @@
+# Whisper Large v3 · Groq
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 模态 | ASR（同步文件转写 / 音频译英文） |
+| 供应商 | GroqCloud |
+| 平台模型 ID | `whisper-large-v3` |
+| 转写端点 | 支持 |
+| 翻译端点 | 支持，输出英文 |
+| 公开价格 | `$0.111 / hour` |
+| 免费政策 | Free Plan 持续性限流额度，不是一次性试用金 |
+| 文档/价格 | 公开无需登录；Key/用量需登录 |
+
+## 1. 端点与鉴权
+
+```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
+```
+
+两个端点都传 `model=whisper-large-v3`，且 `file` / `url` 二选一。`url` 可为普通 URL 或
+Base64URL。`/audio/transcriptions` 返回原语言文本，`/audio/translations` 返回英文翻译；后者
+不是可任意选择目标语言的翻译 API。
+
+可选字段包括 `language`（ISO-639-1）、`prompt`（最多 224 tokens）、
+`response_format=json|verbose_json|text`、`temperature=0..1` 和
+`timestamp_granularities[]=segment|word`。官方未公开独立 WebSocket/SSE 实时 ASR，请求是同步
+HTTP 文件处理。
+
+## 2. 响应与时间戳
+
+- `json` 最小结果包含 `text`；`text` 格式返回纯文本。
+- `verbose_json` 可返回段/词时间戳和段级统计。
+- 官方参数表要求时间戳使用 `verbose_json`，但 Python 示例注释误写为 `json`；适配
+  应以参数表和真实 API 验证为准。
+
+## 3. 文件限制
+
+- Free Tier 最大 25 MB，Developer Tier 最大 100 MB；附件上传最大 25 MB，超过时可使用
+  `url`。Groq Models 表对本模型也明确列 100 MB 最大文件。
+- 支持 `flac/mp3/mp4/mpeg/mpga/m4a/ogg/wav/webm`；多音轨文件只处理第一条音轨。
+- 最短 0.01 秒，每次最少按 10 秒计费；服务端下采样为 16 kHz 单声道。
+- 长音频需客户端分块并拼接结果。
+
+## 4. 价格、额度与选型
+
+| 项目 | 官方当前值 |
+|---|---|
+| 价格 | `$0.111 / hour` |
+| 参考速度 | 189x real-time |
+| 参考 WER | 10.3% |
+| Free Plan | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD |
+| Developer Plan | 200K ASH / 300 RPM |
+
+官方建议在多语种且对转写错误更敏感时选本模型；Turbo 的单价更低、参考速度更高。
+速度/WER 是官方比较指标，不是 SLA。实际组织限流以登录后 Limits 页为准。
+
+## 5. 错误与适配要点
+
+错误体是 `{error:{message,type}}`。需处理 400/401/403/404/413/422/429、498 容量不足、
+499 调用方取消与 500/502/503。Say-It/SDK 接入属于简单 Bearer + multipart HTTP；应把
+“转写”和“译英文”建模为明确能力，而不是向 Turbo 也暴露一个必然失败的翻译开关。
+中国大陆网络与付款可用性未经官方承诺或本轮实测。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| ASR API、参数与文件限制 | 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 | 否 |
+| 错误码 | https://console.groq.com/docs/errors | 否 |
+| API Key | https://console.groq.com/keys | **是** |

package/docs/model-adaptation/Whisper-Large-v3-Turbo/Whisper-Large-v3-Turbo_Groq.md

@@ -0,0 +1,75 @@
+# Whisper Large v3 Turbo · Groq
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 模态 | ASR（同步文件转写） |
+| 供应商 | GroqCloud |
+| 平台模型 ID | `whisper-large-v3-turbo` |
+| 翻译端点 | **不支持** |
+| 公开价格 | `$0.04 / hour` |
+| 免费政策 | Free Plan 持续性限流额度，不是一次性试用金 |
+| 文档/价格 | 公开无需登录；Key/用量需登录 |
+
+## 1. 端点与鉴权
+
+```text
+POST https://api.groq.com/openai/v1/audio/transcriptions
+Authorization: Bearer <GROQ_API_KEY>
+Content-Type: multipart/form-data
+```
+
+必填 `model=whisper-large-v3-turbo`，且 `file` / `url` 二选一。`url` 可为普通 URL 或
+Base64URL。可选字段包括 `language`（ISO-639-1）、`prompt`（最多 224 tokens）、
+`response_format=json|verbose_json|text`、`temperature=0..1` 和
+`timestamp_granularities[]=segment|word`。
+
+本模型不能调用 `/audio/translations`。官方未公开独立 WebSocket/SSE 实时 ASR，请求是同步
+HTTP 文件转写。
+
+## 2. 响应与时间戳
+
+- `json` 最小结果包含 `text`；`text` 格式返回纯文本。
+- `verbose_json` 可返回段/词时间戳和段级统计。
+- 官方参数表要求时间戳使用 `verbose_json`，但 Python 示例注释误写为 `json`；适配
+  应以参数表和真实 API 验证为准。
+
+## 3. 文件限制
+
+- Free Tier 最大 25 MB，Developer Tier 公开总限制为 100 MB；附件上传最大 25 MB，
+  超过时可使用 `url`。Models 表的 Turbo 单模型文件大小栏为 `-`，100 MB 不应作为
+  Turbo 永久的硬编码常量。
+- 支持 `flac/mp3/mp4/mpeg/mpga/m4a/ogg/wav/webm`；多音轨文件只处理第一条音轨。
+- 最短 0.01 秒，每次最少按 10 秒计费；服务端下采样为 16 kHz 单声道。
+- 长音频需客户端分块并拼接结果。
+
+## 4. 价格、额度与选型
+
+| 项目 | 官方当前值 |
+|---|---|
+| 价格 | `$0.04 / hour` |
+| 参考速度 | 216x real-time |
+| 参考 WER | 12% |
+| Free Plan | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD |
+| Developer Plan | 400K ASH / 400 RPM |
+
+Turbo 是官方建议的多语种性价比选项；如果任务对错词率更敏感或需音频译英文，应选
+`whisper-large-v3`。速度/WER 是官方比较指标，不是 SLA。实际组织限流以登录后
+Limits 页为准。
+
+## 5. 错误与适配要点
+
+错误体是 `{error:{message,type}}`。需处理 400/401/403/404/413/422/429、498 容量不足、
+499 调用方取消与 500/502/503。Say-It/SDK 接入属于简单 Bearer + multipart HTTP，但需在发送前
+按账户等级校验文件大小，传递 `AbortSignal`，并对 429/5xx 执行受控重试。中国大陆网络与
+付款可用性未经官方承诺或本轮实测。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| ASR API、参数与文件限制 | 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 | 否 |
+| 错误码 | https://console.groq.com/docs/errors | 否 |
+| API Key | https://console.groq.com/keys | **是** |