@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/README.md

@@ -0,0 +1,304 @@
+# 模型适配清单（总索引）
+
+本目录是**痕迹AI 的模型适配唯一资料源**。Henji-AI 同时是 `@henjicc/ai-sdk` 的主开发仓库与首发验证宿主；官方调研、实现和完整验证先在这里闭环，发布后消费项目才精确锁版本接入。适配思路已从「挑一个供应商、把它的模型尽量做全」调整为：
+**先定一份常用且优秀的模型清单，再为清单里的每个模型逐一接入所有支持它的供应商。**
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 模型数量 | 生成主清单 19（图片 10 / 视频 9）+ 主清单外存量 12 + SDK 跨项目能力模型 20（ASR 15 / 翻译 3 / LLM 2） |
+| 模型供应商文档数量 | 生成/存量 80 + SDK 跨项目能力 20（另有 Fal 工具 12） |
+| 覆盖供应商 | 火山引擎（官方生成/ASR）、百炼（官方）、硅基流动（官方 ASR）、智谱（官方 LLM）、Groq（官方 LLM/ASR）、APIMart、KIE、Fal、派欧云、魔搭、Grsai |
+
+另有 12 个按能力按需分发的 Fal 图像工具，不进入默认 105 模型兼容目录：
+
+- 消除：[Flux Pro Erase](Flux-Pro-Erase/Flux-Pro-Erase_Fal.md)、[Bria Eraser](Bria-Eraser/Bria-Eraser_Fal.md)、[Finegrain Eraser](Finegrain-Eraser/Finegrain-Eraser_Fal.md)。
+- 图片实用工具：[Image Apps v2 重打光](Image-Apps-v2-重打光/Image-Apps-v2-重打光_Fal.md)、[ControlLight](ControlLight/ControlLight_Fal.md)、[Image Apps v2 扩图](Image-Apps-v2-扩图/Image-Apps-v2-扩图_Fal.md)、[Image Apps v2 商品摄影](Image-Apps-v2-商品摄影/Image-Apps-v2-商品摄影_Fal.md)、[Image Apps v2 照片修复](Image-Apps-v2-照片修复/Image-Apps-v2-照片修复_Fal.md)、[Pixelcut 背景移除](Pixelcut-背景移除/Pixelcut-背景移除_Fal.md)。
+- 多角度：[Qwen Image Edit 2509 多角度](Qwen-Image-Edit-2509-多角度/Qwen-Image-Edit-2509-多角度_Fal.md)、[透视变换](透视变换/透视变换_Fal.md)、[FLUX 2 多角度](FLUX-2-多角度/FLUX-2-多角度_Fal.md)。
+
+工具均复用 Fal 队列、上传与结果解析；它们是独立的按需 SDK 入口，不是新的执行内核。Henji-AI 运行客户端显式装载三个 pack，但普通模型选择器仍固定为 105 个默认模型：六个图片实用工具通过图片能力菜单创建固定模型节点，三个多角度工具由专用多角度节点选择，消除工具保留给后续遮罩能力接入。真实质量、延迟和账单仍待获得付费授权后验证。
+
+## 一、目录结构约定
+
+```
+docs/model-adaptation/
+├── README.md                      # 本文件：总清单 + 索引
+├── 文档采集手册.md                  # 官方调研、事件契约、fixture 与 SDK 首发验证的唯一详细规范
+├── 供应商/                         # 先完成供应商公共协议，再做具体模型
+│   ├── 快速适配供应商.md             # 新供应商的统一核对与落地清单
+│   ├── APIMart.md
+│   ├── KIE.md
+│   ├── Fal.md
+│   ├── Groq.md
+│   ├── 硅基流动.md
+│   ├── 百炼.md
+│   ├── 火山引擎.md
+│   ├── 派欧云.md
+│   └── 魔搭.md
+├── <模型名>/                       # 一个模型一个文件夹
+│   └── <模型名>_<供应商名>.md       # 支持该模型的每个供应商一个文件
+```
+
+- **供应商名**使用项目内统一的显示名：
+  派欧云 / Fal / 魔搭 / KIE / APIMart / 百炼 / 火山引擎 / 硅基流动 / Grsai / Groq（Grsai/Groq 沿用官方品牌拼写）
+- 每个供应商文件都是**自包含**的：接入协议、能力清单、请求参数、响应结构、价格、适配要点、原始链接索引，看完这一份就能完成该供应商的适配
+- 每份文件都标注**信息来源链接**以及**该链接是否需要登录**
+
+### 供应商基础文档
+
+模型适配前先看 [快速适配供应商](供应商/快速适配供应商.md)，确认供应商公共层已经覆盖端点、鉴权、上传、任务查询、结果解析和计价。现有十家基础文档：
+
+- [APIMart](供应商/APIMart.md)：含中国大陆备用线路与图片上传协议
+- [KIE](供应商/KIE.md)：生成任务、文件上传、实际扣费与余额查询
+- [Fal](供应商/Fal.md)：同步 / 队列协议、Fal CDN、官方计价 API
+- [百炼](供应商/百炼.md)：地域端点、临时 OSS 上传与同步 / 异步边界
+- [火山引擎](供应商/火山引擎.md)：方舟图片，以及 SeedASR 2.0 实时/文件两套独立协议与计费
+- [硅基流动](供应商/硅基流动.md)：multipart 文件转写、免费模型与在线文档/历史公告冲突
+- [派欧云](供应商/派欧云.md)：异步任务协议、**无官方上传（借用 KIE）**、实名认证前置、在售清单极小
+- [魔搭](供应商/魔搭.md)：API-Inference 统一接口、**魔粒积分计费**、仅图片、可用性判定方法
+- [Grsai](供应商/Grsai.md)：聚合中转，**同一模型拆多个「渠道」**（`-cl`/`-vip`/`-vt`/`-lite` 等后缀，价差可达 10 倍以上）、无独立上传接口（图片直接 base64/URL 塞进请求体）、双线路连通性探测
+- [Groq](供应商/Groq.md)：OpenAI 兼容 LLM、Whisper 文件转写、动态模型发现、价格/免费层与错误边界
+- [智谱 GLM](../llm-adaptation/供应商/智谱GLM.md)：国内 BigModel / 国际 Z.AI 两个 endpoint profile、OpenAI 兼容 Chat 与供应商级思考约定；模型专属契约仍以本目录模型文件为准
+
+尚未适配的图片工具供应商候选统一记录在[图片工具候选供应商调研](供应商/候选供应商调研-图片工具.md)：当前优先级为 Segmind / WaveSpeedAI（P0）、PiAPI（P1）、Replicate（P2）、Novita AI（P3）；中国内地访问友好性均需真实网络验证，不能仅凭中文站或支付方式下结论。
+
+## 二、通用适配规则
+
+1. **默认绝对不显示的参数**：随机种子 `seed`、负面提示词。
+   即使供应商提供了这两个字段，也**不注册、不下发**。各文件的「适配要点」会逐一标出哪个供应商有这两个字段。
+2. **`output_format` 默认不显示且不请求**，保持供应商默认值。
+3. 价格以**供应商的定价页 / 模型 `llms.txt` / 任务返回的 `cost`** 为准；部分 API 文档正文中的价格已过期，出现不一致时文件内会同时列出两处并说明取舍。
+4. 各供应商同名参数的**默认值、取值集合、字段名经常不一致**（例如 `adaptive` vs `auto`、整数 `5` vs 字符串 `"5"`），必须按供应商分别声明 schema，不要共用常量。
+5. 价格依赖本地媒体像素、时长或文件指标时，由模型在 `pricing.mediaContext` 声明需求，宿主统一读取并注入 calculator；禁止在单个页面或画布节点复制媒体计价逻辑。指标未解析完成时不显示伪造的兜底总价。
+
+## 三、模型清单
+
+### 图片（10）
+
+| 模型 | 火山引擎 | 百炼 | APIMart | KIE | Fal | 派欧云 | 魔搭 | Grsai |
+|---|---|---|---|---|---|---|---|---|
+| [Seedream 5.0 Pro](Seedream-5.0-Pro/) | [✅ 官方](Seedream-5.0-Pro/Seedream-5.0-Pro_火山引擎.md) | — | [✅](Seedream-5.0-Pro/Seedream-5.0-Pro_APIMart.md) | [✅](Seedream-5.0-Pro/Seedream-5.0-Pro_KIE.md) | [✅](Seedream-5.0-Pro/Seedream-5.0-Pro_Fal.md) | ❌ 无 | ❌ 无 | ❌ 无 |
+| [Seedream 5.0 Lite](Seedream-5.0-Lite/) | [✅ 官方](Seedream-5.0-Lite/Seedream-5.0-Lite_火山引擎.md) | — | [✅](Seedream-5.0-Lite/Seedream-5.0-Lite_APIMart.md) | [✅](Seedream-5.0-Lite/Seedream-5.0-Lite_KIE.md) | [✅](Seedream-5.0-Lite/Seedream-5.0-Lite_Fal.md) | ❌ 无 | ❌ 无 | ❌ 无 |
+| [Qwen Image 3.0](Qwen-Image-3.0/) | — | [✅ 官方](Qwen-Image-3.0/Qwen-Image-3.0_百炼.md) | [✅](Qwen-Image-3.0/Qwen-Image-3.0_APIMart.md) | [✅](Qwen-Image-3.0/Qwen-Image-3.0_KIE.md) | [✅](Qwen-Image-3.0/Qwen-Image-3.0_Fal.md) | ❌ 无 | ❌ 无 | ❌ 无 |
+| [Z-Image Turbo](Z-Image-Turbo/) | — | [✅ 官方](Z-Image-Turbo/Z-Image-Turbo_百炼.md) | [✅](Z-Image-Turbo/Z-Image-Turbo_APIMart.md) | [✅](Z-Image-Turbo/Z-Image-Turbo_KIE.md) | [✅](Z-Image-Turbo/Z-Image-Turbo_Fal.md) | ❌ 无 | [✅](Z-Image-Turbo/Z-Image-Turbo_魔搭.md) | ❌ 无 |
+| [GPT-Image-2](GPT-Image-2/) | — | — | [✅](GPT-Image-2/GPT-Image-2_APIMart.md) | [✅](GPT-Image-2/GPT-Image-2_KIE.md) | [✅](GPT-Image-2/GPT-Image-2_Fal.md) | ❌ 无 | ❌ 无 | [✅](GPT-Image-2/GPT-Image-2_Grsai.md) |
+| [IC-Light v2](IC-Light-v2/) | — | — | ❌ 无 | ❌ 无 | [✅](IC-Light-v2/IC-Light-v2_Fal.md) | ❌ 无 | ❌ 无 | ❌ 无 |
+| [Nano Banana 2](Nano-Banana-2/) | — | — | [✅](Nano-Banana-2/Nano-Banana-2_APIMart.md) | [✅](Nano-Banana-2/Nano-Banana-2_KIE.md) | [✅](Nano-Banana-2/Nano-Banana-2_Fal.md) | ❌ 无 | ❌ 无 | [✅](Nano-Banana-2/Nano-Banana-2_Grsai.md) |
+| [Nano Banana 2 Lite](Nano-Banana-2-Lite/) | — | — | [✅](Nano-Banana-2-Lite/Nano-Banana-2-Lite_APIMart.md) | [✅](Nano-Banana-2-Lite/Nano-Banana-2-Lite_KIE.md) | ❌ 无（已探测确认，见 [Fal 文档说明](Nano-Banana-2/Nano-Banana-2_Fal.md)） | ❌ 无 | ❌ 无 | [✅](Nano-Banana-2-Lite/Nano-Banana-2-Lite_Grsai.md) |
+| [Nano Banana Pro](Nano-Banana-Pro/) | — | — | [✅](Nano-Banana-Pro/Nano-Banana-Pro_APIMart.md) | [✅](Nano-Banana-Pro/Nano-Banana-Pro_KIE.md) | [✅](Nano-Banana-Pro/Nano-Banana-Pro_Fal.md) | ❌ 无 | ❌ 无 | [✅](Nano-Banana-Pro/Nano-Banana-Pro_Grsai.md) |
+| [Midjourney](Midjourney/) | — | — | [✅](Midjourney/Midjourney_APIMart.md) | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 |
+| [Grok Imagine 2.0](Grok-Imagine-2.0/) | — | — | [✅](Grok-Imagine-2.0/Grok-Imagine-2.0_APIMart.md) | [✅](Grok-Imagine-2.0/Grok-Imagine-2.0_KIE.md) | [✅](Grok-Imagine-2.0/Grok-Imagine-2.0_Fal.md) | ❌ 无 | ❌ 无 | ❌ 无 |
+
+**Nano Banana 2 Lite 是独立模型，不是 Nano Banana 2 的分辨率/渠道选项**：代码里两者 `canonicalModelId` 不同（`nano-banana-2` vs `nano-banana-2-lite`），`generationModelDescriptions.ts` 也各自维护一条独立描述，APIMart/KIE 均已用独立 `.model.ts` 文件实现，因此本表把它列为单独一行，不再挂在 Nano Banana 2 文档里。
+
+### 视频（9）
+
+| 模型 | APIMart | KIE | Fal | 派欧云 | 魔搭 |
+|---|---|---|---|---|---|
+| [Seedance 2.0](Seedance-2.0/) | [✅](Seedance-2.0/Seedance-2.0_APIMart.md) | [✅](Seedance-2.0/Seedance-2.0_KIE.md) | [✅](Seedance-2.0/Seedance-2.0_Fal.md) | ❌ 已下架 | ❌ 无 |
+| [Seedance 2.0 Fast](Seedance-2.0-Fast/) | [✅](Seedance-2.0-Fast/Seedance-2.0-Fast_APIMart.md) | [✅](Seedance-2.0-Fast/Seedance-2.0-Fast_KIE.md) | [✅](Seedance-2.0-Fast/Seedance-2.0-Fast_Fal.md) | ❌ 已下架 | ❌ 无 |
+| [Seedance 2.0 Mini](Seedance-2.0-Mini/) | [✅](Seedance-2.0-Mini/Seedance-2.0-Mini_APIMart.md) | [✅](Seedance-2.0-Mini/Seedance-2.0-Mini_KIE.md) | [✅](Seedance-2.0-Mini/Seedance-2.0-Mini_Fal.md) | ❌ 已下架 | ❌ 无 |
+| [Seedance 2.5](Seedance-2.5/) | [✅](Seedance-2.5/Seedance-2.5_APIMart.md) | [✅](Seedance-2.5/Seedance-2.5_KIE.md) | [✅](Seedance-2.5/Seedance-2.5_Fal.md) | ❌ 已下架 | ❌ 无 |
+| [MiniMax H3](MiniMax-H3/) | [✅](MiniMax-H3/MiniMax-H3_APIMart.md) | [✅](MiniMax-H3/MiniMax-H3_KIE.md) | [✅](MiniMax-H3/MiniMax-H3_Fal.md) | ❌ 无 | ❌ 无 |
+| [Kling 3.0](Kling-3.0/) | [✅](Kling-3.0/Kling-3.0_APIMart.md) | [✅](Kling-3.0/Kling-3.0_KIE.md) | [✅](Kling-3.0/Kling-3.0_Fal.md) | [✅](Kling-3.0/Kling-3.0_派欧云.md) | ❌ 无 |
+| [Kling 3.0 Turbo](Kling-3.0-Turbo/) | [✅](Kling-3.0-Turbo/Kling-3.0-Turbo_APIMart.md) | [✅](Kling-3.0-Turbo/Kling-3.0-Turbo_KIE.md) | [✅](Kling-3.0-Turbo/Kling-3.0-Turbo_Fal.md) | ❌ 无 | ❌ 无 |
+| [Kling 3.0 Omni](Kling-3.0-Omni/) | [✅](Kling-3.0-Omni/Kling-3.0-Omni_APIMart.md) | [✅](Kling-3.0-Omni/Kling-3.0-Omni_KIE.md) | [✅](Kling-3.0-Omni/Kling-3.0-Omni_Fal.md) | ❌ 无 | ❌ 无 |
+| [Gemini Omni Flash](Gemini-Omni-Flash/) | [✅](Gemini-Omni-Flash/Gemini-Omni-Flash_APIMart.md) | [✅](Gemini-Omni-Flash/Gemini-Omni-Flash_KIE.md) | [✅](Gemini-Omni-Flash/Gemini-Omni-Flash_Fal.md) | ❌ 无 | ❌ 无 |
+
+视频类模型在**火山引擎与百炼上未纳入本清单**：Seedance 系列的官方接口不在本次适配范围，Kling 官方接口按用户要求**仅作参考、暂不适配**（能力地图：https://www.klingai.com/document-api/guides/capability-map/video ）。
+
+Grsai 暂未在此表出现：其站内「Veo API」旧版文档给出了 `veo3.1-fast` 视频模型的端点，但该模型**未出现在 dashboard「模型列表」的定价清单中**，可用性与计价未确认，详见 [Grsai 基础文档 §8](供应商/Grsai.md)。
+
+### 主清单外存量模型（12）
+
+以下模型**不在主清单里**，但已在代码中适配并对用户开放，文档用于维护现有实现。部分模型已有多个供应商入口，未来是否纳入主清单待定。
+
+| 模型 | 模态 | 供应商 | 文档 |
+|---|---|---|---|
+| MiniMax Hailuo 2.3 | 视频 | 派欧云 / KIE / Fal | [派欧云](Hailuo-2.3/Hailuo-2.3_派欧云.md) / [KIE](Hailuo-2.3/Hailuo-2.3_KIE.md) / [Fal](Hailuo-2.3/Hailuo-2.3_Fal.md) |
+| MiniMax Hailuo 02 | 视频 | KIE / Fal | [KIE](Hailuo-02/Hailuo-02_KIE.md) / [Fal](Hailuo-02/Hailuo-02_Fal.md) |
+| Grok Imagine | 图片 | KIE | [KIE](Grok-Imagine/Grok-Imagine_KIE.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) |
+| Topaz 图片放大 | 图片 | Fal | [Topaz-图片放大_Fal.md](Topaz-图片放大/Topaz-图片放大_Fal.md) |
+| Topaz 透明图放大 | 图片 | Fal | [Topaz-透明图放大_Fal.md](Topaz-透明图放大/Topaz-透明图放大_Fal.md) |
+| SeedVR2 图片放大 | 图片 | Fal | [SeedVR2-图片放大_Fal.md](SeedVR2-图片放大/SeedVR2-图片放大_Fal.md) |
+| Bria 创意放大 | 图片 | Fal | [Bria-创意放大_Fal.md](Bria-创意放大/Bria-创意放大_Fal.md) |
+| Ideogram 图片放大 | 图片 | Fal | [Ideogram-图片放大_Fal.md](Ideogram-图片放大/Ideogram-图片放大_Fal.md) |
+
+魔搭侧另有 5 个已适配的开源图像模型（`Qwen/Qwen-Image`、`Qwen/Qwen-Image-Edit-2509`、`black-forest-labs/FLUX.1-Krea-dev`、`MusePublic/majicMIX_realistic`、`MusePublic/14_ckpt_SD_XL`）。它们共用魔搭 API-Inference 的同一套端点与参数，差异只有 model ID、尺寸上限和魔粒档位，因此不单独建文件，统一记在 [供应商/魔搭.md](供应商/魔搭.md) 第 7 节。
+
+### SDK / Say-It 语音识别（15）
+
+以下 15 个模型均有独立 SDK capability descriptor 与按需执行模块；消费应用仍需显式导入和注册，升级包版本不会自动增加界面入口。火山文件版只接受供应商可访问的公网 URL，Say-It 在没有受管上传/TOS 之前不得把它伪装成本地文件入口。
+
+| 模型 | 模式 | 主协议 | 上限 | 文档 |
+|---|---|---|---|---|
+| `fun-asr-realtime-2026-02-28` | 实时 | WebSocket `run-task` | 时长无限制 | [百炼](Fun-ASR-Realtime-2026-02-28/Fun-ASR-Realtime-2026-02-28_百炼.md) |
+| `fun-asr-realtime` | 实时稳定别名 | WebSocket `run-task` | 时长无限制 | [百炼](Fun-ASR-Realtime/Fun-ASR-Realtime_百炼.md) |
+| `qwen3-asr-flash-realtime-2026-02-10` | 实时 | WebSocket session | 时长无限制 | [百炼](Qwen3-ASR-Flash-Realtime-2026-02-10/Qwen3-ASR-Flash-Realtime-2026-02-10_百炼.md) |
+| `qwen3-asr-flash-realtime` | 实时稳定别名 | WebSocket session | 时长无限制 | [百炼](Qwen3-ASR-Flash-Realtime/Qwen3-ASR-Flash-Realtime_百炼.md) |
+| `fun-asr-flash-2026-06-15` | 短音频 | DashScope HTTP/SSE 同步 | 5 分钟 / 2 GB | [百炼](Fun-ASR-Flash-2026-06-15/Fun-ASR-Flash-2026-06-15_百炼.md) |
+| `qwen3-asr-flash` | 短音频稳定别名 | OpenAI 兼容 / DashScope 同步 | 5 分钟 / 10 MB | [百炼](Qwen3-ASR-Flash/Qwen3-ASR-Flash_百炼.md) |
+| `qwen3-asr-flash-2026-02-10` | 短音频快照 | OpenAI 兼容 / DashScope 同步 | 5 分钟 / 10 MB | [百炼](Qwen3-ASR-Flash-2026-02-10/Qwen3-ASR-Flash-2026-02-10_百炼.md) |
+| `fun-asr` | 文件异步 | 提交 + 轮询 + 结果 JSON | 12 小时 / 2 GB | [百炼](Fun-ASR/Fun-ASR_百炼.md) |
+| `qwen3-asr-flash-filetrans` | 文件异步 | 提交 + 轮询 | 12 小时 / 2 GB | [百炼](Qwen3-ASR-Flash-Filetrans/Qwen3-ASR-Flash-Filetrans_百炼.md) |
+| `seedasr-2.0-realtime` | 实时 | 火山二进制 WebSocket | PCM S16LE / 16kHz / mono | [火山引擎](SeedASR-2.0-Realtime/SeedASR-2.0-Realtime_火山引擎.md) |
+| `seedasr-2.0-file` | 文件异步 | HTTP submit + query | 仅公网 URL；本地文件需外部 TOS/受管上传 | [火山引擎](SeedASR-2.0-File/SeedASR-2.0-File_火山引擎.md) |
+| `FunAudioLLM/SenseVoiceSmall` | 文件同步 | multipart HTTP | 1 小时 / 50 MB | [硅基流动](SenseVoiceSmall/SenseVoiceSmall_硅基流动.md) |
+| `TeleAI/TeleSpeechASR` | 文件同步 | multipart HTTP | 1 小时 / 50 MB | [硅基流动](TeleSpeechASR/TeleSpeechASR_硅基流动.md) |
+| `whisper-large-v3-turbo` | 文件同步 | OpenAI-compatible multipart | 免费层 25 MB；Developer 100 MB | [Groq](Whisper-Large-v3-Turbo/Whisper-Large-v3-Turbo_Groq.md) |
+| `whisper-large-v3` | 文件同步 | OpenAI-compatible multipart | 免费层 25 MB；Developer 100 MB | [Groq](Whisper-Large-v3/Whisper-Large-v3_Groq.md) |
+
+### Say-It 翻译（3）
+
+| 模型 | 流式语义 | 北京原价（输入/输出，每百万 Token） | 文档 |
+|---|---|---|---|
+| `qwen-mt-flash` | 增量 | 0.7 / 1.95 元 | [百炼](Qwen-MT-Flash/Qwen-MT-Flash_百炼.md) |
+| `qwen-mt-plus` | 累积序列 | 1.8 / 5.4 元 | [百炼](Qwen-MT-Plus/Qwen-MT-Plus_百炼.md) |
+| `qwen-mt-lite` | 增量 | 0.6 / 1.6 元 | [百炼](Qwen-MT-Lite/Qwen-MT-Lite_百炼.md) |
+
+### SDK LLM（2）
+
+| 模型 | 供应商 | 备注 | 文档 |
+|---|---|---|---|
+| `openai/gpt-oss-20b` | Groq | Say-It 默认；`reasoning_effort=low/medium/high`；不支持 `reasoning_format` | [Groq](GPT-OSS-20B/GPT-OSS-20B_Groq.md) |
+| `glm-5.3-flash` | 智谱 | 原生多模态 Chat 模型；1M 上下文 / 128K 输出；完整能力仍有官方冲突项 | [智谱](GLM-5.3-Flash/GLM-5.3-Flash_智谱.md) |
+
+## 四、平台模型 ID 速查
+
+### 可选工具模型
+
+| 工具 | Fal endpoint ID | SDK 入口 |
+|---|---|---|
+| Flux Pro Erase | `fal-ai/flux-pro/v1/erase` | `tool-models/fal/flux-pro-erase` |
+| Bria Eraser | `fal-ai/bria/eraser` | `tool-models/fal/bria-eraser` |
+| Finegrain Eraser (Mask) | `fal-ai/finegrain-eraser/mask` | `tool-models/fal/finegrain-eraser` |
+| Qwen Image Edit 2509 多角度 | `fal-ai/qwen-image-edit-2509-lora-gallery/multiple-angles` | `@henjicc/ai-sdk/tool-models/fal/qwen-image-edit-2509-multiple-angles` |
+| 透视变换 | `fal-ai/image-apps-v2/perspective` | `@henjicc/ai-sdk/tool-models/fal/perspective-change` |
+| Image Apps v2 重打光 | `fal-ai/image-apps-v2/relighting` | `tool-models/fal/relighting` |
+| ControlLight | `fal-ai/control-light` | `tool-models/fal/control-light` |
+| Image Apps v2 扩图 | `fal-ai/image-apps-v2/outpaint` | `tool-models/fal/outpaint` |
+| Image Apps v2 商品摄影 | `fal-ai/image-apps-v2/product-photography` | `tool-models/fal/product-photography` |
+| Image Apps v2 照片修复 | `fal-ai/image-apps-v2/photo-restoration` | `tool-models/fal/photo-restoration` |
+| Pixelcut 背景移除 | `pixelcut/background-removal` | `tool-models/fal/pixelcut-background-removal` |
+| FLUX 2 多角度 | `fal-ai/flux-2-lora-gallery/multiple-angles` | `tool-models/fal/flux-2-multiple-angles` |
+
+- 3 个消除工具聚合为 `@henjicc/ai-sdk/tool-packs/fal-image-edit-tools`，统一能力画像为 `operation=image-edit`、`feature=erase`。
+- 6 个重打光/修复/扩图/商品/抠图工具聚合为 `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools`，再按单模型画像区分具体能力。
+- Qwen 2509、透视变换和 FLUX 2 聚合为 `@henjicc/ai-sdk/tool-packs/fal-multi-angle-tools`，与消除和实用工具 pack 分开分发。
+
+三个 pack 都只是静态分发集合，执行继续走同一生成客户端和 Fal 公共协议。
+
+| 模型 | APIMart | KIE | Fal |
+|---|---|---|---|
+| Seedream 5.0 Pro | `seedream-5-0-pro` | `seedream/5-pro-text-to-image`、`5-pro-image-to-image`、`5-pro-layer-decomposition` | `bytedance/seedream/v5/pro/{text-to-image,edit}` |
+| Seedream 5.0 Lite | `seedream-5-0-lite` | `seedream/5-lite-text-to-image`、`5-lite-image-to-image` | `bytedance/seedream/v5/lite/{text-to-image,edit}` |
+| Qwen Image 3.0 | `qwen-image-3.0`、`qwen-image-3.0-pro` | `qwen3/{text-to-image,image-to-image}`、`qwen3-pro/text-to-image`、`qwen3/pro-image-to-image` | `alibaba/qwen-image-3/{text-to-image,edit}` |
+| Z-Image Turbo | `z-image-turbo` | `z-image` | `fal-ai/z-image/turbo`、`fal-ai/z-image/turbo/image-to-image`；魔搭 `Tongyi-MAI/Z-Image-Turbo` |
+| GPT-Image-2 | `gpt-image-2`（别名 `gpt-image-2-ext`）、`gpt-image-2-official` | `gpt-image-2-text-to-image`、`gpt-image-2-image-to-image` | `openai/gpt-image-2`、`openai/gpt-image-2/edit` |
+| IC-Light v2 | — | — | `fal-ai/iclight-v2` |
+| Topaz 图片放大 | — | — | `topaz/upscale/image/{precision,creative,generative}` |
+| Topaz 透明图放大 | — | — | `topaz/upscale/image/transparent` |
+| SeedVR2 图片放大 | — | — | `fal-ai/seedvr/upscale/image` |
+| Bria 创意放大 | — | — | `bria/upscale/creative` |
+| Ideogram 图片放大 | — | — | `fal-ai/ideogram/upscale` |
+| Nano Banana 2 | `gemini-3.1-flash-image-preview`(-official) | `nano-banana-2` | `fal-ai/nano-banana-2`、`fal-ai/nano-banana-2/edit` |
+| Nano Banana 2 Lite | `gemini-3.1-flash-lite-image`(-ext) | `nano-banana-2-lite` | ❌ 无（已探测确认） |
+| Nano Banana Pro | `gemini-3-pro-image-preview`(-official) | `nano-banana-pro` | `fal-ai/nano-banana-pro`、`fal-ai/nano-banana-pro/edit` |
+| Midjourney | `midjourney`（Imagine）、`midjourney-blend`、`midjourney-edit`、`midjourney-video`（新路由均自动注入平台模型 ID） | — | — |
+| Grok Imagine 2.0 | `grok-imagine-2.0-ext`、`grok-imagine-image-2.0` | `grok-imagine-image-2-0/{text-to-image,image-edit,segment-map,segment-edit}` | `xai/grok-imagine-image/v2.0/{text-to-image,edit}` |
+| Grok Imagine | — | `grok-imagine/{text-to-image,image-to-image}` | — |
+| Seedance 2.0 | `seedance-2.0` | `bytedance/seedance-2` | `bytedance/seedance-2.0/{text-to-video,image-to-video,reference-to-video}` |
+| Seedance 2.0 Fast | `seedance-2.0-fast` | `bytedance/seedance-2-fast` | `bytedance/seedance-2.0/fast/...` |
+| Seedance 2.0 Mini | `seedance-2.0-mini` | `bytedance/seedance-2-mini` | `bytedance/seedance-2.0/mini/...` |
+| Seedance 2.5 | `seedance-2.5` | `bytedance/seedance-2-5` | `bytedance/seedance-2.5/...` |
+| MiniMax H3 | `MiniMax-H3`、`MiniMax-H3-Context-IR`、`MiniMax-H3-Regeneration` | `minimax-h3/{text-to-video,image-to-video,reference-to-video}` | `minimax/h3/{text-to-video,image-to-video,reference-to-video}` |
+| MiniMax Hailuo 2.3 | — | `hailuo/2-3-image-to-video-{standard,pro}` | `fal-ai/minimax/hailuo-2.3/{standard,pro}/{text-to-video,image-to-video}`、`fal-ai/minimax/hailuo-2.3-fast/{standard,pro}/image-to-video` |
+| MiniMax Hailuo 02 | — | `hailuo/02-{text,image}-to-video-{standard,pro}` | `fal-ai/minimax/hailuo-02/{standard,pro}/{text-to-video,image-to-video}`、`fal-ai/minimax/hailuo-02-fast/image-to-video` |
+| Kling 3.0 | `kling-v3` | `kling-3.0/video` | `fal-ai/kling-video/v3/{pro,standard}/...`；派欧云 `/v3/async/kling-v3.0-{std,pro,4k}-{t2v,i2v}` |
+| Kling 3.0 Turbo | `kling-3.0-turbo` | `kling/v3-turbo-{text,image}-to-video` | `fal-ai/kling-video/v3/turbo/{pro,standard}/...` |
+| Kling 3.0 Omni | `kling-v3-omni` | `kling-3.0-omni/{text-to-video,image-to-video,reference-to-video,transformation}` | `fal-ai/kling-video/o3/{pro,standard}/...` |
+| Gemini Omni Flash | `gemini-omni-flash-preview`、`Omni-Flash-Ext` | `gemini-omni-video` + `/api/v1/omni/audio/create` + `/api/v1/omni/character/create` | `google/gemini-omni-flash/{image-to-video,reference-to-video}` |
+
+Grsai 的平台模型 ID 未并入本表：它把「渠道」直接编码进 `model` 字段（如 `nano-banana-2-cl`、`gpt-image-2-vip`），渠道数量比 APIMart/KIE/Fal 常见的 2 档更多（GPT-Image-2 2 个、Nano Banana 2 主模型 4 个、Nano Banana 2 Lite 1 个、Nano Banana Pro 5 个），完整枚举见对应模型文档：[GPT-Image-2_Grsai.md](GPT-Image-2/GPT-Image-2_Grsai.md)、[Nano-Banana-2_Grsai.md](Nano-Banana-2/Nano-Banana-2_Grsai.md)、[Nano-Banana-2-Lite_Grsai.md](Nano-Banana-2-Lite/Nano-Banana-2-Lite_Grsai.md)、[Nano-Banana-Pro_Grsai.md](Nano-Banana-Pro/Nano-Banana-Pro_Grsai.md)。
+
+## 五、供应商通用协议速查
+
+| 供应商 | Base URL | 鉴权 | 提交 | 查询 | 结果字段 |
+|---|---|---|---|---|---|
+| **火山引擎** | 方舟 `https://ark.cn-beijing.volces.com`；语音 `https://openspeech.bytedance.com` | 方舟 Bearer；语音 `X-Api-Key` + Resource/Request ID | 图片同步；SeedASR 实时 WSS；文件 `POST /api/v3/auc/bigmodel/submit` | 文件 `POST /api/v3/auc/bigmodel/query` | 图片 `data[]`；ASR `result.text/utterances[]` |
+| **百炼** | `https://{WorkspaceId}.<region>.maas.aliyuncs.com` | `Authorization: Bearer sk-xxxx` | 生成/短 ASR/Qwen-MT 为同步 HTTP；实时 ASR 为 `/api-ws/v1/inference` 或 `/api-ws/v1/realtime` WSS；文件 ASR 为 `POST /api/v1/services/audio/asr/transcription` + `X-DashScope-Async: enable` | 异步 `GET /api/v1/tasks/{task_id}` | 按能力分为图像 `content[].image`、转写事件/文本、`transcription_url`、翻译 `choices[].message.content` |
+| **Groq** | `https://api.groq.com/openai/v1` | `Authorization: Bearer <GROQ_API_KEY>` | `POST /chat/completions`（同步/SSE）；`POST /audio/transcriptions`；`GET /models` | — | Chat choices/delta；ASR `text/language/duration/segments/words` |
+| **硅基流动** | `https://api.siliconflow.cn/v1` | `Authorization: Bearer <API Key>` | `POST /audio/transcriptions` multipart | — | `text`；响应头 `x-siliconcloud-trace-id` |
+| **智谱** | 国内 `https://open.bigmodel.cn/api/paas/v4`；国际 `https://api.z.ai/api/paas/v4` | `Authorization: Bearer <API Key>`；两区凭据分离 | `POST /chat/completions`（同步/SSE） | — | `choices[].message.content/reasoning_content/tool_calls`；流式 `choices[].delta` |
+| **APIMart** | `https://api.apimart.ai`；大陆备用线路见[基础文档](供应商/APIMart.md) | `Authorization: Bearer <KEY>` | `POST /v1/images/generations`、`POST /v1/videos/generations` | `GET /v1/tasks/{task_id}` | `result.images[]` / `result.videos[]` |
+| **KIE** | `https://api.kie.ai` | `Authorization: Bearer <KEY>` | `POST /api/v1/jobs/createTask` | `GET /api/v1/jobs/recordInfo?taskId=` | `JSON.parse(resultJson).resultUrls` |
+| **Fal** | `https://fal.run` / `https://queue.fal.run` | `Authorization: Key $FAL_KEY` | `POST https://queue.fal.run/<endpoint-id>` | `GET .../requests/{id}/status`、`GET .../requests/{id}` | `images[]` / `video` |
+| **派欧云** | `https://api.ppio.com/v3`（代码仍用旧域名 `api.ppinfra.com`，待核实） | `Authorization: Bearer <KEY>` | `POST /v3/async/<route>` | `GET /v3/async/task-result?task_id=` | `images[].image_url` / `videos[].video_url` / `audios[].audio_url`（TTL 3600s） |
+| **魔搭** | `https://api-inference.modelscope.cn` | `Authorization: Bearer <TOKEN>` | `POST /v1/images/generations` + 头 `X-ModelScope-Async-Mode: true`（代码写的是 `/api/v1/jobs/createTask`，待核实） | `GET /v1/tasks/{task_id}` + 头 `X-ModelScope-Task-Type: image_generation` | `output_images[]` |
+| **Grsai** | `https://grsaiapi.com`（全球）/ `https://grsai.dakka.com.cn`（国内直连，已接入连通性探测+自动切换） | `Authorization: Bearer <API Key>` | `POST /v1/api/generate`（`replyType` 项目侧统一强制 `async`） | `GET /v1/api/result?id=` | `results[].url` |
+
+任务状态枚举：
+- APIMart：`pending` / `processing` / `completed` / `failed` / `cancelled`（Midjourney 另有 MJ 风格状态 `NOT_START` / `SUBMITTED` / `IN_PROGRESS` / `MODAL` / `SUCCESS` / `FAILURE`）
+- KIE：`waiting` / `queuing` / `generating` / `success` / `fail`
+- Fal：`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`
+- 百炼异步：`PENDING` / `RUNNING` / `SUCCEEDED` / `FAILED` / `CANCELED` / `UNKNOWN`
+- 火山文件 ASR：响应头 `20000002` 排队 / `20000001` 处理中 / `20000000` 成功；`20000003` 静音终态；`45/55*` 失败
+- 派欧云：`TASK_STATUS_QUEUED` / `TASK_STATUS_PROCESSING` / `TASK_STATUS_SUCCEED` / `TASK_STATUS_FAILED`
+- 魔搭：`SUCCEED` / `FAILED`
+- Grsai：`running` / `violation`（违规，独立终态）/ `succeeded` / `failed`
+
+## 六、常用外部入口
+
+| 用途 | 链接 | 是否需登录 |
+|---|---|---|
+| APIMart 文档总索引 | https://docs.apimart.ai/llms.txt | 否 |
+| APIMart 定价中心 | https://apimart.ai/zh/pricing | 否 |
+| KIE 文档总索引 | https://docs.kie.ai/llms.txt | 否 |
+| KIE 定价页 | https://kie.ai/pricing | 否 |
+| Fal 平台总览 | https://fal.ai/llms.txt | 否 |
+| Fal 单模型 schema | `https://fal.ai/models/<endpoint-id>/llms.txt` | 否 |
+| 火山方舟图片生成 API | https://www.volcengine.com/docs/82379/1541523 | 否 |
+| 火山方舟模型价格 | https://www.volcengine.com/docs/82379/1544106 | 否 |
+| 火山 SeedASR 实时 WebSocket | https://docs.volcengine.com/docs/6561/2630027?lang=zh | 否 |
+| 火山 SeedASR 文件 submit/query | https://docs.volcengine.com/docs/6561/1354868?lang=zh | 否 |
+| 火山 SeedASR 价格/免费额度 | https://docs.volcengine.com/docs/6561/1359369?lang=zh | 否 |
+| 百炼模型价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| 百炼 ASR 模型与音频规格 | https://help.aliyun.com/zh/model-studio/asr-model/ | 否 |
+| 百炼 Qwen-MT API | https://help.aliyun.com/zh/model-studio/qwen-mt-api | 否 |
+| Groq 模型/价格 | https://console.groq.com/docs/models | 否 |
+| Groq API 参考 | https://console.groq.com/docs/api-reference | 否 |
+| Groq Reasoning | https://console.groq.com/docs/reasoning | 否 |
+| Groq Speech-to-Text | https://console.groq.com/docs/speech-to-text | 否 |
+| 硅基流动音频转写 API | https://api-docs.siliconflow.cn/docs/api/audio-transcriptions-post | 否 |
+| 硅基流动价格 | https://siliconflow.cn/pricing | 否 |
+| 可灵官方视频能力地图（仅参考） | https://www.klingai.com/document-api/guides/capability-map/video | 否 |
+| 派欧云文档索引 | https://ppio.com/docs/llms.txt | 否 |
+| 派欧云定价页 | https://ppio.com/pricing | 否 |
+| 魔搭 API-Inference 文档 | https://www.modelscope.cn/docs/model-service/API-Inference/intro | 否 |
+| 魔搭魔粒说明 | https://www.modelscope.cn/docs/magicube/intro | 否 |
+| APIMart API Key | https://apimart.ai/keys | **是** |
+| KIE API Key | https://kie.ai/api-key | **是** |
+| Fal API Key | https://fal.ai/dashboard/keys | **是** |
+| 火山方舟 API Key | https://console.volcengine.com/ark/region:cn-beijing/apiKey | **是** |
+| 百炼 API Key | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |
+| Groq API Key | https://console.groq.com/keys | **是** |
+| 硅基流动 API Key | https://cloud.siliconflow.cn/account/ak | **是** |
+| 智谱 GLM-5.3-Flash 模型/API | https://docs.bigmodel.cn/cn/guide/models/vlm/glm-5.3-flash | 否 |
+| 智谱模型价格 | https://open.bigmodel.cn/pricing | 否 |
+| 国际 Z.AI GLM-5.3-Flash | https://docs.z.ai/guides/vlm/glm-5.3-flash | 否 |
+| 国际 Z.AI 模型价格 | https://docs.z.ai/guides/overview/pricing | 否 |
+| Grsai 文档总索引（llms.txt） | https://qmy27nhsd9.apifox.cn/llms.txt | 否 |
+| Grsai dashboard 模型列表（权威价格） | https://grsai.com/zh/dashboard/models | 否 |
+| Grsai dashboard 公告（渠道调价历史） | https://grsai.com/zh/dashboard/announcements | 否 |
+| Grsai API Key | https://grsai.ai/zh/dashboard/api-keys | **是** |
+
+## 七、维护方式
+
+- **动手前**：先读 [文档采集手册.md](文档采集手册.md)——官方来源、流式事件矩阵、fixture/parser 测试闭环和 SDK 首发顺序的详细门槛只维护在这里
+- **新增模型**：在本文件的清单表里加一行 → 建同名文件夹 → 为每个支持它的供应商写一份 `<模型名>_<供应商名>.md`
+- **更新已有模型**：直接改对应的供应商文件，并更新该文件头部的「最后更新」以及本文件的「最后更新」
+- **信息来源要求**：每条参数 / 价格都要能追溯到文件末尾「原始链接索引」中的某个链接；需要登录才能看到的页面必须标注

package/docs/model-adaptation/SeedASR-2.0-File/SeedASR-2.0-File_/347/201/253/345/261/261/345/274/225/346/223/216.md

@@ -0,0 +1,115 @@
+# SeedASR 2.0 File · 火山引擎
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 能力 | 录音文件异步识别（submit/query） |
+| SDK `modelId` | `seedasr-2.0-file` |
+| 火山请求模型 | `request.model_name="bigmodel"` + 2.0 资源 ID `volc.seedasr.auc` |
+| P0 输入 | 供应商可读取的 HTTP(S) 远端 URL |
+| 文档/价格 | 公开；API Key、开通和用量需登录 |
+
+## 1. 端点与新版鉴权
+
+```text
+POST https://openspeech.bytedance.com/api/v3/auc/bigmodel/submit
+POST https://openspeech.bytedance.com/api/v3/auc/bigmodel/query
+```
+
+P0 只实现新版控制台单 Key 鉴权：
+
+```text
+X-Api-Key: <API Key>
+X-Api-Resource-Id: volc.seedasr.auc
+X-Api-Request-Id: <客户端生成的 UUID，也是任务 ID>
+Content-Type: application/json
+```
+
+提交还带 `X-Api-Sequence: -1`。查询沿用同一个 UUID；可把提交响应的 `X-Tt-Logid` 回传到查询头，便于服务定位。旧版 `X-Api-App-Key + X-Api-Access-Key` 没有进入 P0，也不得和 `X-Api-Key` 混发。
+
+文档同页还列出 1.0 的 `volc.bigasr.auc`。本模型是 SeedASR 2.0，不能因为旧附件的默认值仍是 `volc.bigasr.auc` 就降级到 1.0。
+
+## 2. 提交请求
+
+```json
+{
+  "user": { "uid": "<request UUID>" },
+  "audio": {
+    "url": "https://audio.example/meeting.mp3",
+    "format": "mp3",
+    "language": "zh-CN"
+  },
+  "request": {
+    "model_name": "bigmodel",
+    "enable_itn": true,
+    "enable_punc": true,
+    "enable_ddc": false,
+    "show_utterances": true
+  }
+}
+```
+
+| 字段 | P0 行为 |
+|---|---|
+| `audio.url` | 必填，只接受 HTTP(S)；本地 bytes 和 `media-ref` 明确报 `unsupported_media_source` |
+| `audio.format` | 必填；只接受官方标准版枚举 `raw/wav/mp3/ogg`，可由 MIME、文件名或 URL 后缀推断 |
+| `audio.language` | 可选，来自通用输入 `language`；不应误放进 `request` |
+| `request.model_name` | 固定 `bigmodel`；2.0 由资源 ID 区分 |
+| `enable_itn` | 默认 `true` |
+| `enable_punc` | 默认 `true`，受通用 `punctuation` 控制 |
+| `enable_ddc` | P0 默认 `false` |
+| `show_utterances` | 默认 `true`，用于结构化句段/时间戳 |
+
+提交成功时 Response body 为空，结果必须从响应头判断：`X-Api-Status-Code=20000000`、`X-Api-Message`、`X-Tt-Logid`。不能因为 HTTP 200 就假定任务已提交成功。
+
+## 3. 查询状态与结果
+
+查询 body 固定 `{}`。P0 状态矩阵：
+
+| `X-Api-Status-Code` | 分类 | SDK 行为 |
+|---|---|---|
+| `20000000` | 成功终态 | 解析 JSON，发 `final/completed` |
+| `20000001` | 处理中 | 发 `processing`，继续轮询 |
+| `20000002` | 排队中 | 发 `processing`，继续轮询 |
+| `20000003` | 静音终态 | `provider_task_failed`，不伪造空成功 |
+| `45xxxxxx` | 请求/音频错误终态 | `provider_task_failed`，停止轮询 |
+| `55xxxxxx` | 服务端错误终态 | `provider_task_failed`，停止轮询 |
+| 缺少状态头 | 非法响应 | `invalid_response` |
+
+成功 JSON 的稳定读取路径：
+
+```text
+result.text
+result.utterances[].text/start_time/end_time/words[]
+audio_info.duration
+```
+
+SDK 将毫秒字段归一到 `durationMs/segments[].startMs/endMs/words[]`。成功终态却没有非空 `result.text` 时严格报 `invalid_response`。
+
+官方没有为该 submit/query 流程给出 P0 可依赖的远端取消端点。用户取消只中止当前 HTTP/等待和后续轮询，不再发送查询，也不声称已取消服务端任务。
+
+## 4. 价格与免费额度
+
+| 项目 | 官方公开值 |
+|---|---|
+| 后付费 | 0.8 元/小时 |
+| 免费试用 | 20 小时 |
+| 有效期 | 开通后 6 个月 |
+
+20 小时是需要在豆包语音控制台开通的试用额度，不是每月自动刷新。创建应用、开通服务和免费试用均需用户在控制台操作；实际扣费以最新价格页和账单为准。
+
+## 5. Fixture 与验证来源
+
+| Fixture | 分类 | 用途 |
+|---|---|---|
+| `asr-seedasr-field-construction.json` | `field-construction` | 官方未给文件成功字面样例；按字段表构造状态头、成功结果与 SDK 出站请求 |
+| `asr-seedasr-synthetic.json` | `synthetic-negative` | 静音/错误等断牙负例，不冒充真实返回 |
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| SeedASR 2.0 文件 API | https://docs.volcengine.com/docs/6561/1354868?lang=zh | 否 |
+| 文件识别示例/附件 | https://docs.volcengine.com/docs/6561/2628951?lang=zh | 否 |
+| 计费与免费试用 | https://docs.volcengine.com/docs/6561/1359369?lang=zh | 否 |
+| 豆包语音控制台 | https://console.volcengine.com/speech/new/overview | **是** |

package/docs/model-adaptation/SeedASR-2.0-Realtime/SeedASR-2.0-Realtime_/347/201/253/345/261/261/345/274/225/346/223/216.md

@@ -0,0 +1,143 @@
+# SeedASR 2.0 Realtime · 火山引擎
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 能力 | 双向实时语音识别（二进制 WebSocket） |
+| SDK `modelId` | `seedasr-2.0-realtime` |
+| 火山请求模型 | `request.model_name="bigmodel"` + 2.0 资源 ID `volc.seedasr.sauc.duration` |
+| P0 音频 | PCM S16LE、16 kHz、16 bit、单声道 |
+| 文档/价格 | 公开；API Key、开通和用量需登录 |
+
+## 1. 端点与新版鉴权
+
+P0 使用官方双向流式优化端点：
+
+```text
+wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
+```
+
+握手头：
+
+```text
+X-Api-Key: <API Key>
+X-Api-Resource-Id: volc.seedasr.sauc.duration
+X-Api-Request-Id: <客户端生成的 UUID>
+X-Api-Sequence: -1
+```
+
+只支持新版 `X-Api-Key`。同一官方页面同时列出 1.0 的 `volc.bigasr.sauc.*` 与 2.0 的 `volc.seedasr.sauc.*`；本模型固定 2.0 小时版资源 ID。并发版 `volc.seedasr.sauc.concurrent` 属于另一计费形态，不在 P0 中静默切换。
+
+## 2. 首帧与音频规格
+
+首帧 JSON 经 UTF-8 + gzip 后装入二进制帧：
+
+```json
+{
+  "user": { "uid": "<request UUID>" },
+  "audio": {
+    "format": "pcm",
+    "codec": "raw",
+    "rate": 16000,
+    "bits": 16,
+    "channel": 1
+  },
+  "request": {
+    "model_name": "bigmodel",
+    "enable_itn": true,
+    "enable_punc": true,
+    "enable_ddc": false,
+    "show_utterances": true,
+    "enable_nonstream": false,
+    "result_type": "full"
+  }
+}
+```
+
+P0 不在 SDK 内转码：输入不符合 PCM S16LE/16 kHz/mono 时，在建立付费连接前失败。每个 PCM16 音频块的字节数必须为偶数。官方示例建议每 200 ms 一包，即 6400 字节；分块节奏由宿主负责。
+
+`bigmodel_async` 当前契约不发送 `audio.language`；传入 `language` 或热词 `hints` 会明确报不支持，避免静默丢参数。
+
+## 3. 二进制帧契约
+
+### 3.1 4 字节头
+
+| 位置 | 高 4 bit | 低 4 bit |
+|---|---|---|
+| byte 0 | version=`1` | header size=`1`（4 字节） |
+| byte 1 | message type | flags |
+| byte 2 | serialization | compression |
+| byte 3 | reserved | reserved |
+
+消息与标志：
+
+| 值 | 含义 |
+|---|---|
+| message type `1` | client full request |
+| message type `2` | client audio-only request |
+| message type `9` | server full response |
+| message type `15` | server error response |
+| flag bit `1` | 帧含 4 字节大端有符号 sequence |
+| flag bit `2` | 最后一包 |
+| flag bit `4` | 帧含 4 字节大端 event |
+| serialization `0/1` | none / JSON |
+| compression `0/1` | none / gzip |
+
+完整响应布局为 `header → [sequence] → [event] → uint32 payload_size → payload`；错误响应为 `header → [sequence] → [event] → uint32 error_code → uint32 payload_size → payload`。解析器要求声明长度与实际剩余字节完全一致，断牙和尾随字节都报 `invalid_response`。服务端 payload 同时接受 `compression=none/gzip`，其他压缩或序列化值拒绝。
+
+### 3.2 当前官方附件的客户端帧
+
+| 帧 | 头 hex | sequence | payload |
+|---|---|---|---|
+| 首帧 | `11 11 11 00` | `1` | JSON UTF-8 + gzip |
+| 普通音频 | `11 21 11 00` | 正数，从 `2` 递增 | 原始 PCM + gzip |
+| 最后一块真实音频 | `11 23 11 00` | 当前序号取负数 | 原始 PCM + gzip |
+
+协议字段表把原始音频描述为 `serialization=none`，但 2026-08-08 当前官方 Python 附件对音频帧实际写入 `serialization=JSON` 标志（第三字节 `0x11`），附件自带成功 `run.log` 也使用这一结构。P0 以可复现的当前官方附件为准锁定 `0x11`；这是已记录的官方资料内部差异，后续若官方修正文档或附件需重新验证，而不是同时猜两套发送协议。
+
+SDK 对音频保留一块延迟：收到下一块时才把上一块以正 sequence 发出；`finish()` 把最后一块真实音频以负 sequence 发送。不会制造空终止音频包。无任何真实音频就 `finish()` 会报 `invalid_audio`。
+
+## 4. 服务端事件矩阵
+
+| 服务端帧/字段 | Capability 事件 | 终态 | 行为 |
+|---|---|---|---|
+| 首个合法 type `9` full response | `started` | 否 | 官方附件该帧 `result.text=""`；SDK 不要求必须为空，也不产生空 partial |
+| type `9`，非空 `result.text` | `partial` | 否 | 文本变化才发，重复内容去重 |
+| `result.utterances[].definite=true` | `final` | 否 | 表示句段已确定，不等于整个连接结束；按时间范围/文本去重 |
+| flag bit `2`（last） | `completed` | 是 | 只有客户端已 `finish()` 后才合法；输出 `result.text/utterances/audio_info.duration` |
+| type `15` | 无 | 是（错误） | 读取 uint32 错误码；错误 payload 可为 JSON 或安全 UTF-8 文本 |
+| 未知 `event` 数字 | 无 | 否 | 只记脱敏 warning，仍按 type/payload 处理 |
+| WebSocket 提前断开 | 无 | 是（错误） | `provider_connection_closed`，不误报完成 |
+| text WebSocket frame | 无 | 是（错误） | 协议要求二进制，报 `invalid_response` |
+
+`utterances[].definite=true` 只能判断句段 final，整个会话终态必须看帧头 last 标志。整个终帧仍无有效文本时严格报 `invalid_response`。
+
+用户主动取消只关闭连接，不发送负 sequence 终帧，也不把取消伪装成正常完成。full request 默认在 15 秒内必须收到首个服务端响应，可用 `openTimeoutMs` 显式调整；超时会关闭半开连接。`finish()`、连接释放和显式 `close()` 都幂等；发送失败、服务端错误、断线、超时和取消都走同一个释放边界。
+
+## 5. 价格与免费额度
+
+| 项目 | 官方公开值 |
+|---|---|
+| 后付费（小时版） | 1 元/小时 |
+| 免费试用 | 20 小时 |
+| 有效期 | 开通后 6 个月 |
+
+20 小时为需在豆包语音控制台开通的试用额度，不是每月自动刷新。并发版的资源与计费方式不同，不应把本页小时版单价套到并发版。
+
+## 6. Fixture 与验证来源
+
+| Fixture | 分类 | 用途 |
+|---|---|---|
+| `asr-seedasr-official.json` | `official-redacted` | 官方附件成功 `run.log` 的握手/空进度/终帧；仅 `log_id` 脱敏 |
+| `asr-seedasr-field-construction.json` | `field-construction` | 按官方当前附件构造三类客户端帧与首帧字段 |
+| `asr-seedasr-synthetic.json` | `synthetic-negative` | 未知 event、错误码、断牙/尾随字节等负例 |
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| 流式 API/二进制协议 | https://docs.volcengine.com/docs/6561/1354869?lang=zh | 否 |
+| 双向流式优化端点与当前附件 | https://docs.volcengine.com/docs/6561/2630027?lang=zh | 否 |
+| 流式调用示例/资源 ID | https://docs.volcengine.com/docs/6561/2628951?lang=zh | 否 |
+| 计费与免费试用 | https://docs.volcengine.com/docs/6561/1359369?lang=zh | 否 |
+| 豆包语音控制台 | https://console.volcengine.com/speech/new/overview | **是** |

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

@@ -0,0 +1,45 @@
+# SeedVR2 图片放大（Fal）
+
+## 契约
+
+| 项目 | 内容 |
+|---|---|
+| endpoint ID | `fal-ai/seedvr/upscale/image` |
+| 输入 | `image_url`，应用严格要求 1 张图片 |
+| 官方模式 | `factor` 或 `target`；应用只开放 factor 模式 |
+| 应用参数 | 2×/4×、`noise_scale` 0～1（默认 0.1） |
+| 隐藏字段 | `seed`、`output_format`、`sync_mode`、target resolution |
+| 输出 | `image: File` |
+| 价格 | Fal 标价 `$0.001/MP` |
+| 资料核查 | 2026-08-29；公开，无需登录 |
+
+官方价格只标明 megapixels billing unit，没有在公开页明确它指输入还是输出。应用采用“预计输出 MP ×
+$0.001”的保守展示口径，并在价格文案中明确这是估价；SDK 通过 `pricing.mediaContext` 声明源图像素与
+2×/4× 面积倍率，宿主共享价格层统一读取媒体指标。指标未解析成功时不显示伪造兜底价；实际账单仍以
+Fal billing event 为准。
+
+## 请求示例
+
+```json
+{
+  "image_url": "https://example.com/source.jpg",
+  "upscale_mode": "factor",
+  "upscale_factor": 4,
+  "noise_scale": 0.1
+}
+```
+
+## 队列与适配
+
+使用 `Authorization: Key <FAL_KEY>` 调用 `https://queue.fal.run`，状态为 `IN_QUEUE`、
+`IN_PROGRESS`、`COMPLETED`。canonical ID 为 `seedvr2-image-upscale`，应用模型 ID 为
+`fal-ai-seedvr2-image-upscale`。默认 JPG 输出不保证 alpha，因此画布预检会提示透明图改用专用模型。
+已完成端点、字段钳制、单图限制、2×/4×预检和输出 MP 估价的离线测试；未执行真实付费生成。
+
+## 一手资料
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| API 文档 | https://fal.ai/models/fal-ai/seedvr/upscale/image/api | 否 |
+| OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/seedvr/upscale/image | 否 |
+| API Key | https://fal.ai/dashboard/keys | 是 |