@henjicc/ai-sdk 0.9.0 → 0.10.0

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

@@ -1,73 +1,73 @@
-# SenseVoiceSmall · 硅基流动
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-09-21 |
-| 模态 | ASR（同步文件转写） |
-| 供应商 | SiliconFlow / SiliconCloud |
-| 平台模型 ID | `FunAudioLLM/SenseVoiceSmall` |
-| 当前公开价格 | **免费** |
-| 免费前提 | 账号实名认证；固定 Rate Limits，精确数值未公开 |
-| 文档/价格 | 公开无需登录；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=FunAudioLLM/SenseVoiceSmall
-```
-
-`file` 必须不超过 1 小时、50 MB。官方 cURL 以 MP3 为示例，但转写页未公开完整文件
-格式白名单。公开协议没有 `language/prompt/response_format`、热词、说话人、情感或音频事件
-参数，也没有 WebSocket/SSE 实时接口。
-
-## 2. 响应契约
-
-```json
-{
-  "text": "<string>"
-}
-```
-
-响应头包含 `x-siliconcloud-trace-id`。虽然 SenseVoice 开源上游还有多语种、情感与音频事件能力，
-硅基流动当前转写 API 只声明 `text`。SDK 文档与类型不得保证端点会返回上游额外标签。
-
-## 3. 价格、账号与限流
-
-- 2026-08-31 公开价格页的语音模型栏对 `FunAudioLLM/SenseVoiceSmall` 标注“免费”。
-- 这是免费模型计划，不是一次性赠送金；官方说明账单中调用消耗为 0。
-- 全部免费模型要求实名认证。限流为固定值，但公开 Rate Limits 页未给本模型的精确
-  RPM/RPD/音频时长额度；以登录后实际账号页为准。
-- 官方转写页明确保留模型上下线和服务能力调整的可能；价格/可用性需在发布前复核。
-
-## 4. 错误与适配要点
-
-官方错误体可为 `{code,message,data}` JSON，也可为纯文本。常见状态为 400/401/403/429/
-500/503/504；403 可与实名、模型权限或余额有关。SDK 的 `provider_http_error` 诊断文本保留
-HTTP status、可用的 `code/message/data`、文本 fallback 和脱敏追踪 ID；
-当前通用 `AiRuntimeError` 不提供结构化供应商错误 metadata。
-
-Say-It/SDK 接入是简单 Bearer + multipart HTTP，但不得透传硅基流动未公开的 OpenAI ASR
-扩展参数。中国大陆使用 `api.siliconflow.cn`；本轮未发起真实请求，实际账号限流未实测。
-
-## 5. 原始链接索引
-
-| 信息 | 链接 | 登录 |
-|---|---|---|
-| ASR API、模型 ID、输入限制与响应 | 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 | 否 |
-| API Key | https://cloud.siliconflow.cn/account/ak | **是** |
-
-## 2026-09-21 文件传输边界复核
-
-SDK 本地 multipart 默认上限为 50,000,000 字节（十进制保守解释官方 50 MB），仍受 1 小时时长限制。宿主 describe/readChunk + fetchStream 仅改变传输内存，不改变文件格式。
+# SenseVoiceSmall · 硅基流动
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-09-21 |
+| 模态 | ASR（同步文件转写） |
+| 供应商 | SiliconFlow / SiliconCloud |
+| 平台模型 ID | `FunAudioLLM/SenseVoiceSmall` |
+| 当前公开价格 | **免费** |
+| 免费前提 | 账号实名认证；固定 Rate Limits，精确数值未公开 |
+| 文档/价格 | 公开无需登录；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=FunAudioLLM/SenseVoiceSmall
+```
+
+`file` 必须不超过 1 小时、50 MB。官方 cURL 以 MP3 为示例，但转写页未公开完整文件
+格式白名单。公开协议没有 `language/prompt/response_format`、热词、说话人、情感或音频事件
+参数，也没有 WebSocket/SSE 实时接口。
+
+## 2. 响应契约
+
+```json
+{
+  "text": "<string>"
+}
+```
+
+响应头包含 `x-siliconcloud-trace-id`。虽然 SenseVoice 开源上游还有多语种、情感与音频事件能力，
+硅基流动当前转写 API 只声明 `text`。SDK 文档与类型不得保证端点会返回上游额外标签。
+
+## 3. 价格、账号与限流
+
+- 2026-08-31 公开价格页的语音模型栏对 `FunAudioLLM/SenseVoiceSmall` 标注“免费”。
+- 这是免费模型计划，不是一次性赠送金；官方说明账单中调用消耗为 0。
+- 全部免费模型要求实名认证。限流为固定值，但公开 Rate Limits 页未给本模型的精确
+  RPM/RPD/音频时长额度；以登录后实际账号页为准。
+- 官方转写页明确保留模型上下线和服务能力调整的可能；价格/可用性需在发布前复核。
+
+## 4. 错误与适配要点
+
+官方错误体可为 `{code,message,data}` JSON，也可为纯文本。常见状态为 400/401/403/429/
+500/503/504；403 可与实名、模型权限或余额有关。SDK 的 `provider_http_error` 诊断文本保留
+HTTP status、可用的 `code/message/data`、文本 fallback 和脱敏追踪 ID；
+当前通用 `AiRuntimeError` 不提供结构化供应商错误 metadata。
+
+Say-It/SDK 接入是简单 Bearer + multipart HTTP，但不得透传硅基流动未公开的 OpenAI ASR
+扩展参数。中国大陆使用 `api.siliconflow.cn`；本轮未发起真实请求，实际账号限流未实测。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| ASR API、模型 ID、输入限制与响应 | 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 | 否 |
+| API Key | https://cloud.siliconflow.cn/account/ak | **是** |
+
+## 2026-09-21 文件传输边界复核
+
+SDK 本地 multipart 默认上限为 50,000,000 字节（十进制保守解释官方 50 MB），仍受 1 小时时长限制。宿主 describe/readChunk + fetchStream 仅改变传输内存，不改变文件格式。

package/docs/model-adaptation/TTS-/345/244/232/344/276/233/345/272/224/345/225/206-2026-09.md

@@ -1,69 +1,115 @@
-# TTS 多供应商适配契约（2026-09-27）
-
-本文件记录本次 SDK 适配所需的供应商原始契约。原始范围为文字转语音和对话语音；2026-09-28 补充 Seed-ICL 2.0 官方 V3 声音训练，详见 [语音克隆契约](Seed-ICL-2.0/Seed-ICL-2.0_火山引擎.md)。用户确认：公开价格可核实时显示估算；无法由输入参数可靠估算的价格不显示估算。
-
-## 模型与请求矩阵
-
-| 平台 | 模型 / 路由 | 协议、输出 | 公开价格 | 官方依据 |
-| --- | --- | --- | --- | --- |
-| 派欧云 | MiniMax Speech 2.8 HD / Turbo | 已有 `/async/minimax-speech-2.8-{hd,turbo}` 轮询；音频 URL | HD ¥3.5、Turbo ¥2 / 万字符 | [派欧云 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd)、[派欧云异步 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async) |
-| Fal | `fal-ai/minimax/speech-2.8-hd`、`fal-ai/minimax/speech-2.8-turbo` | Fal queue；`audio.url` | HD $0.10、Turbo $0.06 / 千字符 | [HD API](https://fal.ai/models/fal-ai/minimax/speech-2.8-hd/api)、[Turbo API](https://fal.ai/models/fal-ai/minimax/speech-2.8-turbo/api)、[HD 定价](https://fal.ai/models/fal-ai/minimax/speech-2.8-hd)、[Turbo 定价](https://fal.ai/models/fal-ai/minimax/speech-2.8-turbo) |
-| Fal | `fal-ai/qwen-3-tts/text-to-speech/1.7b` | Fal queue；`audio.url` | $0.09 / 千字符 | [API](https://fal.ai/models/fal-ai/qwen-3-tts/text-to-speech/1.7b/api)、[定价](https://fal.ai/models/fal-ai/qwen-3-tts/text-to-speech/1.7b) |
-| Fal | `fal-ai/elevenlabs/tts/eleven-v3` | Fal queue；`audio.url` | $0.10 / 千字符 | [API](https://fal.ai/models/fal-ai/elevenlabs/tts/eleven-v3/api)、[定价](https://fal.ai/models/fal-ai/elevenlabs/tts/eleven-v3) |
-| 百炼 | `MiniMax/speech-2.8-hd`、`MiniMax/speech-2.8-turbo` | 同步 HTTP；`output.data.audio` 为 hex | HD ¥3.5、Turbo ¥2 / 万字符 | [API](https://help.aliyun.com/zh/model-studio/minimax-synchronous-speech-synthesis-api)、[定价](https://help.aliyun.com/zh/model-studio/model-pricing) |
-| 百炼 | `qwen-audio-3.1-tts-flash` | 同步 HTTP；`output.audio.url`，有效期 24 小时 | 输入 ¥1.5 / 百万 Token、输出 ¥12 / 百万 Token；提交前无法准确估算输出 Token | [API](https://help.aliyun.com/zh/model-studio/cosyvoice-tts-http-api)、[模型价格](https://help.aliyun.com/zh/model-studio/qwen-audio-3-1-tts-flash) |
-| 百炼 | `cosyvoice-v3.5-flash`、`cosyvoice-v3.5-plus` | 同步 HTTP；`output.audio.url`，有效期 24 小时 | Flash ¥0.8、Plus ¥1.5 / 万字符 | [API](https://help.aliyun.com/zh/model-studio/cosyvoice-tts-http-api)、[定价](https://help.aliyun.com/zh/model-studio/model-pricing) |
-| KIE | `google/gemini-3-1-flash-tts` | `createTask` + `recordInfo`；`resultJson.resultUrls` | 输入 $0.7、音频输出 $14 / 百万 Token；提交前无法准确估算输出 Token | [API](https://docs.kie.ai/market/google/gemini-3-1-flash-tts)、[定价](https://kie.ai/pricing) |
-| KIE | `elevenlabs/text-to-speech-turbo-2-5` | 同上 | $0.03 / 千字符 | [API](https://docs.kie.ai/market/elevenlabs/text-to-speech-turbo-2-5)、[定价](https://kie.ai/pricing) |
-| KIE | `elevenlabs/text-to-dialogue-v3` | 同上；输入为 `input.dialogue[]` | $0.07 / 千字符 | [API](https://docs.kie.ai/market/elevenlabs/text-to-dialogue-v3)、[定价](https://kie.ai/pricing) |
-| 火山引擎 | `seed-tts-2.0`、`seed-icl-2.0` | V3 HTTP Chunked；逐帧 JSON 的 `data` 为 base64 音频块 | 2026-09-28 核实：合成及训练试听 ¥3 / 万字符；后付费克隆首次正式合成另收 ¥138 / 音色 | [V3 HTTP](https://docs.volcengine.com/docs/DoubaoVoice/unidirectional-streaming-text-to-speech-http?lang=zh)、[公开刊例](https://docs.volcengine.com/docs/DoubaoVoice/Billinginstructions-21?lang=zh) |
-| 硅基流动 | `FunAudioLLM/CosyVoice2-0.5B`、`fnlp/MOSS-TTSD-v0.5` | `POST /v1/audio/speech`；直接返回音频二进制 | ¥0.05 / 千 UTF-8 字符 | [API](https://docs.siliconflow.cn/docs/api/audio-speech-post)、[定价](https://siliconflow.cn/pricing) |
-
-百炼的专属业务空间域名为推荐项，官方明确现有 `dashscope.aliyuncs.com` 域名继续可用；SDK 使用现有域名和北京地域 API Key。百炼 MiniMax 与 Qwen/CosyVoice 的路由不同，不能混用。CosyVoice 3.5 无系统音色，必须使用先前创建的复刻或设计音色 ID。火山语音 V3 使用独立的 `X-Api-Key`，SDK 单列 `volcengine-speech` 供应商以免覆盖方舟图片模型的 Key；复刻音色请求须设 `req_params.model=seed-tts-2.0-standard`。火山 V1 非流式接口明确不支持 Seed-TTS 2.0 音色，不能作为 V3 替代。[百炼 API](https://help.aliyun.com/zh/model-studio/cosyvoice-tts-http-api)、[CosyVoice 音色限制](https://help.aliyun.com/zh/model-studio/non-realtime-tts-user-guide)、[火山 V3](https://docs.volcengine.com/docs/DoubaoVoice/unidirectional-streaming-text-to-speech-http?lang=zh)、[火山 V1 说明](https://docs.volcengine.com/docs/DoubaoVoice/HTTPone-timecompositenon-streaminginterface-V1notrecommended?lang=zh)。
-
-## 事件与终态契约
-
-| 协议 | 前置/中间状态 | 成功终态与输出 | 失败/空值处理 | 断线、取消和复用 |
-| --- | --- | --- | --- | --- |
-| Fal queue | 提交返回 `request_id` 或 `status_url`；状态 `IN_QUEUE` / `IN_PROGRESS` | `COMPLETED` 后取 `response_url`，要求 `audio.url` | `FAILED`、无结果 URL 报错；状态字段缺失报错 | 中断信号取消本地等待；远端任务是否被取消，官方未说明。状态 URL 限定 Fal queue 域名。 |
-| KIE jobs | 创建返回 `data.taskId`；查询 `waiting` / `queuing` / `generating` | `success`，解析 `data.resultJson.resultUrls` | `fail` 或查询错误报错；空结果报错 | 中断信号取消本地等待；远端任务取消/恢复官方未说明。 |
-| 百炼非流式 HTTP | 单次 JSON 响应；不产生中间事件 | Qwen/CosyVoice `output.finish_reason=stop` 且 `output.audio.url`；MiniMax `output.base_resp.status_code=0`、`output.data.status=2` 且 hex 音频 | 缺输出、错误码、空音频报错 | 中断 HTTP 请求；连接复用由 HTTP transport 处理。 |
-| 火山 V3 HTTP Chunked | 一次提交，分块读取 JSON；每个 `code=0` 的非空 `data` 是音频块 | 完整读取至服务端终止，按原序拼接全部音频块；`usage.text_words` 为计费字符 | `code!=0` 报错；无音频块报错；未完整终止不得产出音频 | 中断信号终止读取并释放 reader；断线不重放付费请求。帧乱序/断线恢复官方未说明。 |
-| 硅基流动 HTTP | 单次请求 | 2xx 且非空音频二进制 | 非 2xx 或空 body 报错 | 中断 HTTP 请求；无任务轮询。 |
-
-以上只接入各平台已证实的非流式完整结果路径。Fal 本身的 streaming 和百炼 SSE 属于另外的可选协议，不因页面支持 streaming 就默认在本次实现中启用。官方示例中的占位音频与签名 URL 只用于字段契约 fixture，不能据此宣称真实付费生成成功。
-
-### 火山 V3 分块事件矩阵
-
-官方把每个 HTTP 分块描述为 JSON 消息；HTTP 读取边界可能拆开或合并 JSON 消息，因此 SDK 按完整 JSON 对象切帧。`code` 为必填数字，`data` 为可选 base64 音频字符串，`usage.text_words` 为可选数字；空 `data` 或缺失 `data` 不产生音频。官方未说明帧乱序、重复、断线恢复或远端任务取消语义，SDK 不对付费 POST 自动重放。
-
-| 事件/状态 | 前置状态 | 字段契约（required / optional / nullable） | 空值/缺字段语义 | 下一状态 | 对外输出 | 副作用 | 终态/错误 | 连接复用 |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| 成功音频帧 `code=0` | 请求已提交、流读取中 | `code: number` 必填；`data: string` 可选；`usage.text_words: number` 可选 | 空/缺 `data` 无音频；`null` 不是可解码音频 | 继续读取 | 累积音频块和最近一次用量 | base64 解码、顺序追加 | 非终态 | 继续读取同一响应 |
-| 服务错误帧 `code!=0` | 流读取中 | `code: number` 必填；`message: string` 可选 | 缺 `message` 使用通用错误 | 失败 | 错误 | 释放 reader | 错误终态 | 不复用该响应 |
-| 正常 EOF | 流读取中 | 无新的 JSON 字段 | 尚有不完整 JSON 为无效响应；全程无有效音频为空结果 | 完成或失败 | 单个音频 data URI | 拼接所有音频块、释放 reader | 本地终态；官方未提供单独 final 字段 | 请求结束 |
-| 中断或断线 | 流读取中 | `AbortSignal` 或 HTTP 读取故障 | 不交付部分音频 | 失败/取消 | 原因错误 | 取消并释放 reader | 本地终态；断线能否恢复官方未说明 | 不重放写请求 |
-
-状态机不变量：只有正常 EOF 且至少一个非空音频块才能成功；空中间帧可重复；帧中的 JSON 字符串可跨网络分块；错误或取消后不得返回已经累积的部分音频。正常、失败及取消均释放 reader。Fal/KIE 的既有 queue/jobs 状态机沿用原适配器，新增模型仅提供官方 model ID、请求构建和媒体输出字段，不新增轮询协议分支。
-
-## 参数边界
-
-### 音色目录与账号音色查询（2026-09-27 核对）
-
-| 模型范围 | 官方音色来源 | 接入方式与边界 |
-| --- | --- | --- |
-| 百炼 Qwen Audio 3.1 TTS Flash | [官方音色清单](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-voice-list)，当前 68 个预置 ID；[复刻音色列表 API](https://help.aliyun.com/en/model-studio/voice-clone-design-http-api) | 预置清单本地展示；以北京地域百炼 Key 请求 `POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization`，`model=voice-enrollment`、`input.action=list_voice`、`page_index` 从 0 起、`page_size=50`，读取 `output.voice_list[].voice_id/status`；只呈现 `status=OK` 且属于本模型的 ID。 |
-| 百炼 CosyVoice 3.5 | [复刻音色列表 API](https://help.aliyun.com/en/model-studio/voice-clone-design-http-api) | 同上。无预置音色；只呈现 `cosyvoice-v3.5-` 前缀且状态为 `OK` 的音色。 |
-| 百炼 MiniMax Speech 2.8 | [音色管理 API](https://help.aliyun.com/zh/model-studio/sound-management) | 以百炼 Key 请求 `POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`，`model=MiniMax/speech-2.8-turbo`、`input.action=get_voice`、`voice_type=all`；读取 `output.system_voice[]` 和 `output.voice_cloning[]` 的 `voice_id/voice_name/description`，检查 `output.base_resp.status_code=0`。未配置 Key 时仅保留本模型已证实默认音色，不借用其他供应商目录。 |
-| 硅基流动 CosyVoice2 | [官方音色文档](https://docs.siliconflow.cn/docs/userguide/capabilities/text-to-speech) | 本地展示 8 个预置音色；用账号 Key 请求 `GET https://api.siliconflow.cn/v1/audio/voice/list`，读取自定义音色 `uri` 和名称。官方文档未给出完整响应外壳，解析器接受直接数组、`data` 数组及 `voices` 数组；实测前不声称所有账号响应形态均已验证。 |
-| 火山 Seed-TTS 2.0 / 豆包语音 2.0 | [官方音色清单](https://docs.volcengine.com/docs/DoubaoVoice/Tonelist-1?lang=zh) | 2026-09-28 核对 2.0 两个章节共 431 个音色 ID，补齐旧清单遗漏的 `ICL_uranus_*` 系统音色；本地提供搜索和选择。控制面 ListSpeakers 需要独立 AK/SK 签名，不能用语音 Key 代替。 |
-| 火山 Seed-ICL 2.0 | [新版按 ID 查询](https://docs.volcengine.com/docs/DoubaoVoice/tone-query-http?lang=zh)、[旧版音色管理说明](https://docs.volcengine.com/docs/DoubaoVoice/Soundreplicationorderingandusageguide?lang=zh) | 新版官方查询只按已知 `speaker_id` 查状态；旧版批量查询接口与当前 V3 凭据/协议不一致，未接入。2026-09-28 接入 V3 训练和状态查询；新音色自动编号并保存到应用音色库，已有预付费槽位可手动导入。 |
-| Fal Eleven v3 / MiniMax 2.8、KIE Eleven、Gemini 3.1、硅基流动 MOSS | [Fal Eleven v3](https://fal.ai/models/fal-ai/elevenlabs/tts/eleven-v3)、[Fal MiniMax](https://fal.ai/models/fal-ai/minimax/speech-2.8-hd/api)、[KIE Eleven Turbo](https://docs.kie.ai/market/elevenlabs/text-to-speech-turbo-2-5)、[KIE Eleven Dialogue](https://docs.kie.ai/market/elevenlabs/text-to-dialogue-v3)、[Google 预置音色](https://ai.google.dev/gemini-api/docs/speech-generation)、[硅基流动 MOSS](https://docs.siliconflow.cn/docs/userguide/capabilities/text-to-speech) | 收录各渠道官方明确列出的预置音色或示例 ID。渠道未公布完整账号音色查询接口的模型保留手填兜底；不可将 ElevenLabs 或其他供应商原生音色 API 直接当成转售渠道的可用列表。 |
-
-上述音色查询均为单次 HTTP JSON 读请求，官方没有流式事件、取消远端任务、分页总数或连接复用的特殊契约；HTTP 失败、供应商错误码、响应外壳缺失都应报错，不把错误当成空目录。分页仅用于百炼 `list_voice`，遇不足一页时结束；到达客户端有界页数仍满页时应提示目录未完整读取。自定义音色的名称若官方只返回 ID，则展示 ID。
-
-- 各模型的文本来自 SDK 统一 `prompt`/`text` 输入，转换到供应商要求的 `prompt`、`text` 或嵌套 `input.text`。
-- 音色使用各平台官方音色 ID；火山 Seed-ICL 支持直接上传录音克隆；其他供应商复刻音色使用官方列表或已取得的 ID。
-- KIE Gemini 3.1 使用 `speakers[]` 与 `dialogue_turns[]`；Eleven v3 对话使用 `dialogue[]`。SDK 在仅有普通文本时明确构建单说话人/单台词数组；调用方传入结构化数组时保留多说话人能力。痕迹AI 当前通用参数面板只暴露单说话人文本入口。
-- 音频块和二进制响应在 SDK 边界转换为 `data:audio/...;base64,...`，交给宿主已有媒体落盘边界；不得只返回原始 base64/hex 字符串。
-- 派欧云 2.8 的 `emotion`：MiniMax 原厂说明支持情感，但派欧云异步参考页写为仅 2.6/01 生效。平台契约冲突，不能将原厂能力直接视为派欧云 2.8 能力；需在该平台屏蔽未证实的情感选项。[派欧云异步 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async)。
+# TTS 多供应商适配契约（2026-09-27）
+
+本文件记录本次 SDK 适配所需的供应商原始契约。原始范围为文字转语音和对话语音；2026-09-28 补充 Seed-ICL 2.0 官方 V3 声音训练，详见 [语音克隆契约](Seed-ICL-2.0/Seed-ICL-2.0_火山引擎.md)。用户确认：公开价格可核实时显示估算；无法由输入参数可靠估算的价格不显示估算。
+
+## 模型与请求矩阵
+
+| 平台 | 模型 / 路由 | 协议、输出 | 公开价格 | 官方依据 |
+| --- | --- | --- | --- | --- |
+| 派欧云 | MiniMax Speech 2.8 HD / Turbo | 已有 `/async/minimax-speech-2.8-{hd,turbo}` 轮询；音频 URL | HD ¥3.5、Turbo ¥2 / 万字符 | [派欧云 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd)、[派欧云异步 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async) |
+| Fal | `fal-ai/minimax/speech-2.8-hd`、`fal-ai/minimax/speech-2.8-turbo` | Fal queue；`audio.url` | HD $0.10、Turbo $0.06 / 千字符 | [HD API](https://fal.ai/models/fal-ai/minimax/speech-2.8-hd/api)、[Turbo API](https://fal.ai/models/fal-ai/minimax/speech-2.8-turbo/api)、[HD 定价](https://fal.ai/models/fal-ai/minimax/speech-2.8-hd)、[Turbo 定价](https://fal.ai/models/fal-ai/minimax/speech-2.8-turbo) |
+| Fal | `fal-ai/qwen-3-tts/text-to-speech/1.7b` | Fal queue；`audio.url` | $0.09 / 千字符 | [API](https://fal.ai/models/fal-ai/qwen-3-tts/text-to-speech/1.7b/api)、[定价](https://fal.ai/models/fal-ai/qwen-3-tts/text-to-speech/1.7b) |
+| Fal | `fal-ai/elevenlabs/tts/eleven-v3` | Fal queue；`audio.url` | $0.10 / 千字符 | [API](https://fal.ai/models/fal-ai/elevenlabs/tts/eleven-v3/api)、[定价](https://fal.ai/models/fal-ai/elevenlabs/tts/eleven-v3) |
+| 百炼 | `MiniMax/speech-2.8-hd`、`MiniMax/speech-2.8-turbo` | 同步 HTTP；`output.data.audio` 为 hex | HD ¥3.5、Turbo ¥2 / 万字符 | [API](https://help.aliyun.com/zh/model-studio/minimax-synchronous-speech-synthesis-api)、[定价](https://help.aliyun.com/zh/model-studio/model-pricing) |
+| 百炼 | `qwen-audio-3.1-tts-flash` | 同步 HTTP；`output.audio.url`，有效期 24 小时 | 输入 ¥1.5 / 百万 Token、输出 ¥12 / 百万 Token；提交前按全文慢速输出作保守估算，非官方折算 | [API](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-http-api)、[模型价格](https://help.aliyun.com/zh/model-studio/qwen-audio-3-1-tts-flash) |
+| 百炼 | `cosyvoice-v3.5-flash`、`cosyvoice-v3.5-plus` | 同步 HTTP；`output.audio.url`，有效期 24 小时 | Flash ¥0.8、Plus ¥1.5 / 万字符 | [API](https://help.aliyun.com/zh/model-studio/cosyvoice-tts-http-api)、[定价](https://help.aliyun.com/zh/model-studio/model-pricing) |
+| KIE | `google/gemini-3-1-flash-tts` | `createTask` + `recordInfo`；`resultJson.resultUrls` | 输入 $0.7、音频输出 $14 / 百万 Token；提交前无法准确估算输出 Token | [API](https://docs.kie.ai/market/google/gemini-3-1-flash-tts)、[定价](https://kie.ai/pricing) |
+| KIE | `elevenlabs/text-to-speech-turbo-2-5` | 同上 | $0.03 / 千字符 | [API](https://docs.kie.ai/market/elevenlabs/text-to-speech-turbo-2-5)、[定价](https://kie.ai/pricing) |
+| KIE | `elevenlabs/text-to-dialogue-v3` | 同上；输入为 `input.dialogue[]` | $0.07 / 千字符 | [API](https://docs.kie.ai/market/elevenlabs/text-to-dialogue-v3)、[定价](https://kie.ai/pricing) |
+| 火山引擎 | `seed-tts-2.0`、`seed-icl-2.0` | V3 HTTP Chunked；逐帧 JSON 的 `data` 为 base64 音频块 | 2026-09-28 核实：合成及训练试听 ¥3 / 万字符；后付费克隆首次正式合成另收 ¥138 / 音色 | [V3 HTTP](https://docs.volcengine.com/docs/DoubaoVoice/unidirectional-streaming-text-to-speech-http?lang=zh)、[公开刊例](https://docs.volcengine.com/docs/DoubaoVoice/Billinginstructions-21?lang=zh) |
+| 硅基流动 | `FunAudioLLM/CosyVoice2-0.5B`、`fnlp/MOSS-TTSD-v0.5` | `POST /v1/audio/speech`；直接返回音频二进制 | ¥0.05 / 千 UTF-8 字符 | [API](https://docs.siliconflow.cn/docs/api/audio-speech-post)、[定价](https://siliconflow.cn/pricing) |
+
+百炼的专属业务空间域名为推荐项，官方明确现有 `dashscope.aliyuncs.com` 域名继续可用；SDK 使用现有域名和北京地域 API Key。百炼 MiniMax 与 Qwen/CosyVoice 的路由不同，不能混用。CosyVoice 3.5 无系统音色，必须使用先前创建的复刻或设计音色 ID。火山语音 V3 使用独立的 `X-Api-Key`，SDK 单列 `volcengine-speech` 供应商以免覆盖方舟图片模型的 Key；复刻音色请求须设 `req_params.model=seed-tts-2.0-standard`。火山 V1 非流式接口明确不支持 Seed-TTS 2.0 音色，不能作为 V3 替代。[百炼 API](https://help.aliyun.com/zh/model-studio/cosyvoice-tts-http-api)、[CosyVoice 音色限制](https://help.aliyun.com/zh/model-studio/non-realtime-tts-user-guide)、[火山 V3](https://docs.volcengine.com/docs/DoubaoVoice/unidirectional-streaming-text-to-speech-http?lang=zh)、[火山 V1 说明](https://docs.volcengine.com/docs/DoubaoVoice/HTTPone-timecompositenon-streaminginterface-V1notrecommended?lang=zh)。
+
+## 事件与终态契约
+
+| 协议 | 前置/中间状态 | 成功终态与输出 | 失败/空值处理 | 断线、取消和复用 |
+| --- | --- | --- | --- | --- |
+| Fal queue | 提交返回 `request_id` 或 `status_url`；状态 `IN_QUEUE` / `IN_PROGRESS` | `COMPLETED` 后取 `response_url`，要求 `audio.url` | `FAILED`、无结果 URL 报错；状态字段缺失报错 | 中断信号取消本地等待；远端任务是否被取消，官方未说明。状态 URL 限定 Fal queue 域名。 |
+| KIE jobs | 创建返回 `data.taskId`；查询 `waiting` / `queuing` / `generating` | `success`，解析 `data.resultJson.resultUrls` | `fail` 或查询错误报错；空结果报错 | 中断信号取消本地等待；远端任务取消/恢复官方未说明。 |
+| 百炼非流式 HTTP | 单次 JSON 响应；不产生中间事件 | Qwen/CosyVoice `output.finish_reason=stop` 且 `output.audio.url`；MiniMax `output.base_resp.status_code=0`、`output.data.status=2` 且 hex 音频 | 缺输出、错误码、空音频报错 | 中断 HTTP 请求；连接复用由 HTTP transport 处理。 |
+| 火山 V3 HTTP Chunked | 一次提交，分块读取 JSON；每个 `code=0` 的非空 `data` 是音频块 | 完整读取至服务端终止，按原序拼接全部音频块；`usage.text_words` 为计费字符 | `code!=0` 报错；无音频块报错；未完整终止不得产出音频 | 中断信号终止读取并释放 reader；断线不重放付费请求。帧乱序/断线恢复官方未说明。 |
+| 硅基流动 HTTP | 单次请求 | 2xx 且非空音频二进制 | 非 2xx 或空 body 报错 | 中断 HTTP 请求；无任务轮询。 |
+
+以上只接入各平台已证实的非流式完整结果路径。Fal 本身的 streaming 和百炼 SSE 属于另外的可选协议，不因页面支持 streaming 就默认在本次实现中启用。官方示例中的占位音频与签名 URL 只用于字段契约 fixture，不能据此宣称真实付费生成成功。
+
+### 火山 V3 分块事件矩阵
+
+官方把每个 HTTP 分块描述为 JSON 消息；HTTP 读取边界可能拆开或合并 JSON 消息，因此 SDK 按完整 JSON 对象切帧。`code` 为必填数字，`data` 为可选 base64 音频字符串，`usage.text_words` 为可选数字；空 `data` 或缺失 `data` 不产生音频。官方未说明帧乱序、重复、断线恢复或远端任务取消语义，SDK 不对付费 POST 自动重放。
+
+| 事件/状态 | 前置状态 | 字段契约（required / optional / nullable） | 空值/缺字段语义 | 下一状态 | 对外输出 | 副作用 | 终态/错误 | 连接复用 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 成功音频帧 `code=0` | 请求已提交、流读取中 | `code: number` 必填；`data: string` 可选；`usage.text_words: number` 可选 | 空/缺 `data` 无音频；`null` 不是可解码音频 | 继续读取 | 累积音频块和最近一次用量 | base64 解码、顺序追加 | 非终态 | 继续读取同一响应 |
+| 服务错误帧 `code!=0` | 流读取中 | `code: number` 必填；`message: string` 可选 | 缺 `message` 使用通用错误 | 失败 | 错误 | 释放 reader | 错误终态 | 不复用该响应 |
+| 正常 EOF | 流读取中 | 无新的 JSON 字段 | 尚有不完整 JSON 为无效响应；全程无有效音频为空结果 | 完成或失败 | 单个音频 data URI | 拼接所有音频块、释放 reader | 本地终态；官方未提供单独 final 字段 | 请求结束 |
+| 中断或断线 | 流读取中 | `AbortSignal` 或 HTTP 读取故障 | 不交付部分音频 | 失败/取消 | 原因错误 | 取消并释放 reader | 本地终态；断线能否恢复官方未说明 | 不重放写请求 |
+
+状态机不变量：只有正常 EOF 且至少一个非空音频块才能成功；空中间帧可重复；帧中的 JSON 字符串可跨网络分块；错误或取消后不得返回已经累积的部分音频。正常、失败及取消均释放 reader。Fal/KIE 的既有 queue/jobs 状态机沿用原适配器，新增模型仅提供官方 model ID、请求构建和媒体输出字段，不新增轮询协议分支。
+
+## 参数边界
+
+### 音色目录与账号音色查询（2026-09-27 核对）
+
+| 模型范围 | 官方音色来源 | 接入方式与边界 |
+| --- | --- | --- |
+| 百炼 Qwen Audio 3.1 TTS Flash | [官方音色清单](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-voice-list)，当前 68 个预置 ID；[复刻音色列表 API](https://help.aliyun.com/en/model-studio/voice-clone-design-http-api) | 预置清单本地展示；以北京地域百炼 Key 请求 `POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization`，`model=voice-enrollment`、`input.action=list_voice`、`page_index` 从 0 起、`page_size=50`，读取 `output.voice_list[].voice_id/status`；只呈现 `status=OK` 且属于本模型的 ID。 |
+| 百炼 CosyVoice 3.5 | [复刻音色列表 API](https://help.aliyun.com/en/model-studio/voice-clone-design-http-api) | 同上。无预置音色；只呈现 `cosyvoice-v3.5-` 前缀且状态为 `OK` 的音色。 |
+| 百炼 MiniMax Speech 2.8 | [音色管理 API](https://help.aliyun.com/zh/model-studio/sound-management) | 以百炼 Key 请求 `POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`，`model=MiniMax/speech-2.8-turbo`、`input.action=get_voice`、`voice_type=all`；读取 `output.system_voice[]` 和 `output.voice_cloning[]` 的 `voice_id/voice_name/description`，检查 `output.base_resp.status_code=0`。未配置 Key 时仅保留本模型已证实默认音色，不借用其他供应商目录。 |
+| 硅基流动 CosyVoice2 | [官方音色文档](https://docs.siliconflow.cn/docs/userguide/capabilities/text-to-speech) | 本地展示 8 个预置音色；用账号 Key 请求 `GET https://api.siliconflow.cn/v1/audio/voice/list`，读取自定义音色 `uri` 和名称。官方文档未给出完整响应外壳，解析器接受直接数组、`data` 数组及 `voices` 数组；实测前不声称所有账号响应形态均已验证。 |
+| 火山 Seed-TTS 2.0 / 豆包语音 2.0 | [官方音色清单](https://docs.volcengine.com/docs/DoubaoVoice/Tonelist-1?lang=zh) | 2026-09-28 核对 2.0 两个章节共 431 个音色 ID，补齐旧清单遗漏的 `ICL_uranus_*` 系统音色；本地提供搜索和选择。控制面 ListSpeakers 需要独立 AK/SK 签名，不能用语音 Key 代替。 |
+| 火山 Seed-ICL 2.0 | [新版按 ID 查询](https://docs.volcengine.com/docs/DoubaoVoice/tone-query-http?lang=zh)、[旧版音色管理说明](https://docs.volcengine.com/docs/DoubaoVoice/Soundreplicationorderingandusageguide?lang=zh) | 新版官方查询只按已知 `speaker_id` 查状态；旧版批量查询接口与当前 V3 凭据/协议不一致，未接入。2026-09-28 接入 V3 训练和状态查询；新音色自动编号并保存到应用音色库，已有预付费槽位可手动导入。 |
+| Fal Eleven v3 / MiniMax 2.8、KIE Eleven、Gemini 3.1、硅基流动 MOSS | [Fal Eleven v3](https://fal.ai/models/fal-ai/elevenlabs/tts/eleven-v3)、[Fal MiniMax](https://fal.ai/models/fal-ai/minimax/speech-2.8-hd/api)、[KIE Eleven Turbo](https://docs.kie.ai/market/elevenlabs/text-to-speech-turbo-2-5)、[KIE Eleven Dialogue](https://docs.kie.ai/market/elevenlabs/text-to-dialogue-v3)、[Google 预置音色](https://ai.google.dev/gemini-api/docs/speech-generation)、[硅基流动 MOSS](https://docs.siliconflow.cn/docs/userguide/capabilities/text-to-speech) | 收录各渠道官方明确列出的预置音色或示例 ID。渠道未公布完整账号音色查询接口的模型保留手填兜底；不可将 ElevenLabs 或其他供应商原生音色 API 直接当成转售渠道的可用列表。 |
+
+上述音色查询均为单次 HTTP JSON 读请求，官方没有流式事件、取消远端任务、分页总数或连接复用的特殊契约；HTTP 失败、供应商错误码、响应外壳缺失都应报错，不把错误当成空目录。分页仅用于百炼 `list_voice`，遇不足一页时结束；到达客户端有界页数仍满页时应提示目录未完整读取。自定义音色的名称若官方只返回 ID，则展示 ID。
+
+- 各模型的文本来自 SDK 统一 `prompt`/`text` 输入，转换到供应商要求的 `prompt`、`text` 或嵌套 `input.text`。
+- 音色使用各平台官方音色 ID；火山 Seed-ICL 支持直接上传录音克隆；其他供应商复刻音色使用官方列表或已取得的 ID。
+- KIE Gemini 3.1 使用 `speakers[]` 与 `dialogue_turns[]`；Eleven v3 对话使用 `dialogue[]`。SDK 在仅有普通文本时明确构建单说话人/单台词数组；调用方传入结构化数组时保留多说话人能力。痕迹AI 当前通用参数面板只暴露单说话人文本入口。
+- 音频块和二进制响应在 SDK 边界转换为 `data:audio/...;base64,...`，交给宿主已有媒体落盘边界；不得只返回原始 base64/hex 字符串。
+- 派欧云 2.8 的 `emotion`：MiniMax 原厂说明支持情感，但派欧云异步参考页写为仅 2.6/01 生效。平台契约冲突，不能将原厂能力直接视为派欧云 2.8 能力；需在该平台屏蔽未证实的情感选项。[派欧云异步 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async)。
+
+
+## 2026-10-12 外部 MCP 实测复核（t168）
+
+- KIE 当前 [Turbo 2.5 输入字段表](https://docs.kie.ai/market/elevenlabs/text-to-speech-turbo-2-5.md) 的 `voice` 是 ID 枚举，默认 James `EkK5I93UQWFDigLMpZcX`，Brian 为 `nPczCjzI2devNBz1zQrb`。旧轮询示例的 Rachel 与输入表冲突，修正 SDK 默认值与宿主选择器，旧名称不做迁移。`text` 上限 5000 字符，`stability` 0–1、`speed` 0.7–1.2；当前已发送字段符合范围。`language_code` 可省略，文档未要求中文必填。
+- 脱敏契约 fixture：`tests/fixtures/tts/kie-turbo-input.json`，从上述官方字段表构造，不是实测成功响应。精确测试验证默认中文请求可通过字段表，以及名称/越界参数不可通过；没有真实付费调用。此前 Internal Error 不能只凭静态核对断言已解决；用户最小确认调用：同一中文短句、James ID、默认 stability/speed、language_code 省略，仅调用一次并保留 taskId 与最终供应商状态。
+- [百炼错误码官方说明](https://help.aliyun.com/zh/model-studio/error-code) 明确 `The product is not activated` 是模型服务未开通。SDK 百炼响应解码时统一转中文、`retryable:false`，日志保留 `providerCode`、`providerMessage`、HTTP status；它是供应商可移植语义，归 SDK，不在 MCP 或 UI 加百炼分支。HTTP 200/400/403、兼容接口嵌套 error 与 MiniMax base_resp 均以离线构造响应覆盖；空的顶层 message 不遮蔽嵌套原因。
+- [Qwen 模型页](https://help.aliyun.com/zh/model-studio/qwen-audio-3-1-tts-flash) 确认输入 ¥1.5/百万 Token、输出 ¥12/百万 Token；[HTTP 文档](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-http-api) 只提供 usage token 统计，未找到该型号音频秒数折算率。其他 Qwen ASR 的 25 Token/秒不能作为此 TTS 计费事实。估价方案待确认，不能宣称账单硬上限。
+
+- 其他 NaN 音频仅 KIE Gemini 3.1 Flash TTS：[Google 同名模型窗口](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-tts-preview) 为输入 8192 / 输出 16384 Token，[官方折算](https://cloud.google.com/text-to-speech/pricing) 为音频 25 Token/秒，即最大输出窗口约 655.36 秒。采用整个 token 窗口乘 KIE 当前 $0.7/$14 百万 Token 费率，保守预留 $0.2351104，`billingMode:estimated`；不以文本语速推断硬上限、不限制产品数量。该窗口来自 Google，KIE 文档没有独立窗口承诺，说明中保留“实际以 KIE 账单为准”。
+
+## 2026-10-12 Qwen Audio 3.1 TTS 估算上限
+
+BrowserOS neo核对[HTTP API](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-http-api)、[计费](https://help.aliyun.com/zh/model-studio/model-pricing)、[模型说明](https://help.aliyun.com/zh/model-studio/tts-model)、[公开控制台模型卡](https://bailian.console.aliyun.com/cn-beijing/model/market/detail/qwen-audio-3.1-tts-flash)。控制台最大输入、上下文和最大输出长度均为“—”，公开文档只给输入/输出Token用量，没有Token/秒。无法给“官方文本上限对应输出”而不编造官方上限，因此以本次输入全文的字符预算作为可读文本范围，不设产品数量上限。
+
+工程保守假设（不声称官方保证）：常速最慢合理朗读每秒1字，按rate 0.5–2折算最长合理时长ceil(全文Unicode字符数/rate)秒；每音频秒100Token预算；输入全文及风格指令的UTF-8字节数作为输入Token预算。费用=(输入预算×1.5+音频预算×12)/1e6元。标为“估算上限（非账单保证）”，沿现有约价显示，不再因NaN阻断。并非可证明的绝对账单上限；语音指令、停顿/特殊标记等可能影响输出，应以供应商实际usage为准。未扩大maxOutputTokens或请求参数。未查到需登录的官方折算证据；未进入体验或账号费用页面，未读取Key。
+
+展示沿统一 PriceEstimate，pricing.estimateKind=upper-bound 在面板和画布徽标都标“估算上限”，悬浮提示说明保守假设与实际账单结算；无模型ID分支。
+
+
+## 2026-10-12 第二轮 MCP 复核（t173）
+
+本轮仅通过 BrowserOS neo 会话 `mcp-round2` 阅读官方页面，未发出任何模型 API 请求。KIE 最近相关请求日志为 2026-10-11 15:55:59 UTC，早于 t168 的 2026-10-12 02:02（北京时间）提交及 03:38 合并；旧日志中的 Brian/Rachel 不代表已合并版本。不过请求构建器仍可绕过参数面板发出名称，本轮在 SDK 模型 builder 校验官方 voice ID 枚举，省略时默认 James。
+
+KIE [Turbo 输入字段](https://docs.kie.ai/market/elevenlabs/text-to-speech-turbo-2-5)：模型 `elevenlabs/text-to-speech-turbo-2-5`，`input.text` 最长 5000 字符，`input.voice` 为官方 67 个 ID，默认 `EkK5I93UQWFDigLMpZcX`，`speed` 0.7–1.2，`stability` 0–1，`language_code` 可选，本轮不发送。只构建不发送的最小请求：
+
+```json
+{"model":"elevenlabs/text-to-speech-turbo-2-5","input":{"text":"测试一下。","voice":"EkK5I93UQWFDigLMpZcX","stability":0.5,"speed":1.05}}
+```
+
+公开错误分类依据：
+
+| 官方来源 | 可确认契约 | SDK 分类 |
+|---|---|---|
+| [百炼错误码](https://help.aliyun.com/zh/model-studio/error-code) | Arrearage；AccessDenied.Unpurchased；Model.AccessDenied；MiniMax 的明确 product is not activated 文案 | 账户余额；产品未开通；模型权限 |
+| [KIE 任务详情](https://docs.kie.ai/market/common/get-task-detail) | code=402；fail + Internal Error；422 参数失败 | 账户余额；供应商内部失败；参数拒绝 |
+| [PPIO 错误码](https://ppio.com/docs/models/reference-error-code) | BILLING_BALANCE_NOT_ENOUGH / NOT_ENOUGH_BALANCE；API_NOT_ALLOWED / ACCESS_DENY | 账户余额；模型权限 |
+| [硅基流动错误码](https://api-docs.siliconflow.cn/docs/userguide/faqs/error-code) | HTTP 402；403 访问/实名条件 | 账户余额；模型权限 |
+| [APIMart 任务状态](https://docs.apimart.ai/cn/api-reference/tasks/status) | HTTP/响应 code 402；403 | 账户余额；模型权限 |
+| [火山方舟错误码](https://docs.volcengine.com/docs/ark/error-codes?lang=zh) | AccountOverdueError；ModelNotOpen / OperationDenied.ServiceNotOpen；AccessDenied / OperationDenied.PermissionDenied | 账户余额；产品未开通；模型权限 |
+| [Fal FAQ](https://fal.ai/docs/documentation/model-apis/faq) | 余额低于阈值会锁定账户，但未给可确认的 wire 错误码/原文 | 不猜测，保留原错误 |
+| [Grsai 公共文档](https://grsai.ai/zh/dashboard/documents/other) | 可查 credits，未找到余额/权限失败码表 | 不猜测，保留原错误 |
+
+响应/终态矩阵：正常 JSON 沿原解码；明确准入失败立即抛 `provider_product_not_activated` / `provider_model_access_denied` / `provider_insufficient_balance`，`retryable:false`，不自动重发；未知 403 或 BILLING_FAILED 保留 provider_http_error；KIE 任务 fail + Internal Error 返回 `provider_internal_error`，允许用户稍后手动提交，但 `terminal:true` 禁止自动继续轮询；422 返回 provider_invalid_request，保留供应商说明。非 JSON 响应沿原 invalid_json，不猜测业务错误；没有新增流、重连、远端取消或成功结构。
+
+fixture 正反例覆盖上述正式码、未知失败、终态不续查、默认音色和 Brian/Rachel 拒绝。断牙：临时移除共享 access 分类，15 个测试中 14 个失败、1 个未知错误测试通过；恢复实现后 15 个通过。工作区不构建/发布 SDK；宿主新错误码以 mock 验证，合并后由总管理者在主仓重建 SDK 再做宿主联动。

package/docs/model-adaptation/TTS-/346/227/266/351/227/264/346/210/263-2026-10.md

@@ -0,0 +1,36 @@
+# TTS 原生时间戳核实（t177，2026-10-12）
+
+仅核实本仓当前接入的接口，不把模型官网或另一供应商的能力等同于当前接口能力。使用 BrowserOS neo 的 `tts-timestamps` 会话，自建标签页逐页读取；没有登录、读取密钥或执行生成。表中“未声明”不等于供应商绝对不支持，“未见附加费”不等于供应商保证免费。
+
+| 模型（规格） | 当前接口 | 时间戳与粒度 | 开启参数 / 返回字段 | 计费证据 | 本批 |
+|---|---|---|---|---|---|
+| 百炼 Qwen Audio 3.1 TTS Flash | HTTP SpeechSynthesizer，当前非流式 | 仅流式输出支持词级时间戳；有音色限制 | `word_timestamp_enabled`；`output.sentence.words[].begin_time/end_time`，毫秒 | 未见时间戳单列费用；合成正常计费 | 不切换协议，未接；[官方](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-http-api) |
+| 百炼 CosyVoice 3.5 Flash / Plus | HTTP SpeechSynthesizer，当前非流式 | 仅流式，文档明确克隆音色支持 | 同上 | 未见单列费用 | 未接；[官方](https://help.aliyun.com/zh/model-studio/cosyvoice-tts-http-api) |
+| 百炼 MiniMax Speech 2.8 HD / Turbo | 同步 HTTP multimodal-generation | 非流式可开启字幕，但官方响应表未定义字幕载荷 | `input.subtitle_enable=true`；本次公开页面/HTML 均未给字幕字段或单位 | 未明确字幕附加费，不能承诺免费 | 暂未接，缺可验证返回契约；[官方](https://help.aliyun.com/zh/model-studio/minimax-synchronous-speech-synthesis-api) |
+| PPIO MiniMax Speech 2.8 HD / Turbo | async 提交/轮询 | 当前接口文档未声明时间戳 | 无可核实参数和返回字段 | 正常合成计费 | 未接；[HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async)、[Turbo](https://ppio.com/docs/models/reference-minimax-speech-2.8-turbo-async) |
+| Fal MiniMax Speech 2.8 HD / Turbo | Fal queue speech-2.8-hd / turbo | 当前输入/输出 schema 未声明时间戳 | 输出 audio | 正常合成计费 | 未接；[HD](https://fal.ai/models/fal-ai/minimax/speech-2.8-hd/api)、[Turbo](https://fal.ai/models/fal-ai/minimax/speech-2.8-turbo/api) |
+| 火山 Seed-TTS 2.0 | HTTP Chunked `/api/v3/tts/unidirectional` | 支持字级，仅中英文；无需 WebSocket | `req_params.audio_params.enable_subtitle=true`；`sentence.words[].word/startTime/endTime/confidence`，秒 | 合成 3 元/万字符；[计费页](https://docs.volcengine.com/docs/DoubaoVoice/Billinginstructions-21?lang=zh)未单列该开关费用；独立字幕打轴收费不等于本字段收费 | 已接；[官方](https://docs.volcengine.com/docs/DoubaoVoice/unidirectional-streaming-text-to-speech-http?lang=zh) |
+| 火山 Seed-ICL 2.0（合成模式） | 同上，克隆音色用 seed-icl-2.0 资源 | 同上；训练接口不产音频时间戳 | 同上；自定义音色保留原激活同意流程 | 合成同上，音色训练/激活另沿原确认路径 | 已接；[官方](https://docs.volcengine.com/docs/DoubaoVoice/unidirectional-streaming-text-to-speech-http?lang=zh) |
+| KIE Eleven v3 对话 | createTask / recordInfo | 当前接口未声明 | resultJson.resultUrls，未见时间戳 | 正常合成计费 | 未接；[官方](https://docs.kie.ai/market/elevenlabs/text-to-dialogue-v3) |
+| Fal Eleven v3 | Fal queue elevenlabs/tts/eleven-v3 | 声明支持词级；输出类型仅 list<void> | `timestamps=true`；输出 `timestamps`，条目字段/时间单位未定义 | 未找到开关附加费用说明 | 暂未接，缺条目契约；[官方](https://fal.ai/models/fal-ai/elevenlabs/tts/eleven-v3/api) |
+| Fal Qwen3 TTS 1.7B | Fal queue qwen-3-tts/text-to-speech/1.7b | 当前接口未声明 | 输出 audio | 正常合成计费 | 未接；[官方](https://fal.ai/models/fal-ai/qwen-3-tts/text-to-speech/1.7b/api) |
+| 硅基流动 CosyVoice2 | POST /v1/audio/speech，非流式音频 | 未声明 | 二进制音频，未见时间戳元数据 | 正常合成计费 | 未接；[官方](https://docs.siliconflow.cn/docs/api/audio-speech-post) |
+| 硅基流动 MOSS-TTSD v0.5 | 同上 | 未声明 | 同上 | 正常合成计费 | 未接；[官方](https://docs.siliconflow.cn/docs/api/audio-speech-post) |
+| KIE Gemini 3.1 Flash TTS | createTask / recordInfo | 当前接口未声明 | resultJson.resultUrls | 正常合成计费 | 未接；[官方](https://docs.kie.ai/market/google/gemini-3-1-flash-tts) |
+| 补查：KIE Eleven Turbo 2.5 | createTask / recordInfo | 输入示例有 timestamps，但 resultJson 未说明时间戳载荷 | `input.timestamps`，无可核实返回条目 | 附加费未明确 | 未接；[官方](https://docs.kie.ai/market/elevenlabs/text-to-speech-turbo-2-5) |
+
+## 公共结果契约
+
+SDK 返回 `metadata.outputTimings: GenerationOutputTimings`，数组项为 `{ outputIndex, timings: { granularity: 'char' | 'word' | 'sentence', items: [{ text, startMs, endMs, confidence? }] } }`。outputIndex 对应输出媒体序号，时间是源音频毫秒；confidence 为供应商可选的 0–1 数值。没有时间戳时省略，不能把空音频或非法区间伪装成可用结果。火山当前单音频输出序号为 0，按流帧收集 `sentence.words`，保留原音频拼接路径；非法时间拒绝并取消响应流，不重发生成。
+
+Seed-TTS / ICL 的 catalog 自动开启字幕并声明 `timestamps` 标签，宿主模型 schema 和搜索沿同一 meta.tags 投影。只覆盖合成，不为音色训练伪造字幕。仅中英文的官方限制仍成立。
+
+官方响应 fixture：`packages/ai-sdk/tests/fixtures/tts/volcengine-subtitle.json`，正文和秒数取自官方示例，音频占位替换为 ID3 三字节；异常 fixture 为测试构造，未冒充线上采样。两模型的请求参数和解析都有精确测试。
+
+## 资料缺口及最小核验
+
+百炼 MiniMax 的公开页声明 subtitle_enable，却没有字幕返回字段；Fal Eleven v3 的返回类型是 list<void>；KIE Turbo 示例开关没有相应结果字段。本次不猜字段名或时间单位，尚未完成这些原生适配。总管理者可先向官方取得带字幕的响应 schema/脱敏响应样本；需付费调用时另行授权。
+
+火山最小合成参数：`{prompt:'你好，语音测试',volcSeedTtsSpeaker:'zh_female_vv_uranus_bigtts'}`。ICL 使用已有已激活音色，`{prompt:'你好，语音测试',volcSeedIclSpeaker:'已有音色ID',volcIclActivationConsent:true}`；此处只是后续测试建议，没有执行。核查跨句时钟是否连续、是否重复 sentence、中英混读标点覆盖和音频实际对齐精度。当前公开文档未给出重复帧与句时钟重置规则，因此不擅自加偏移或去重。
+
+未遇到需要用户登录的资料页面。未切换 Qwen/CosyVoice 到流式或 WebSocket，没有 npm publish。

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

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