@henjicc/ai-sdk 0.2.8 → 0.3.0

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

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