@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//346/264/276/346/254/247/344/272/221.md

@@ -0,0 +1,138 @@
+# 派欧云 PPIO · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 供应商类型 | 聚合平台（自建推理集群） |
+| 覆盖模态 | 图片、视频、音频 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 结算币种 | 人民币 ¥ |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.ppio.com/v3`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v3/async/<model-route>`，返回 `{ "task_id": "..." }`
+- **查询**：`GET /v3/async/task-result?task_id=<id>`
+- **状态字段**：`/task/status`，枚举 `TASK_STATUS_QUEUED` / `TASK_STATUS_PROCESSING` / `TASK_STATUS_SUCCEED` / `TASK_STATUS_FAILED`
+- **结果字段**：`images[].image_url` / `videos[].video_url` / `audios[].audio_url`
+- **结果 URL 有效期**：默认 **3600 秒**，必须及时下载持久化
+
+部分音频接口同时提供同步版本（`POST /v3/<route>`，无 `async` 段），直接返回结果不需轮询；本项目统一走异步路由。
+
+### 域名（已切换）
+
+官网与全部文档示例现在使用 `https://api.ppio.com/v3`，`api.ppinfra.com` 在官网已无任何引用。
+
+**已实测**：两个域名对同一路由的响应完全一致（带无效 Key 请求 `/v3/async/kling-v3.0-std-t2v`，两者都返回 `{"code":403,"reason":"INVALID_API_KEY"}`），即旧域名仍在兼容且路由解析正常。代码已切到官方现行域名 `api.ppio.com`。
+
+## 2. 文件上传（重要限制）
+
+**PPIO 没有提供官方文件上传服务。** 本项目的处理方式定义在 `electron/main/services/ai-runtime/ppio-media.ts`，按字段名和路由决定媒体如何进入请求体：
+
+| 模式 | 触发条件 | 行为 |
+|---|---|---|
+| `raw-base64` | 字段名以 `_base64` / `_base64s` 结尾 | 裸 base64 字符串 |
+| `public-url` | 字段名以 `_url` / `_urls` 结尾、**任何视频素材**、`reference_voice` 字段，或命中特定路由白名单 | **必须是公网 HTTP(S) URL** |
+| `data-uri` | 其余情况（默认） | `data:<mime>;base64,<data>` 内联 |
+
+`public-url` 模式下，本项目**借用 KIE 的上传服务**换取公网 URL（`upload.ts` → `uploadForPublicUrl` → `uploadToKie`）。因此：
+
+> **用户如果只配置了 PPIO 的 API Key，没有配置 KIE Key，所有需要公网 URL 的 PPIO 模型都会直接失败**，错误提示为「当前 PPIO 模型字段要求公网 HTTP/HTTPS 媒体 URL。请直接传入公网 URL，或配置 KIE API Key」。
+
+这与项目规则「必须调用当前生成供应商自己的官方文件上传服务」存在张力，属于**已知的、供应商能力缺失导致的例外**，不是实现疏漏。新增 PPIO 模型时若涉及视频或 `_url` 字段，需要在产品侧明确这个前置依赖。
+
+## 3. 实名认证前置条件
+
+部分模型要求**个人或企业实名认证**后才能调用，未认证会直接报错：
+
+- Wan 2.5 Preview（全部路由）
+- MiniMax 声音克隆 `/v3/minimax-voice-cloning`
+
+这类限制在模型文档页以 Warning 形式标注，不体现在 API 错误码文档里。
+
+## 4. 在售模型清单（2026-08-26）
+
+PPIO 的媒体模型规模比其他聚合平台小得多，且**图像侧几乎空白**。
+
+### 图片（仅 2 条路由）
+
+| 模型 | 路由 | 价格 |
+|---|---|---|
+| Qwen-Image 文生图 | `/v3/async/qwen-image-txt2img` | ¥0.145/张 |
+| Qwen-Image 图像编辑 | `/v3/async/qwen-image-edit` | ¥0.145/张 |
+
+初代 20B Qwen-Image，**不是** Qwen Image 3.0。
+
+### 视频
+
+在售：Kling 3.0（7 条路由）、Kling 2.5 Turbo Pro、Wan 2.5 Preview、Wan 2.6、Wan 2.7、MiniMax Hailuo 2.3（含 Fast）、PixVerse V4.5。各自价格见对应模型文档。
+
+### 音频
+
+| 模型 | 路由 | 价格 |
+|---|---|---|
+| MiniMax Speech 2.8 HD | `/v3/[async/]minimax-speech-2.8-hd` | ¥3.5 / 万字符 |
+| MiniMax Speech 2.8 Turbo | `/v3/[async/]minimax-speech-2.8-turbo` | ¥2.0 / 万字符 |
+| MiniMax speech-2.6-hd | 路由未公开 | ¥3.5 / 万字符 |
+| MiniMax speech-2.6-turbo | 路由未公开 | ¥2.0 / 万字符 |
+| MiniMax 声音克隆 | `/v3/minimax-voice-cloning` | ¥9.9 / 音色 |
+| MiniMax 声音设计 | `/v3/minimax-voice-design` | ¥9.9 / 音色 |
+| MiniMax Music | `/v3/minimax-music` | music-2.5/2.5+ ¥1.0/首；music-2.0 ¥0.25/首 |
+| MiniMax Lyrics | `/v3/minimax-music-lyrics` | ¥0.05 / 首 |
+| Fish Audio TTS | 路由未公开 | ¥105 / 百万字符（≈¥1.05/万字符） |
+| Fish Audio Voice Clone | 路由未公开 | ¥0.7 / 音色 |
+
+**speech-2.6 系列与 Fish Audio 两条在定价页有价、说明仍在售，但文档站已不提供 API 参考页，路由无法确认。** PPIO 对所有未知路径统一返回 400，无法靠探测区分路由是否存在。要接入需要实测或联系 PPIO。
+
+MiniMax Speech 的公开商品注册表使用 `(单价 × 字符数 + 999999) / 1000000` 结算表达式，代表每次请求的字符费都**向上取整到人民币分**。声音克隆的试听是一次独立 TTS 计费，同样先向上取整到分，再叠加 ¥9.9 音色费。
+
+> Fish Audio 的 TTS 比 MiniMax Turbo 便宜约一半，声音克隆比 MiniMax 便宜 14 倍。若后续要做成本优化，这是值得优先确认路由的方向。
+
+### 主清单模型的覆盖情况
+
+项目「常用优秀模型清单」共 18 个，**PPIO 只提供其中 1 个**：
+
+| 清单模型 | PPIO |
+|---|---|
+| Kling 3.0 | ✅ 提供，见 [Kling-3.0_派欧云.md](../Kling-3.0/Kling-3.0_派欧云.md) |
+| 其余 17 个 | ❌ 全部没有 |
+
+**Seedream 与 Seedance 曾经上线过后又下架。** `/v3/video/create` 统一视频接口的配置里至今残留 `seedance_v1_pro_t2v`、`seedance_v1_lite_i2v`、`seedance_v1.5_pro_t2v/i2v` 等条目，但它们**不在定价页**，同批残留的还有 `kling2.1_*`、`wan2.2_*`、`minimax_hailuo_02`——这批都是已下架的旧条目。
+
+> **判定规则：以定价页为准，不要以 `/v3/video/create` 配置为准。** 对照证据：`kling2.5_turbo_pro_*` 同样只存在于统一配置、没有独立文档页，但定价页有价——说明定价页确实覆盖统一接口模型，因此 Seedance 在定价页的缺席是真缺席。
+
+## 5. 已适配模型文档索引
+
+| 模型 | 文档 | 是否在主清单 |
+|---|---|---|
+| Kling 3.0 | [Kling-3.0_派欧云.md](../Kling-3.0/Kling-3.0_派欧云.md) | ✅ 是 |
+| MiniMax Hailuo 2.3 | [Hailuo-2.3_派欧云.md](../Hailuo-2.3/Hailuo-2.3_派欧云.md) | 否 |
+| Wan 2.5 Preview | [Wan-2.5-Preview_派欧云.md](../Wan-2.5-Preview/Wan-2.5-Preview_派欧云.md) | 否 |
+| Wan 2.6 | [Wan-2.6_派欧云.md](../Wan-2.6/Wan-2.6_派欧云.md) | 否 |
+| Wan 2.7 | [Wan-2.7_派欧云.md](../Wan-2.7/Wan-2.7_派欧云.md) | 否 |
+| MiniMax Speech | [MiniMax-Speech_派欧云.md](../MiniMax-Speech/MiniMax-Speech_派欧云.md) | 否 |
+
+## 6. 适配要点
+
+- **请求体结构在 Wan 家族内部就不统一**：Wan 2.5 / 2.6 是 `{input: {...}, parameters: {...}}` 嵌套结构，Wan 2.7 是**扁平结构**。同家族不同版本不能共用 builder。
+- **同一模型的 t2v 与 i2v 分辨率字段名不同**：t2v 用 `size`（必须填 `1920*1080` 这类具体像素，不接受档位名或比例），i2v 用 `resolution`（枚举 `480P`/`720P`/`1080P`）。Wan 2.5、2.6、2.7 都是这个规律，极易踩坑。
+- **计价维度差异大**：Wan 2.5 / 2.6 按**视频条数**计费（分辨率 × 时长查表），Wan 2.7 与 Kling 3.0 按**秒**计费。同供应商内不能套用同一套计价模板。
+- **音频开关会改变单价档位**：Kling 3.0 的 `sound` 字段为 `true` 时单价上浮 50%；Wan 2.7 r2v 的 `audio` 字段同样影响费用。计价函数必须读这个字段。
+- 项目默认隐藏的参数（`seed`、负面提示词）：PPIO 多数模型都提供 `seed` 与 `negative_prompt` 字段，按项目约定**不显示、不请求**。
+- `output_format` 按项目约定不显示且不请求。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文档全量索引（llms.txt） | https://ppio.com/docs/llms.txt | 否 |
+| 定价页（图像/视频/音频 tab） | https://ppio.com/pricing | 否 |
+| 模型注册表 API（定价页自身调用） | https://api-server.ppio.com/v1/product/multimodal-model/list?returnSchema=true | 否 |
+| 商品批量价格 API（POST） | https://api-server.ppio.com/v1/product/batch-price | 否 |
+| 统一视频接口配置（23 个 model 取值 + JSON Schema） | https://api.ppio.com/v3/admin/video-unify-api/config | 否 |
+| LLM 更新日志（含历史上下架记录） | https://ppio.com/docs/announcement/changelog-llm.md | 否 |
+| API 鉴权方式 | https://ppio.com/docs/api/authentication | 否 |
+| API 错误码 | https://ppio.com/docs/api/error-codes | 否 |
+| API Key 管理 | https://ppio.com/settings/key-management | **是** |

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/201/253/345/261/261/345/274/225/346/223/216.md

@@ -0,0 +1,173 @@
+# 火山引擎 · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 供应商类型 | 模型原厂/云平台（方舟 + 豆包语音） |
+| 项目内 `providerId` | `volcengine` |
+| 生成 Base URL | `https://ark.cn-beijing.volces.com/api/v3` |
+| 鉴权 | `Authorization: Bearer <ARK_API_KEY>` |
+| 当前项目范围 | Seedream 同步图片生成与编辑；SeedASR 2.0 文件/实时识别 |
+| 文档/价格可见性 | 公开，无需登录；API Key、用量和账单需登录 |
+
+## 1. 服务面与鉴权边界
+
+火山方舟和豆包语音是同一供应商下的不同服务面，端点、资源 ID 和 API Key 头不能混用。
+
+### 1.1 方舟生成
+
+模型运行时的主 Base URL：
+
+```text
+https://ark.cn-beijing.volces.com/api/v3
+```
+
+火山引擎还提供 `https://ark.cn-beijing.volcengineapi.com/` 用于部分 OpenAPI/HMAC 管理接口，不要与 Bearer API Key 的模型生成 Base URL 混用。
+
+```text
+Authorization: Bearer <ARK_API_KEY>
+Content-Type: application/json
+```
+
+### 1.2 豆包语音 SeedASR 2.0
+
+```text
+文件：https://openspeech.bytedance.com/api/v3/auc/bigmodel/{submit|query}
+实时：wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
+
+X-Api-Key: <Speech API Key>
+X-Api-Resource-Id: <SeedASR 2.0 resource id>
+X-Api-Request-Id: <UUID>
+```
+
+P0 只支持新版控制台的单头 `X-Api-Key`，不要求旧版 `X-Api-App-Key + X-Api-Access-Key`。文件资源 ID 为 `volc.seedasr.auc`，实时小时版为 `volc.seedasr.sauc.duration`。`volc.bigasr.*` 是同页列出的 1.0 资源，不可用于 SeedASR 2.0。
+
+## 2. 图片生成
+
+```text
+POST /api/v3/images/generations
+```
+
+当前 Seedream 5.0 Pro/Lite 使用同一个同步端点，通过 body 的 `model` 区分模型。
+
+### 2.1 输入媒体
+
+`image` 接受单个字符串或字符串数组，可使用：
+
+- 服务端可访问的 HTTP/HTTPS URL。
+- `data:image/<format>;base64,<data>` Data URI，格式名需小写。
+
+因此，当前图片生成不需要先接 Files API。如使用 TOS 私有存储，可生成华北2（`cn-beijing`）内网 GET 预签名 URL，但需确保 TOS 与方舟在同一地域。
+
+### 2.2 结果
+
+`response_format` 官方支持：
+
+| 值 | 结果 |
+|---|---|
+| `url` | `data[].url`，链接在生成后 24 小时内有效 |
+| `b64_json` | `data[].b64_json` |
+
+Henji-AI 当前产品约定不向用户暴露 `output_format`，图片模型固定请求 `url` 以进入统一媒体转存链路。
+
+同步成功后不需要轮询。结果中还可出现 `size`、`output_format`、图层位置和层级信息，按具体模型功能解析。
+
+## 3. Files API 的边界
+
+方舟公共 Files API：
+
+```text
+POST /api/v3/files
+GET  /api/v3/files/{file_id}
+GET  /api/v3/files
+DELETE /api/v3/files/{file_id}
+```
+
+上传支持本地二进制 `file`、HTTP/HTTPS `url` 和 `tos://` URI，返回 File ID。默认托管空间单文件不超过 512 MB；使用用户 TOS 时视频可到 2 GB。默认保留 7 天，`expire_at` 可设为 1–30 天。
+
+但官方当前将 File ID 主要用于 Responses API / Chat API 的多模态理解，不是 `images/generations` 的通用输入字段。因此：
+
+- 不把 `/api/v3/files` 盲目接成 Seedream 图片生成的通用上传。
+- 只有某个生成模型的官方文档明确接受 File ID 时，才在该分支使用。
+- 当前图片生成保持公网 URL/Data URI 方案。
+
+## 4. 视频等异步生成
+
+方舟的视频生成与图片同步接口不是同一个运行契约。接入 Seedance 或其他视频模型前，必须单独核对当前官方文档的提交端点、任务 ID、查询端点、终态和 `usage.completion_tokens`。不复用图片 provider 的“同步必定完成”假设。
+
+## 5. SeedASR 2.0
+
+| 能力 | SDK `modelId` | 端点/协议 | P0 输入 |
+|---|---|---|---|
+| 录音文件识别 | `seedasr-2.0-file` | HTTP submit/query | HTTP(S) 远端 URL；`raw/wav/mp3/ogg` |
+| 双向实时识别 | `seedasr-2.0-realtime` | 二进制 WebSocket | PCM S16LE、16 kHz、16 bit、mono |
+
+### 5.1 文件 submit/query
+
+提交 UUID 同时是 `X-Api-Request-Id` 和后续查询任务 ID；提交成功 body 为空，必须读取 `X-Api-Status-Code`。查询的 `20000001/20000002` 是处理中/排队，`20000000` 才是成功终态；`result.text`、`result.utterances` 和 `audio_info.duration` 归一到统一 ASR 输出。没有官方 P0 取消端点，用户取消只中止本地查询链。
+
+### 5.2 实时二进制协议
+
+首帧、普通音频和最后音频分别使用 type `1/2/2`；服务端完整响应/错误响应为 type `9/15`。JSON 与 PCM 都按当前官方附件 gzip。SDK 保留最后一块真实音频，`finish()` 以负 sequence 发送；取消只关闭 WebSocket，不伪造正常终帧。服务端 `utterances[].definite=true` 是句段 final，整个会话 terminal 以二进制帧 last 标志为准。
+
+严格字段、状态矩阵、附件差异和 fixture 分类分别见两份模型文档：
+
+- `SeedASR-2.0-File/SeedASR-2.0-File_火山引擎.md`
+- `SeedASR-2.0-Realtime/SeedASR-2.0-Realtime_火山引擎.md`
+
+## 6. 计价
+
+火山方舟价格的权威入口是官方模型价格页，未提供一个使用 ARK API Key 查询所有生成模型实时单价的简单公共 API。
+
+| 类型 | 计费 |
+|---|---|
+| 图片 | 按成功输出数量/像素档位；组图按实际成功张数 |
+| 图层拆分 | 各图层可能按实际像素档分别计费 |
+| 视频 | 常见为 token 单价 × token 用量；用量受时长、尺寸、帧率和是否含输入视频影响 |
+
+准确价格以页面最新表格与实际账单为准。文档 API 的 `Result.UpdatedTime` 可用于判断页面时效。
+
+豆包语音当前公开的 SeedASR 2.0 小时版价格与试用：
+
+| 能力 | 后付费 | 免费试用 | 有效期 |
+|---|---:|---:|---|
+| 文件识别 | 0.8 元/小时 | 20 小时 | 开通后 6 个月 |
+| 实时识别（小时版） | 1 元/小时 | 20 小时 | 开通后 6 个月 |
+
+免费试用需要在豆包语音控制台手动开通，不是每月刷新。实时并发版使用另一资源 ID 和计费方式，不能套用小时版价格。
+
+## 7. 余额与用量
+
+方舟有用量统计和 `GetInferenceUsage` 等云 OpenAPI，但这些管理面接口常需火山引擎 AccessKey/SecretKey 签名，不是生成 Bearer API Key 的同一权限。当前不为低优先级余额查询引入云账号高权限。
+
+## 8. 项目当前实现
+
+| 能力 | 状态 | 说明 |
+|---|---|---|
+| Seedream 同步生成 | 已接入 | `providers/volcengine.ts` |
+| 多 URL 结果解析 | 已接入 | 递归收集 `data[]` 等结构 |
+| 本地图片 | 已接入 | 按官方契约转 Data URI |
+| Files API | 不作为图片生成公共上传 | 避免将理解 API 的 File ID 误发给生成 API |
+| 视频异步生成 | 未接入 | 待确定具体方舟视频模型时按官方契约实现 |
+| SeedASR 2.0 文件识别 | 已接入 SDK P0 | 仅远端 URL；submit/query；新版 `X-Api-Key` |
+| SeedASR 2.0 实时识别 | 已接入 SDK P0 | 二进制 WS；固定 PCM S16LE 16 kHz mono |
+| 余额查询 | 暂缓 | 需云账号级签名与权限 |
+
+## 9. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| Base URL 与鉴权 | https://www.volcengine.com/docs/82379/1298459 | 否 |
+| 图片生成 API | https://www.volcengine.com/docs/82379/1541523 | 否 |
+| 模型价格 | https://www.volcengine.com/docs/82379/1544106 | 否 |
+| Files API 教程 | https://www.volcengine.com/docs/82379/1885708 | 否 |
+| 上传文件 API | https://www.volcengine.com/docs/82379/1870405 | 否 |
+| TOS 内网预签名 URL | https://www.volcengine.com/docs/82379/2551760 | 否 |
+| SeedASR 2.0 文件 API | https://docs.volcengine.com/docs/6561/1354868?lang=zh | 否 |
+| SeedASR 2.0 流式 API/二进制协议 | https://docs.volcengine.com/docs/6561/1354869?lang=zh | 否 |
+| 双向流式优化示例/附件 | https://docs.volcengine.com/docs/6561/2630027?lang=zh | 否 |
+| 豆包语音计费与试用 | https://docs.volcengine.com/docs/6561/1359369?lang=zh | 否 |
+| API Key | https://console.volcengine.com/ark/region:cn-beijing/apiKey | 是 |
+| 豆包语音控制台 | https://console.volcengine.com/speech/new/overview | 是 |
+
+> 火山文档页是 SPA。需要机器可读源文时，可使用官方内容接口：`https://docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=<id>&type=online`。

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/231/276/347/202/274.md

@@ -0,0 +1,227 @@
+# 阿里云百炼 · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 供应商类型 | 模型原厂/云平台（Alibaba Cloud Model Studio） |
+| 项目内 `providerId` | `bailian` |
+| 鉴权 | `Authorization: Bearer <DashScope API Key>` |
+| 本次资料范围 | 图片生成/编辑、在线 ASR（实时/短音频/文件）、Qwen-MT 文本翻译 |
+| 文档/价格可见性 | 公开，无需登录；API Key、空间和账单需登录 |
+
+## 1. Base URL 和区域
+
+百炼的 API Key、业务空间和 Base URL 有区域绑定，不能混用。
+
+| 区域 | 推荐 DashScope Base URL | 历史公共地址 |
+|---|---|---|
+| 华北2（北京） | `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1` | `https://dashscope.aliyuncs.com/api/v1` |
+| 新加坡 | `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1` | `https://dashscope-intl.aliyuncs.com/api/v1` |
+| 美国（弗吉尼亚） | `https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1` | 按当前官方地域文档 |
+
+`WorkspaceId` 需从百炼控制台的业务空间详情获取。官方目前仍保证历史地址可用，但推荐迁移到空间专属域名以获得更稳定的访问。
+
+实时 WebSocket 同样受地域约束：
+
+```text
+Fun-ASR-Realtime: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
+Qwen3-ASR-Realtime: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_id>
+```
+
+新加坡使用 `{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com`。API Key、Workspace、地域必须一致。
+
+## 2. 生成端点
+
+### 2.1 同步多模态生成（当前项目使用）
+
+```text
+POST /api/v1/services/aigc/multimodal-generation/generation
+```
+
+该契约适用于当前 Qwen Image 3.0 等同步图片模型。主要结果路径：
+
+```text
+output.choices[].message.content[].image
+```
+
+图片 URL 通常仅保留 **24 小时**，需及时转存。
+
+### 2.2 异步生成（按模型支持）
+
+百炼的异步接口并非所有模型共用同一个提交路由。以历史 Qwen Image 异步文生图为例：
+
+```text
+POST /api/v1/services/aigc/text2image/image-synthesis
+X-DashScope-Async: enable
+```
+
+查询任务：
+
+```text
+GET /api/v1/tasks/{task_id}
+```
+
+通用状态包括 `PENDING`、`RUNNING`、`SUCCEEDED`、`FAILED`、`CANCELED`、`UNKNOWN`。但每个模型是否支持异步、提交路由与结果结构必须查询单模型文档，不得仅因为供应商有 tasks API 就强行切换。
+
+## 3. 上传本地文件
+
+百炼提供免费临时存储，用于将本地图片、视频或音频转为 `oss://` 地址。
+
+### 3.1 获取上传凭证
+
+```text
+GET https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=<model-name>
+Authorization: Bearer <API Key>
+```
+
+返回 `data.upload_host`、`upload_dir`、`policy`、`signature`、`oss_access_key_id`、`x_oss_object_acl`、`x_oss_forbid_overwrite` 等字段。凭证通常只在 `expire_in_seconds` 内有效。
+
+### 3.2 上传到 OSS
+
+`POST {data.upload_host}`，multipart 字段包含：
+
+- `OSSAccessKeyId`
+- `Signature`
+- `policy`
+- `x-oss-object-acl`
+- `x-oss-forbid-overwrite`
+- `key`
+- `success_action_status=200`
+- `file`（必须放在最后）
+
+生成给模型使用的地址：`oss://<upload_dir>/<filename>`。
+
+### 3.3 使用临时 URL
+
+- 调用模型时必须加 `X-DashScope-OssResourceResolve: enable`。
+- 文件有效期 **48 小时**。
+- 上传时必须指定后续调用的精确模型名，不同模型不能共享该文件。
+- 上传和生成使用的 API Key 必须属于同一阿里云主账号。
+- 单文件上传接口上限 1 GB，具体模型通常有更低的输入限制。
+- 临时存储不用于生产长期托管，高并发建议使用自有 OSS。
+
+## 4. 在线 ASR 三类协议
+
+### 4.1 Fun-ASR-Realtime WebSocket
+
+1. 建立 WSS，握手头带 `Authorization: Bearer <API Key>`。
+2. 发 `run-task`（客户端生成 UUID `task_id`）。
+3. 等 `task-started` 后发单声道二进制音频，持续接收 `result-generated`。
+4. 发 `finish-task`，等 `task-finished` 后才可复用连接或关闭。
+5. `task-failed` 后服务端关闭连接，该连接不可复用；完成后 60 秒内无新任务会自动断开。
+
+`result-generated` 同时承载句子生命周期和文本。官方“句子开始结果”为 `sentence_begin=true`、`sentence_end=false`、`text=""`、`words=[]`，应忽略空文本并继续等待；`sentence_end=true` 才是必须带文本的最终结果。`task-finished.payload` 通常为空，只表示任务结束。实现必须保留此前累计的 final，并在任务全程没有有效 final 时明确报无有效转写。
+
+音频格式 `pcm/wav/mp3/opus/speex/aac/amr`，采样率任意，时长无限制；输入必须单声道。
+
+### 4.2 Qwen3-ASR-Flash-Realtime WebSocket
+
+该系列不复用 `run-task` 协议，而是会话事件：`session.created` → `session.update` → 多个 `input_audio_buffer.append` →（Manual 模式发 `input_audio_buffer.commit`）→ `session.finish` → `session.finished`。
+
+- VAD 模式由服务端断句；Manual 模式由客户端 `commit`。
+- 最终文本为 `conversation.item.input_audio_transcription.completed`，中间文本为 `.text`，失败为 `.failed` / `error`。
+- 推完音频必须先发 `session.finish` 并等 `session.finished`，直接断开会丢弃未完成结果。每次会话后主动断开，不支持连接复用。
+- `pcm/opus`，8kHz/16kHz，单声道；单个 `append` 的 Base64 `audio` 最大 15 MiB，实时使用应分小块。
+
+### 4.3 短音频同步 HTTP
+
+| 系列 | 端点 | 输入 | 上限 | 结果 |
+|---|---|---|---|---|
+| `fun-asr-flash-2026-06-15` | `POST /api/v1/services/aigc/multimodal-generation/generation` | `input.messages[].content[].input_audio.data` 为公网 URL 或 Data URI | 5 分钟 / 2 GB | `output.text` / `output.sentence` + `usage.duration` |
+| `qwen3-asr-flash*` | OpenAI 兼容 `POST /compatible-mode/v1/chat/completions`；或上述 DashScope 同步端点 | URL 或 Base64；OpenAI 兼容额外参数放 `asr_options` | 5 分钟 / 10 MB | OpenAI `choices[].message.content`；DashScope `output.choices[]` |
+
+`fun-asr-flash` 协议支持 `X-DashScope-SSE: enable`；音频不少于 1 分钟时才会多次返回中间结果。
+
+### 4.4 文件异步 HTTP
+
+```text
+POST /api/v1/services/audio/asr/transcription
+X-DashScope-Async: enable
+GET  /api/v1/tasks/{task_id}
+```
+
+- `fun-asr` 提交 `input.file_urls` （单次 1 个公网 URL）；`qwen3-asr-flash-filetrans` 提交 `input.file_url`。
+- 两者上限均为 12 小时 / 2 GB；说话人分离场景建议不超过 2 小时。
+- 状态：`PENDING/RUNNING/SUCCEEDED/FAILED/UNKNOWN`。`fun-asr` 成功结果在 `output.results[].transcription_url`，需再下载 JSON；内含 `transcript/sentences/words/speaker_id`。
+- 异步任务支持查询最近 24 小时提交的任务；必须将转写结果及时落地，不得把签名 URL 当长期资源。
+
+## 5. Qwen-MT 翻译
+
+Qwen-MT 可通过 OpenAI 兼容 `POST /compatible-mode/v1/chat/completions` 或 DashScope `POST /api/v1/services/aigc/text-generation/generation` 调用。请求只支持 User Message，译文在 `choices[0].message.content`。
+
+`translation_options` 必填：
+
+- `source_lang`：源语言英文全称，或 `auto`。
+- `target_lang`：目标语言英文全称。
+- `terms` / `tm_list` / `domains`：可选术语干预、翻译记忆、英文领域提示。
+
+`qwen-mt-flash` / `qwen-mt-lite` 流式返回是增量片段；`qwen-mt-plus` 为累积序列，消费时不能一律字符串追加。
+
+## 6. 计价查询
+
+百炼生成模型没有一个可以用 DashScope API Key 查询全部图片/视频当前单价的稳定公开 API。项目使用以下优先级：
+
+1. 当前官方模型价格页。
+2. 单模型 API 文档中的计费规则。
+3. 调用返回的 `usage`，用于对账输出数量/像素/等效用量。
+4. 最终账单与用量明细。
+
+价格与可用模型都可能按区域不同，文档必须同时记录地域。
+
+本次官方价格页（2026-08-28 读取，北京原价）：
+
+| 模型族 | 输入单价 |
+|---|---|
+| Fun-ASR / Fun-ASR-Flash | 0.00022 元/秒 |
+| Fun-ASR-Realtime | 0.00033 元/秒 |
+| Qwen3-ASR-Flash / Filetrans | 0.00022 元/秒，输出不计费 |
+| Qwen3-ASR-Flash-Realtime | 0.00033 元/秒 |
+| Qwen-MT Plus | 输入 1.8 元/百万 Token，输出 5.4 元/百万 Token |
+| Qwen-MT Flash | 输入 0.7 元/百万 Token，输出 1.95 元/百万 Token |
+| Qwen-MT Lite | 输入 0.6 元/百万 Token，输出 1.6 元/百万 Token |
+
+## 7. 错误边界
+
+- WebSocket 握手时 Key 缺失/无效返回 HTTP 401/403；任务层 Fun-ASR 为 `task-failed`，Qwen3-ASR 为 `error` / `conversation.item.input_audio_transcription.failed`。
+- HTTP 同步错误通常在顶层 `code/message/request_id`；异步还需读 `output.task_status/code/message` 与每个 `results[].subtask_status/code/message`。
+- 需显式分类：模型 ID 不存在/服务未开通（不重试）、Key/空间/地域错配（不重试）、空音频/格式或时长不合法（不重试）、媒体 URL 下载失败（替换输入或上传后重试）、限流/网络/服务端错误（受控退避）。
+- 用户取消要在错误归一前优先识别：WS 停止送音频并关连接，HTTP/SSE 中止 fetch，异步停止轮询；不得转成“网络失败”后自动重试。
+
+## 8. 余额
+
+余额/账单属于阿里云财务体系，通常需要云账号 AccessKey 和 OpenAPI 签名，不是 DashScope 生成 API Key 的同一契约。按当前优先级，Henji-AI 只保存 Key 并标记“未在线验证”，暂不接入云财务权限。
+
+## 9. 项目当前实现
+
+| 能力 | 状态 | 说明 |
+|---|---|---|
+| 同步图片生成 | 已接入 | `providers/bailian.ts` |
+| 图片 URL 解析 | 已接入 | 兼容 `image` / `url` 嵌套字段 |
+| Base URL | 可用但未完整配置化 | 当前固定历史北京地址；未提供 WorkspaceId/区域设置 |
+| 本地文件 | 已支持当前模型 | 当前转 Data URI；接入不支持 Data URI 或大文件模型前，先实现上述 `oss://` 公共上传 |
+| 异步任务 | 未提前造分支 | 当前模型不使用；新异步模型接入时按它的官方路由实现 |
+| 余额查询 | 暂缓 | 避免引入云账号 AK/SK 高权限 |
+| Qwen-MT | **已接入 SDK，待真实请求** | 三模型通过 `capabilities/translation/bailian` 按需导入；已有官方示例 fixture 与精确测试，尚无真实付费请求证据 |
+| ASR | **短音频/文件已接入，实时待后续** | `capabilities/speech-recognition/bailian` 按需导入；实时 WebSocket 由后续独立任务实现，不与翻译模块互相导入 |
+
+## 10. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| 模型与地域总览 | https://help.aliyun.com/zh/model-studio/models | 否 |
+| Qwen Image API（同步/异步、地址、结果） | https://help.aliyun.com/zh/model-studio/qwen-image-api | 否 |
+| 上传文件获取临时 URL | https://help.aliyun.com/zh/model-studio/get-temporary-file-url | 否 |
+| ASR 模型与音频规格 | https://help.aliyun.com/zh/model-studio/asr-model/ | 否 |
+| 实时 ASR 用户指南 | https://help.aliyun.com/zh/model-studio/real-time-speech-recognition-user-guide | 否 |
+| Fun-ASR-Realtime WebSocket 协议 | https://help.aliyun.com/zh/model-studio/fun-asr-realtime-websocket-api | 否 |
+| Fun-ASR-Realtime 客户端/服务端事件 | https://help.aliyun.com/zh/model-studio/fun-asr-client-events ; https://help.aliyun.com/zh/model-studio/fun-asr-server-events | 否 |
+| Qwen-ASR-Realtime 交互/事件 | https://help.aliyun.com/zh/model-studio/qwen-asr-realtime-interaction-process ; https://help.aliyun.com/zh/model-studio/qwen-asr-realtime-client-events ; https://help.aliyun.com/zh/model-studio/qwen-asr-realtime-server-events | 否 |
+| 非实时 ASR 用户指南 | https://help.aliyun.com/zh/model-studio/non-realtime-speech-recognition-user-guide | 否 |
+| Fun-ASR 文件异步 API | https://help.aliyun.com/zh/model-studio/fun-asr-recorded-speech-recognition-http-api | 否 |
+| Fun-ASR-Flash 短音频 API | https://help.aliyun.com/zh/model-studio/non-real-time-speech-recognition-for-fun-asr-flash | 否 |
+| Qwen-ASR 短音频/文件 API | https://help.aliyun.com/zh/model-studio/qwen-asr-api-reference | 否 |
+| Qwen-MT API | https://help.aliyun.com/zh/model-studio/qwen-mt-api | 否 |
+| Qwen-MT 能力页 | https://help.aliyun.com/zh/model-studio/machine-translation | 否（本次访问触发验证码，未取正文） |
+| 官方模型价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| 错误码/区域不匹配 | https://help.aliyun.com/zh/model-studio/developer-reference/error-code | 否 |
+| API Key | https://bailian.console.aliyun.com/?apiKey=1#/api-key | 是 |

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/241/205/345/237/272/346/265/201/345/212/250.md

@@ -0,0 +1,88 @@
+# 硅基流动 · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 供应商 | SiliconFlow / SiliconCloud |
+| 建议 `providerId` | `siliconflow` |
+| Base URL | `https://api.siliconflow.cn/v1` |
+| 鉴权 | `Authorization: Bearer <SILICONFLOW_API_KEY>` |
+| 已核验 ASR 类型 | 同步文件语音转写 API |
+| 文档/价格可见性 | 公开，无需登录；API Key、实名、用量和账单需登录 |
+
+## 1. ASR 端点与请求
+
+```text
+POST https://api.siliconflow.cn/v1/audio/transcriptions
+Authorization: Bearer <SILICONFLOW_API_KEY>
+Content-Type: multipart/form-data
+```
+
+| 字段 | 类型 | 要求 |
+|---|---|---|
+| `file` | binary file | 必填；时长不超过 1 小时，文件不超过 50 MB |
+| `model` | enum string | 必填；`FunAudioLLM/SenseVoiceSmall` 或 `TeleAI/TeleSpeechASR` |
+
+官方端点参考目前只公开了 `file` 和 `model`，没有公开 `language`、`prompt`、
+`response_format`、词级时间戳、说话人分离或热词参数。cURL 使用 MP3 为示例，但页面未给出
+完整 MIME/容器白名单；不应仅根据开源上游模型能力自行扩展公开云 API 参数。
+
+成功响应是 `application/json`：
+
+```json
+{
+  "text": "<string>"
+}
+```
+
+响应头 `x-siliconcloud-trace-id` 是服务端生成的请求追踪标识，可在排障时提供给官方，
+不应当成稳定业务 ID。官方未公开独立 WebSocket、SSE、异步任务或实时麦克风 ASR
+协议；本端点应按同步文件转写建模。
+
+## 2. 模型、价格与免费政策
+
+| 平台模型 ID | API 明确列举 | 当前价格证据 | 结论 |
+|---|---:|---|---|
+| `FunAudioLLM/SenseVoiceSmall` | 是 | 公开价格页语音模型标注“免费” | 自有 Key 调用按当前免费模型政策处理 |
+| `TeleAI/TeleSpeechASR` | 是 | 通用价格页当前未找到该 ID；官方“说点啥”用例将它列入该客户端的免费服务 | **自有 Key 的通用计费未确认**，上线前必须在控制台/账单复核 |
+
+免费模型不是一次性试用金：官方 Rate Limits 页明确说免费模型调用账单消耗为 0，
+同时要求账号完成实名认证。免费模型使用固定 Rate Limits，但公开页未给这两个 ASR
+模型的精确数值；不应把其它模型的 RPM/RPD 直接套用。模型转写页还明确保留定期上下线
+和调整服务能力的权利，因此发布前应再做模型可用性查询。
+
+## 3. 错误契约
+
+官方转写 API 参考和通用错误页表明错误体并非始终同一形状：
+
+- JSON 形状可为 `{ "code": 20012, "message": "...", "data": null }`；
+- 部分鉴权/权限/路由错误在 API 参考中展示为纯字符串；
+- 429 错误示例含 `message` 和 `data`，需从 `message` 区分 RPM/RPD/TPM/TPD/IPM/IPD；
+- 503/504 通常表示服务高负载，500 是未知服务异常。
+
+常见 HTTP 状态：400 参数，401 凭证，403 余额/权限/实名，429 限流，500 未知服务错误，
+503/504 过载。SDK 的 `provider_http_error` 诊断文本需保留 HTTP status、可用的
+`code/message/data`、纯文本 fallback 和脱敏后的 `x-siliconcloud-trace-id`；当前通用
+`AiRuntimeError` 不提供结构化供应商错误 metadata，不可只按一种 JSON 错误结构解析。
+
+## 4. Say-It/SDK 接入边界
+
+接入复杂度低：标准 Bearer Key + `multipart/form-data` + JSON 或文本错误，无 HMAC、无二进制
+私有帧。与 OpenAI/Groq 语音转写形状接近，但当前公开字段仅有 `file/model`，不能把
+OpenAI 的 `language/prompt/response_format/temperature` 透传过来。
+
+中国大陆使用 `api.siliconflow.cn`，需 SiliconCloud 账号与 API Key；免费模型需实名认证。
+本轮没有发起真实或付费请求，运营商网络可达性、账户实际限流和 TeleSpeechASR 自有 Key
+计费均未实测。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 语音转文字 API、模型 enum、输入限制、响应字段 | https://docs.siliconflow.cn/docs/api/audio-transcriptions-post | 否 |
+| 当前公开价格 | https://siliconflow.cn/pricing | 否 |
+| 免费模型、实名与 Rate Limits 规则 | https://docs.siliconflow.cn/cn/userguide/rate-limits/rate-limit-and-upgradation | 否 |
+| 通用错误体与状态说明 | https://docs.siliconflow.cn/cn/faqs/error-code | 否 |
+| TeleSpeechASR/SenseVoiceSmall 客户端免费服务用例 | https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-BiBiKeyboard | 否 |
+| API Key 管理 | https://cloud.siliconflow.cn/account/ak | **是** |
+| 实名认证 | https://cloud.siliconflow.cn/account/authentication | **是** |