@henjicc/ai-sdk 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/CHANGELOG.md +225 -211
  2. package/README.md +2 -2
  3. package/dist/capabilities/speech-recognition/bailian/module.js +29 -14
  4. package/dist/capabilities/speech-recognition/bailian/types.d.ts +2 -0
  5. package/dist/catalog/apimart/gemini-omni-flash.model.js +3 -14
  6. package/dist/catalog/kie/gemini-omni-video.model.js +5 -26
  7. package/dist/catalog/ppio/minimax-speech.model.js +1 -1
  8. package/dist/catalog/volcengine-speech/seed-icl-2.0.model.d.ts +1 -0
  9. package/dist/catalog/volcengine-speech/seed-icl-2.0.model.js +52 -10
  10. package/dist/catalog/volcengine-speech/seed-tts-2.0-voices.d.ts +2 -0
  11. package/dist/catalog/volcengine-speech/seed-tts-2.0-voices.js +438 -0
  12. package/dist/catalog/volcengine-speech/seed-tts-2.0.model.js +2 -2
  13. package/dist/generation/core.d.ts +6 -0
  14. package/dist/generation/core.js +10 -2
  15. package/dist/index.d.ts +5 -0
  16. package/dist/index.js +7 -0
  17. package/dist/providers/volcengine-speech.d.ts +1 -1
  18. package/dist/providers/volcengine-speech.js +9 -3
  19. package/dist/providers/volcengine-voice-clone.d.ts +3 -0
  20. package/dist/providers/volcengine-voice-clone.js +129 -0
  21. package/dist/types/runtime.d.ts +3 -0
  22. package/dist/upload/media-binary.js +1 -0
  23. package/docs/consumers.md +27 -9
  24. package/docs/model-adaptation/Gemini-Omni-Flash/Gemini-Omni-Flash_APIMart.md +1 -0
  25. package/docs/model-adaptation/Gemini-Omni-Flash/Gemini-Omni-Flash_KIE.md +1 -0
  26. package/docs/model-adaptation/README.md +11 -9
  27. package/docs/model-adaptation/Seed-ICL-2.0/Seed-ICL-2.0_/347/201/253/345/261/261/345/274/225/346/223/216.md +65 -0
  28. package/docs/model-adaptation/TTS-/345/244/232/344/276/233/345/272/224/345/225/206-2026-09.md +69 -69
  29. package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/231/276/347/202/274.md +6 -0
  30. package/docs/model-adaptation//346/226/207/346/241/243/351/207/207/351/233/206/346/211/213/345/206/214.md +6 -5
  31. package/package.json +1 -1
package/docs/model-adaptation/TTS-/345/244/232/344/276/233/345/272/224/345/225/206-2026-09.md CHANGED
@@ -1,69 +1,69 @@
1
- # TTS 多供应商适配契约（2026-09-27）
2
-
3
- 本文件记录本次 SDK 适配所需的供应商原始契约。范围限定为文字转语音和对话语音；声音训练、音乐生成不在本次模型清单内。用户确认：公开价格可核实时显示估算；无法由输入参数可靠估算的价格不显示估算。
4
-
5
- ## 模型与请求矩阵
6
-
7
- | 平台 | 模型 / 路由 | 协议、输出 | 公开价格 | 官方依据 |
8
- | --- | --- | --- | --- | --- |
9
- | 派欧云 | 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) |
10
- | 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) |
11
- | 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) |
12
- | 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) |
13
- | 百炼 | `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) |
14
- | 百炼 | `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) |
15
- | 百炼 | `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) |
16
- | 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) |
17
- | 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) |
18
- | 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) |
19
- | 火山引擎 | `seed-tts-2.0`、`seed-icl-2.0` | V3 HTTP Chunked；逐帧 JSON 的 `data` 为 base64 音频块 | 资源包有公开价；按量单价仍需进一步核实，暂不显示预估 | [V3 HTTP](https://docs.volcengine.com/docs/DoubaoVoice/unidirectional-streaming-text-to-speech-http?lang=zh)、[产品价格入口](https://docs.volcengine.com/docs/DoubaoVoice?lang=zh) |
20
- | 硅基流动 | `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) |
21
-
22
- 百炼的专属业务空间域名为推荐项，官方明确现有 `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)。
23
-
24
- ## 事件与终态契约
25
-
26
- | 协议 | 前置/中间状态 | 成功终态与输出 | 失败/空值处理 | 断线、取消和复用 |
27
- | --- | --- | --- | --- | --- |
28
- | Fal queue | 提交返回 `request_id` 或 `status_url`；状态 `IN_QUEUE` / `IN_PROGRESS` | `COMPLETED` 后取 `response_url`，要求 `audio.url` | `FAILED`、无结果 URL 报错；状态字段缺失报错 | 中断信号取消本地等待；远端任务是否被取消，官方未说明。状态 URL 限定 Fal queue 域名。 |
29
- | KIE jobs | 创建返回 `data.taskId`；查询 `waiting` / `queuing` / `generating` | `success`，解析 `data.resultJson.resultUrls` | `fail` 或查询错误报错；空结果报错 | 中断信号取消本地等待；远端任务取消/恢复官方未说明。 |
30
- | 百炼非流式 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 处理。 |
31
- | 火山 V3 HTTP Chunked | 一次提交，分块读取 JSON；每个 `code=0` 的非空 `data` 是音频块 | 完整读取至服务端终止，按原序拼接全部音频块；`usage.text_words` 为计费字符 | `code!=0` 报错；无音频块报错；未完整终止不得产出音频 | 中断信号终止读取并释放 reader；断线不重放付费请求。帧乱序/断线恢复官方未说明。 |
32
- | 硅基流动 HTTP | 单次请求 | 2xx 且非空音频二进制 | 非 2xx 或空 body 报错 | 中断 HTTP 请求；无任务轮询。 |
33
-
34
- 以上只接入各平台已证实的非流式完整结果路径。Fal 本身的 streaming 和百炼 SSE 属于另外的可选协议，不因页面支持 streaming 就默认在本次实现中启用。官方示例中的占位音频与签名 URL 只用于字段契约 fixture，不能据此宣称真实付费生成成功。
35
-
36
- ### 火山 V3 分块事件矩阵
37
-
38
- 官方把每个 HTTP 分块描述为 JSON 消息；HTTP 读取边界可能拆开或合并 JSON 消息，因此 SDK 按完整 JSON 对象切帧。`code` 为必填数字，`data` 为可选 base64 音频字符串，`usage.text_words` 为可选数字；空 `data` 或缺失 `data` 不产生音频。官方未说明帧乱序、重复、断线恢复或远端任务取消语义，SDK 不对付费 POST 自动重放。
39
-
40
- | 事件/状态 | 前置状态 | 字段契约（required / optional / nullable） | 空值/缺字段语义 | 下一状态 | 对外输出 | 副作用 | 终态/错误 | 连接复用 |
41
- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
42
- | 成功音频帧 `code=0` | 请求已提交、流读取中 | `code: number` 必填；`data: string` 可选；`usage.text_words: number` 可选 | 空/缺 `data` 无音频；`null` 不是可解码音频 | 继续读取 | 累积音频块和最近一次用量 | base64 解码、顺序追加 | 非终态 | 继续读取同一响应 |
43
- | 服务错误帧 `code!=0` | 流读取中 | `code: number` 必填；`message: string` 可选 | 缺 `message` 使用通用错误 | 失败 | 错误 | 释放 reader | 错误终态 | 不复用该响应 |
44
- | 正常 EOF | 流读取中 | 无新的 JSON 字段 | 尚有不完整 JSON 为无效响应；全程无有效音频为空结果 | 完成或失败 | 单个音频 data URI | 拼接所有音频块、释放 reader | 本地终态；官方未提供单独 final 字段 | 请求结束 |
45
- | 中断或断线 | 流读取中 | `AbortSignal` 或 HTTP 读取故障 | 不交付部分音频 | 失败/取消 | 原因错误 | 取消并释放 reader | 本地终态；断线能否恢复官方未说明 | 不重放写请求 |
46
-
47
- 状态机不变量：只有正常 EOF 且至少一个非空音频块才能成功；空中间帧可重复；帧中的 JSON 字符串可跨网络分块；错误或取消后不得返回已经累积的部分音频。正常、失败及取消均释放 reader。Fal/KIE 的既有 queue/jobs 状态机沿用原适配器，新增模型仅提供官方 model ID、请求构建和媒体输出字段，不新增轮询协议分支。
48
-
49
- ## 参数边界
50
-
51
- ### 音色目录与账号音色查询（2026-09-27 核对）
52
-
53
- | 模型范围 | 官方音色来源 | 接入方式与边界 |
54
- | --- | --- | --- |
55
- | 百炼 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。 |
56
- | 百炼 CosyVoice 3.5 | [复刻音色列表 API](https://help.aliyun.com/en/model-studio/voice-clone-design-http-api) | 同上。无预置音色；只呈现 `cosyvoice-v3.5-` 前缀且状态为 `OK` 的音色。 |
57
- | 百炼 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 时仅保留本模型已证实默认音色，不借用其他供应商目录。 |
58
- | 硅基流动 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` 数组；实测前不声称所有账号响应形态均已验证。 |
59
- | 火山 Seed-TTS 2.0 | [官方音色清单](https://docs.volcengine.com/docs/DoubaoVoice/Tonelist-1?lang=zh) | 2026-09-27 页面去重后 230 个音色 ID，本地提供搜索和选择。 |
60
- | 火山 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 凭据/协议不一致，未接入。暂保留手填复刻音色 ID。 |
61
- | 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 直接当成转售渠道的可用列表。 |
62
-
63
- 上述音色查询均为单次 HTTP JSON 读请求，官方没有流式事件、取消远端任务、分页总数或连接复用的特殊契约；HTTP 失败、供应商错误码、响应外壳缺失都应报错，不把错误当成空目录。分页仅用于百炼 `list_voice`，遇不足一页时结束；到达客户端有界页数仍满页时应提示目录未完整读取。自定义音色的名称若官方只返回 ID，则展示 ID。
64
-
65
- - 各模型的文本来自 SDK 统一 `prompt`/`text` 输入，转换到供应商要求的 `prompt`、`text` 或嵌套 `input.text`。
66
- - 音色使用各平台官方音色 ID；复刻音色仅允许已在供应商侧取得的 ID，不在本次为训练/上传建立新流程。
67
- - KIE Gemini 3.1 使用 `speakers[]` 与 `dialogue_turns[]`；Eleven v3 对话使用 `dialogue[]`。SDK 在仅有普通文本时明确构建单说话人/单台词数组；调用方传入结构化数组时保留多说话人能力。痕迹AI 当前通用参数面板只暴露单说话人文本入口。
68
- - 音频块和二进制响应在 SDK 边界转换为 `data:audio/...;base64,...`，交给宿主已有媒体落盘边界；不得只返回原始 base64/hex 字符串。
69
- - 派欧云 2.8 的 `emotion`：MiniMax 原厂说明支持情感，但派欧云异步参考页写为仅 2.6/01 生效。平台契约冲突，不能将原厂能力直接视为派欧云 2.8 能力；需在该平台屏蔽未证实的情感选项。[派欧云异步 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async)。
1
+ # TTS 多供应商适配契约（2026-09-27）
2
+
3
+ 本文件记录本次 SDK 适配所需的供应商原始契约。原始范围为文字转语音和对话语音；2026-09-28 补充 Seed-ICL 2.0 官方 V3 声音训练，详见 [语音克隆契约](Seed-ICL-2.0/Seed-ICL-2.0_火山引擎.md)。用户确认：公开价格可核实时显示估算；无法由输入参数可靠估算的价格不显示估算。
4
+
5
+ ## 模型与请求矩阵
6
+
7
+ | 平台 | 模型 / 路由 | 协议、输出 | 公开价格 | 官方依据 |
8
+ | --- | --- | --- | --- | --- |
9
+ | 派欧云 | 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) |
10
+ | 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) |
11
+ | 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) |
12
+ | 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) |
13
+ | 百炼 | `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) |
14
+ | 百炼 | `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) |
15
+ | 百炼 | `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) |
16
+ | 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) |
17
+ | 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) |
18
+ | 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) |
19
+ | 火山引擎 | `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) |
20
+ | 硅基流动 | `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) |
21
+
22
+ 百炼的专属业务空间域名为推荐项，官方明确现有 `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)。
23
+
24
+ ## 事件与终态契约
25
+
26
+ | 协议 | 前置/中间状态 | 成功终态与输出 | 失败/空值处理 | 断线、取消和复用 |
27
+ | --- | --- | --- | --- | --- |
28
+ | Fal queue | 提交返回 `request_id` 或 `status_url`；状态 `IN_QUEUE` / `IN_PROGRESS` | `COMPLETED` 后取 `response_url`，要求 `audio.url` | `FAILED`、无结果 URL 报错；状态字段缺失报错 | 中断信号取消本地等待；远端任务是否被取消，官方未说明。状态 URL 限定 Fal queue 域名。 |
29
+ | KIE jobs | 创建返回 `data.taskId`；查询 `waiting` / `queuing` / `generating` | `success`，解析 `data.resultJson.resultUrls` | `fail` 或查询错误报错；空结果报错 | 中断信号取消本地等待；远端任务取消/恢复官方未说明。 |
30
+ | 百炼非流式 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 处理。 |
31
+ | 火山 V3 HTTP Chunked | 一次提交，分块读取 JSON；每个 `code=0` 的非空 `data` 是音频块 | 完整读取至服务端终止，按原序拼接全部音频块；`usage.text_words` 为计费字符 | `code!=0` 报错；无音频块报错；未完整终止不得产出音频 | 中断信号终止读取并释放 reader；断线不重放付费请求。帧乱序/断线恢复官方未说明。 |
32
+ | 硅基流动 HTTP | 单次请求 | 2xx 且非空音频二进制 | 非 2xx 或空 body 报错 | 中断 HTTP 请求；无任务轮询。 |
33
+
34
+ 以上只接入各平台已证实的非流式完整结果路径。Fal 本身的 streaming 和百炼 SSE 属于另外的可选协议，不因页面支持 streaming 就默认在本次实现中启用。官方示例中的占位音频与签名 URL 只用于字段契约 fixture，不能据此宣称真实付费生成成功。
35
+
36
+ ### 火山 V3 分块事件矩阵
37
+
38
+ 官方把每个 HTTP 分块描述为 JSON 消息；HTTP 读取边界可能拆开或合并 JSON 消息，因此 SDK 按完整 JSON 对象切帧。`code` 为必填数字，`data` 为可选 base64 音频字符串，`usage.text_words` 为可选数字；空 `data` 或缺失 `data` 不产生音频。官方未说明帧乱序、重复、断线恢复或远端任务取消语义，SDK 不对付费 POST 自动重放。
39
+
40
+ | 事件/状态 | 前置状态 | 字段契约（required / optional / nullable） | 空值/缺字段语义 | 下一状态 | 对外输出 | 副作用 | 终态/错误 | 连接复用 |
41
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- |
42
+ | 成功音频帧 `code=0` | 请求已提交、流读取中 | `code: number` 必填；`data: string` 可选；`usage.text_words: number` 可选 | 空/缺 `data` 无音频；`null` 不是可解码音频 | 继续读取 | 累积音频块和最近一次用量 | base64 解码、顺序追加 | 非终态 | 继续读取同一响应 |
43
+ | 服务错误帧 `code!=0` | 流读取中 | `code: number` 必填；`message: string` 可选 | 缺 `message` 使用通用错误 | 失败 | 错误 | 释放 reader | 错误终态 | 不复用该响应 |
44
+ | 正常 EOF | 流读取中 | 无新的 JSON 字段 | 尚有不完整 JSON 为无效响应；全程无有效音频为空结果 | 完成或失败 | 单个音频 data URI | 拼接所有音频块、释放 reader | 本地终态；官方未提供单独 final 字段 | 请求结束 |
45
+ | 中断或断线 | 流读取中 | `AbortSignal` 或 HTTP 读取故障 | 不交付部分音频 | 失败/取消 | 原因错误 | 取消并释放 reader | 本地终态；断线能否恢复官方未说明 | 不重放写请求 |
46
+
47
+ 状态机不变量：只有正常 EOF 且至少一个非空音频块才能成功；空中间帧可重复；帧中的 JSON 字符串可跨网络分块；错误或取消后不得返回已经累积的部分音频。正常、失败及取消均释放 reader。Fal/KIE 的既有 queue/jobs 状态机沿用原适配器，新增模型仅提供官方 model ID、请求构建和媒体输出字段，不新增轮询协议分支。
48
+
49
+ ## 参数边界
50
+
51
+ ### 音色目录与账号音色查询（2026-09-27 核对）
52
+
53
+ | 模型范围 | 官方音色来源 | 接入方式与边界 |
54
+ | --- | --- | --- |
55
+ | 百炼 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。 |
56
+ | 百炼 CosyVoice 3.5 | [复刻音色列表 API](https://help.aliyun.com/en/model-studio/voice-clone-design-http-api) | 同上。无预置音色；只呈现 `cosyvoice-v3.5-` 前缀且状态为 `OK` 的音色。 |
57
+ | 百炼 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 时仅保留本模型已证实默认音色，不借用其他供应商目录。 |
58
+ | 硅基流动 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` 数组；实测前不声称所有账号响应形态均已验证。 |
59
+ | 火山 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 代替。 |
60
+ | 火山 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 训练和状态查询；新音色自动编号并保存到应用音色库，已有预付费槽位可手动导入。 |
61
+ | 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 直接当成转售渠道的可用列表。 |
62
+
63
+ 上述音色查询均为单次 HTTP JSON 读请求，官方没有流式事件、取消远端任务、分页总数或连接复用的特殊契约；HTTP 失败、供应商错误码、响应外壳缺失都应报错，不把错误当成空目录。分页仅用于百炼 `list_voice`，遇不足一页时结束；到达客户端有界页数仍满页时应提示目录未完整读取。自定义音色的名称若官方只返回 ID，则展示 ID。
64
+
65
+ - 各模型的文本来自 SDK 统一 `prompt`/`text` 输入，转换到供应商要求的 `prompt`、`text` 或嵌套 `input.text`。
66
+ - 音色使用各平台官方音色 ID；火山 Seed-ICL 支持直接上传录音克隆；其他供应商复刻音色使用官方列表或已取得的 ID。
67
+ - KIE Gemini 3.1 使用 `speakers[]` 与 `dialogue_turns[]`；Eleven v3 对话使用 `dialogue[]`。SDK 在仅有普通文本时明确构建单说话人/单台词数组；调用方传入结构化数组时保留多说话人能力。痕迹AI 当前通用参数面板只暴露单说话人文本入口。
68
+ - 音频块和二进制响应在 SDK 边界转换为 `data:audio/...;base64,...`，交给宿主已有媒体落盘边界；不得只返回原始 base64/hex 字符串。
69
+ - 派欧云 2.8 的 `emotion`：MiniMax 原厂说明支持情感，但派欧云异步参考页写为仅 2.6/01 生效。平台契约冲突，不能将原厂能力直接视为派欧云 2.8 能力；需在该平台屏蔽未证实的情感选项。[派欧云异步 HD](https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async)。
package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/231/276/347/202/274.md CHANGED
@@ -280,3 +280,9 @@ Qwen-MT 可通过 OpenAI 兼容 `POST /compatible-mode/v1/chat/completions` 或
280
280
  |空 final 或全程无 final|任务已开始|sentence_end=true 但无文字，或 task-finished 前无 final|仍拒绝空结果|失败并释放连接|
281
281
 
282
282
  fixture `asr-realtime-fun.json.emptyIntermediate` 是实测脱敏结构。共享 Fun Duplex parser 的两个 Fun-ASR ID 与 Qwen-Audio 3.1 streaming 均沿同一规则；Qwen Realtime 独立解析器不受影响。
283
+
284
+ ### 2026-09-28 文件转写恢复查询
285
+
286
+ `BailianAsrOptions.resumeTaskId` 仅用于异步文件转写：有任务 ID 时直接 GET `/tasks/{task_id}`，跳过媒体读取、上传及 POST 提交。任务状态仍沿用 PENDING/RUNNING → SUCCEEDED/FAILED 的既有状态机；超时、取消和鉴权失败不重提任务。短音频协议拒绝恢复输入。官方未保证任务及结果永久保存；过期须返回失败，由调用方决定是否重新付费识别。
287
+
288
+ 依据：<https://help.aliyun.com/zh/model-studio/fun-asr-recorded-speech-recognition-http-api>（2026-09-28 核对，公开）。复用 `asr-file-running/succeeded/failed/result.json` 官方脱敏 fixture；测试覆盖仅查询、不读媒体、不提交、失败终态、取消与非法恢复 ID。
package/docs/model-adaptation//346/226/207/346/241/243/351/207/207/351/233/206/346/211/213/345/206/214.md CHANGED
@@ -285,7 +285,8 @@ Henji-AI 是 `@henjicc/ai-sdk` 的主开发仓库与首发验证宿主。新模
285
285
  | 状态 | 权威来源 | 允许的依赖/包形态 | 必须证明什么 |
286
286
  |---|---|---|---|
287
287
  | 开发态与首发验证 | Henji-AI 的 `packages/ai-sdk` | 仓内 workspace 源码、构建产物、由当前源码生成的本地 tarball | 源码改动、公共导出、类型、可移植性、打包内容与宿主集成正确 |
288
- | 待发布/正式发布 | 当前版本生成的 npm 包 | `npm pack` 产物用于发布前回装；正式包只发布到公共 npm registry | tarball 内容等于待发布版本；完整改动已通过发布门禁及消费者影响核查，按持续授权自主发布；公共 registry 可匿名读取 |
288
+ | 待用户测试 | 已接入 SDK 改动的 Henji-AI | 仓内 workspace 源码与应用构建产物 | Agent 完成必要检查并交给用户实际测试；不得自动发布 |
289
+ | 待发布/正式发布 | 用户明确要求发布的版本所生成的 npm 包 | `npm pack` 产物用于发布前回装；正式包只发布到公共 npm registry | 用户测试确认没问题且明确要求发版；tarball 内容等于待发布版本；通过发布门禁及消费者影响核查；发布后公共 registry 可匿名读取 |
289
290
  | 外部消费 | 公共 npm 上已经发布的不可变版本 | `@henjicc/ai-sdk` 精确版本及对应 lockfile resolved/integrity | 在没有 Henji-AI workspace、源码旁路和用户 npm/GitHub 凭据时仍能安装、导入和运行所需入口 |
290
291
 
291
292
  硬性边界：
@@ -293,15 +294,15 @@ Henji-AI 是 `@henjicc/ai-sdk` 的主开发仓库与首发验证宿主。新模
293
294
  1. Henji-AI 之外的仓库一律视为外部消费者，只能从 `https://registry.npmjs.org/` 安装已发布版本。禁止使用 `workspace:`、`file:`、Git URL、GitHub Packages、源码复制、软链接或手工 tarball 路径作为正式依赖。
294
295
  2. 外部消费者的 manifest 必须写精确版本，不使用 `^`、`~`、`latest` 等浮动范围；lockfile 必须解析到公共 npm tarball，并保存与正式包一致的 integrity。Henji-AI 根 manifest 虽然也声明精确版本，但仓内可能由 npm workspace 解析到本地源码，因此不能拿本仓的安装结果替代仓外验证。
295
296
  3. 消费项目需要尚未发布的能力时，先在 Henji-AI 完成官方资料、实现、契约测试、SDK 全量门禁、打包和回装；正式发布后，消费项目再升级。禁止先在消费方复制 provider/parser/transport 内核或长期 patch SDK。
296
- 4. **用户已持续授权 Agent 自主发布 `@henjicc/ai-sdk`，无需逐次确认。** 一组完整 SDK 功能或修复完成后，应完成版本升级、变更说明和发布门禁，再自主发布到公共 npm；不能只提交源码或重建本地 dist 就声称外部消费者已获得更新。具体要求：
297
- - **发布单位**：可独立验证的一组完整改动，不为每次小编辑发版本。影响 SDK 对外功能、请求契约、兼容性或可消费产物的改动进入发布流程；仅痕迹AI界面、规则、文档或测试调整不触发发布。用户明确要求暂缓某次发布时遵从该要求。
297
+ 4. **先接入痕迹AI，交给用户测试，收到明确发版指令后才发布 `@henjicc/ai-sdk`。原有自主发布的持续授权已撤销。** 每次 SDK 功能或修复都先完成仓内接入和必要检查，将可测试的应用交给用户；用户测试确认没问题并明确要求发版后，再确定版本、更新变更说明、完成发布门禁并发布到公共 npm。自动测试或 CI 通过不能代替用户测试与发布指令；不能只提交源码或重建本地 dist 就声称外部消费者已获得更新。具体要求：
298
+ - **发布单位**：用户明确要求发布的、可独立验证的一组完整改动，不为每次小编辑发版本。影响 SDK 对外功能、请求契约、兼容性或可消费产物的改动可以先在痕迹AI 中累计测试；仅痕迹AI界面、规则、文档或测试调整不触发发布。未收到发布指令时保持待用户测试状态，不主动催促 npm 登录或发布。
298
299
  - **版本级别**：兼容性修复升级 patch，兼容性新增能力升级 minor；删除公共入口、改变参数含义或其他破坏性变更不得作为 patch 发布。稳定版破坏性变更升级 major，`0.x` 阶段升级 minor，并写明迁移方法。
299
300
  - **发布前核查**：读取 [消费项目清单](../consumers.md)，核对公共导出和请求/响应契约的实际使用；破坏性变更先确认可行的迁移路径，必要时提供过渡入口。关键兼容性影响尚不明确或发布门禁失败时，先解决并报告阻塞，不以已有授权绕过验证，也不把重新询问发布许可当成修复手段。
300
301
  - **发布验证**：完成本手册要求的 SDK 全量门禁、候选 tarball 打包回装和 Henji-AI 首发验证；确认对应发布提交的必需 CI 门禁通过。版本号、包内容与已验证源码必须一致，发布内容不得夹带其他任务未验证的改动。
301
302
  - **发布后同步**：按第 5、8 条完成公共 registry 匿名安装验证，并只升级实际需要新能力或修复的消费者；不要求所有项目机械追随每个新版本。报告已发布版本、验证结果、消费者升级情况及尚未验证的部分。
302
- - **授权边界**：本授权针对 SDK 公共 npm 发布，不自动授权真实付费生成、改换分发渠道、绕过权限或改写远端历史。遇到必须由用户完成的 2FA 或凭据操作时，仅请求该必要协助，不重复询问是否允许发布。
303
+ - **授权边界**：用户的明确发布指令只覆盖该次 SDK 公共 npm 发布，不自动授权以后每次发布，也不授权真实付费生成、改换分发渠道、绕过权限或改写远端历史。用户完成登录或 2FA 不等于要求发布；收到该次发布指令后，才请求必要的凭据协助，已有明确指令时不重复询问发布许可。
303
304
  5. 发布前用当前源码产生唯一候选 tarball并完成本地回装；发布后必须在仓外临时目录移除项目级 workspace 影响和用户 npm/GitHub 凭据，从公共 npm 重新安装，核对包名、版本、公开入口和实际所需 bundle。只有这一步通过，才能称为“别人可以直接安装”。
304
- 6. npm 返回 2FA、token 或权限错误时，只修复公共 npm 的鉴权；不得改用私有 registry、GitHub Packages 或源码安装绕过。若发布结果不确定，先查询公共 registry：版本已存在就按 npm 不可变原则发布新版本，版本不存在才重试原版本。
305
+ 6. 收到明确发布指令后，若 npm 返回 2FA、token 或权限错误，只修复公共 npm 的鉴权；不得改用私有 registry、GitHub Packages 或源码安装绕过。若发布结果不确定，先查询公共 registry：版本已存在就核实该次发布结果，不盲目发布新版本，版本不存在才重试原版本。
305
306
  7. GitHub Packages 只可作为历史记录，不再发布新版本，也不得在消费项目新增 `@henjicc` scope 的 GitHub registry 映射。历史包是否删除不影响公共 npm 消费链路。
306
307
  8. 正式发布并通过仓外验证后，读取 [消费项目清单](../consumers.md)，只升级实际受影响的消费者，逐个记录精确版本、integrity、同步 commit、宿主边界与验证结果。
307
308
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@henjicc/ai-sdk",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "痕迹AI 多供应商模型适配 SDK",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {