@henjicc/ai-sdk 0.8.0 → 0.10.0

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

@@ -1,282 +1,339 @@
-# 阿里云百炼 · 供应商基础文档
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 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 标注来源，覆盖成功、失败、取消、超时和畸形响应。
-
-## 2026-09-21 文件 ASR 上传边界
-
-官方依据：[临时上传](https://help.aliyun.com/zh/model-studio/get-temporary-file-url)、[Qwen Base64](https://help.aliyun.com/zh/model-studio/qwen-asr-api-reference)、[Fun-ASR Flash HTTP](https://help.aliyun.com/zh/model-studio/fun-asr-flash-recorded-speech-recognition-http-api)、[模型规格](https://help.aliyun.com/zh/model-studio/asr-model/)。均公开无需登录；本次只核对传输及限制，未改变定价与响应协议。
-
-| 阶段 | 输入/约束 | 成功/下一步 | 失败/资源行为 |
-|---|---|---|---|
-| 同步本地预检 | describe 的 size/mime/filename；Qwen 原始≤7,500,000；Fun Flash≤2,000,000,000字节 | 拉取≤48KiB块，Base64余数跨块保留，精确Content-Length | 大小超限带actualBytes/maxBytes/已知时长；不读取正文 |
-| JSON传输 | SDK按需生成UTF-8片段；宿主fetchStream背压消费 | 保持原有SSE或JSON解析 | 取消/短文件/网络错误终止迭代，不自动重放 |
-| 申请上传策略 | GET uploads?action=getPolicy&model；Bearer | 验证HTTPS upload_host及官方表单字段 | 无效策略拒绝，尚未读取文件 |
-| 直传OSS | media-ref交transport.uploadFile；max_file_size_mb接受字段表string及官方示例number | 原生multipart，file最后；上限min(1GB,凭证MB)，均按十进制保守换算 | 宿主保持scope与文件身份校验，超限结构化报错，不进入media通道 |
-| 提交/轮询/结果 | oss://及X-DashScope-OssResourceResolve；原有状态契约不变 | 完成转写输出 | 上传失败不提交识别；取消停止轮询，不宣称撤销远端任务 |
-
-实际时长不是仅由文件大小决定；PCM需采样率/声道/位深及payload字节数，压缩格式需要元数据时长，缺失返回null。新契约不自动修复只抛中文字符串的旧RPC桥。官方凭证fixture：tests/fixtures/bailian/asr-upload-policy.json；其余响应复用原有官方ASR fixtures，未生成付费请求。
-
-## 2026-09-24 Qwen-Audio 3.1 ASR
-
-公开官方文档无需登录：[短音频 HTTP](https://help.aliyun.com/zh/model-studio/fun-asr-flash-recorded-speech-recognition-http-api)、[文件转写](https://help.aliyun.com/zh/model-studio/fun-asr-recorded-speech-recognition-http-api)、[实时客户端](https://help.aliyun.com/zh/model-studio/fun-asr-client-events)、[实时服务端](https://help.aliyun.com/zh/model-studio/fun-asr-server-events)。未执行付费请求。
-
-新增 qwen-audio-3.1-asr-flash / -filetrans / -streaming，分别复用 Fun 短音频、异步文件和 duplex WebSocket 契约，不能套用旧 Qwen3 Chat / Realtime API。域名支持宿主注入工作空间 apiBaseUrl / funWebSocketUrl，不猜工作空间 ID。短音频远端文件上限 2 GB / 5 分钟；Base64 文档仍要求编码后 10 MB，内联原始限制 7.5 MB。文件转写≤2 GB / 12h，分离建议≤2h。
-
-| 协议事件 | 字段与状态规则 |
-|---|---|
-| 短音频 JSON / SSE result | output.text 累计文本；sentence 或分离时 sentences 数组；sentence_end:boolean，speaker_id:integer/null，begin_time/end_time 毫秒。短于一分钟可直接返回 JSON，不能强制只读 SSE |
-| 句末 | 合并去重句子，保留 speaker_id；usage.duration 秒，3.1 另有 input/output/total_tokens |
-| HTTP / SSE 错误 | code/message 非成功时抛错；畸形 JSON 或无文本拒绝 |
-| 文件提交/轮询 | input.file_urls:string[]（单文件），parameters 必须传对象；PENDING→RUNNING→SUCCEEDED/FAILED；results[].subtask_status 单独核对，成功读取 transcription_url |
-| WS | run-task→task-started→result-generated→finish-task→task-finished；task-failed 终止；未知事件沿共享状态机处理 |
-| 取消/断连/超时 | 使用 AbortSignal / 共享 WebSocket 生命周期释放；不创建第二个计费任务 |
-
-新增 keepDialect 和即时 vocabulary 参数；实时支持 vadModel。短音频说话人分离发送 speaker_diarization_enabled，文件转写发送 diarization_enabled。文件 channel_id 必须是整数数组，公共单声道选择 channelId 映射为 [channelId]；旧 Qwen3 file_url 契约不改变。短音频 sample_rate 按官方字符串发送，用户上下文 type=input_text。speakerId 作为可选公共输出字段，旧调用兼容。短音频按 tokens 计费，文件与实时不能沿用其 token 单价；未新增不可靠费用计算器。
-
-精确测试复用既有共享异步/实时失败、取消与释放测试，并补充 3.1 JSON/SSE、说话人分离、空 parameters 与新参数路由。样本区分字面与字段构造。
-
-### 2026-09-24 实时空文本中间帧实测补充
-
-以合成语音、合法 `SpeechRecognitionRealtimeStart` 在 SDK 0.6.0 直调 `qwen-audio-3.1-asr-flash-streaming`，复现句首事件之后继续返回 `text=""`、`sentence_end=false`、`end_time=null`、无 `sentence_begin` 的中间帧。官方事件页（https://help.aliyun.com/zh/model-studio/fun-asr-server-events，2026-09-24 核对）说明只有新句首个中间结果包含句首标记；空文本后续帧来自本次实测，并非官方字面示例。
-
-|事件|前置状态|字段与空值|状态/输出|错误与资源|
-|---|---|---|---|---|
-|空文本中间帧|任务已开始|text 是空字符串，sentence_end=false；sentence_begin 可省略，end_time 可为 null|保持会话，继续等待，不产生 partial/final|不关闭连接|
-|缺 text 或缺句子状态的无文本帧|任务已开始|缺字段/类型错误不能等同空字符串|invalid_response|失败并释放连接|
-|空 final 或全程无 final|任务已开始|sentence_end=true 但无文字，或 task-finished 前无 final|仍拒绝空结果|失败并释放连接|
-
-fixture `asr-realtime-fun.json.emptyIntermediate` 是实测脱敏结构。共享 Fun Duplex parser 的两个 Fun-ASR ID 与 Qwen-Audio 3.1 streaming 均沿同一规则；Qwen Realtime 独立解析器不受影响。
+# 阿里云百炼 · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 供应商类型 | 模型原厂/云平台（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 就强行切换。
+
+已接入的异步路由（`providers/bailian.ts` 的 `ASYNC_ROUTES`，提交自动带 `X-DashScope-Async: enable`，其余路由仍同步）：
+
+| 路由 | 模型 | 结果 |
+|---|---|---|
+| `/api/v1/services/aigc/video-generation/video-synthesis` | 万相 3.0（`wan3.0-video` / `wan3.0-video-prime`） | `output.video_url`；失败读 `output.code/message`；`UNKNOWN` 计入连续查询失败 |
+
+## 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；视频、音频经 `upload/bailian-oss-upload.ts` 按请求的 model 申请凭证上传成 `oss://`（与语音识别共用一份实现），请求体含 `oss://` 时提交自动带 `X-DashScope-OssResourceResolve: enable` |
+| 异步任务 | 已接入万相 3.0（未真实付费验证） | 按路由白名单区分异步；参考视频、参考音频经临时存储上传 |
+| 余额查询 | 暂缓 | 避免引入云账号 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 标注来源，覆盖成功、失败、取消、超时和畸形响应。
+
+## 2026-09-21 文件 ASR 上传边界
+
+官方依据：[临时上传](https://help.aliyun.com/zh/model-studio/get-temporary-file-url)、[Qwen Base64](https://help.aliyun.com/zh/model-studio/qwen-asr-api-reference)、[Fun-ASR Flash HTTP](https://help.aliyun.com/zh/model-studio/fun-asr-flash-recorded-speech-recognition-http-api)、[模型规格](https://help.aliyun.com/zh/model-studio/asr-model/)。均公开无需登录；本次只核对传输及限制，未改变定价与响应协议。
+
+| 阶段 | 输入/约束 | 成功/下一步 | 失败/资源行为 |
+|---|---|---|---|
+| 同步本地预检 | describe 的 size/mime/filename；Qwen 原始≤7,500,000；Fun Flash≤2,000,000,000字节 | 拉取≤48KiB块，Base64余数跨块保留，精确Content-Length | 大小超限带actualBytes/maxBytes/已知时长；不读取正文 |
+| JSON传输 | SDK按需生成UTF-8片段；宿主fetchStream背压消费 | 保持原有SSE或JSON解析 | 取消/短文件/网络错误终止迭代，不自动重放 |
+| 申请上传策略 | GET uploads?action=getPolicy&model；Bearer | 验证HTTPS upload_host及官方表单字段 | 无效策略拒绝，尚未读取文件 |
+| 直传OSS | media-ref交transport.uploadFile；max_file_size_mb接受字段表string及官方示例number | 原生multipart，file最后；上限min(1GB,凭证MB)，均按十进制保守换算 | 宿主保持scope与文件身份校验，超限结构化报错，不进入media通道 |
+| 提交/轮询/结果 | oss://及X-DashScope-OssResourceResolve；原有状态契约不变 | 完成转写输出 | 上传失败不提交识别；取消停止轮询，不宣称撤销远端任务 |
+
+实际时长不是仅由文件大小决定；PCM需采样率/声道/位深及payload字节数，压缩格式需要元数据时长，缺失返回null。新契约不自动修复只抛中文字符串的旧RPC桥。官方凭证fixture：tests/fixtures/bailian/asr-upload-policy.json；其余响应复用原有官方ASR fixtures，未生成付费请求。
+
+## 2026-11-07 Qwen-Audio 3.0 ASR与新模型盘点
+
+公开官方文档无需登录：[语音识别选型](https://help.aliyun.com/zh/model-studio/asr-model)、[Qwen-Audio-ASR HTTP API](https://help.aliyun.com/zh/model-studio/qwen-audio-asr-http-api)、[Qwen-Audio-ASR-Filetrans HTTP API](https://help.aliyun.com/zh/model-studio/qwen-audio-asr-filetrans-http-api)、[模型调用计费](https://help.aliyun.com/zh/model-studio/model-pricing)。未执行付费请求。
+
+新增 `qwen-audio-3.0-asr-flash` / `-filetrans` / `-streaming`。官方把 3.0 与 3.1 放在同一组接口文档里，请求结构、轮询与事件相同，差别是：
+
+| 项目 | 3.1 | 3.0 |
+|---|---|---|
+| 计费 | 按输入、输出 Token（短音频与文件 0.8 / 2.7 元/百万 Token；实时 6 / 4.5） | 按输入音频秒数，输出不计费（短音频与文件 0.00022 元/秒；实时 0.00033 元/秒） |
+| `keep_dialect`、`speaker_diarization_enabled`（短音频） | 支持 | 文档标注“仅适用于 qwen-audio-3.1-asr-flash”，不发送 |
+| 文件转写 `keep_dialect` | 支持 | 文档标注“仅 qwen-audio-3.1-asr-flash-filetrans 支持”，不发送 |
+| 即时热词 `vocabulary`、预编译热词 `vocabulary_id` | 支持 | 支持（两份接口文档都没有按版本限制） |
+| 短音频返回 | JSON 或 SSE | 音频不少于 1 分钟时才以 SSE 返回；句末以 `output.sentence.sentence_end` 判断 |
+| usage | 时长 + Token | 仅时长 |
+
+SDK 用预设上的 `supports` 声明哪些参数可发，3.0 预设不带 3.1 专属参数。3.0 实时版是否支持 `vad_model` 等 3.1 新参数未见说明，同样不发送。
+
+**未适配、等资料或协议工作的模型**：
+
+- `qwen-audio-3.1-asr-flash-message`（6 / 4.5 元/百万 Token）：面向输入法、语音消息的短段实时识别，使用独立的[客户端事件](https://help.aliyun.com/zh/model-studio/qwen-asr-message-client-events)协议，需先整理事件契约矩阵与官方 fixture 才能编码。
+- `paraformer-v2`、`paraformer-realtime-v2`、`fun-asr-flash-8k-realtime` 等 8k 电话场景与旧一代模型：不进预设。
+
+## 2026-09-24 Qwen-Audio 3.1 ASR
+
+公开官方文档无需登录：[短音频 HTTP](https://help.aliyun.com/zh/model-studio/fun-asr-flash-recorded-speech-recognition-http-api)、[文件转写](https://help.aliyun.com/zh/model-studio/fun-asr-recorded-speech-recognition-http-api)、[实时客户端](https://help.aliyun.com/zh/model-studio/fun-asr-client-events)、[实时服务端](https://help.aliyun.com/zh/model-studio/fun-asr-server-events)。未执行付费请求。
+
+新增 qwen-audio-3.1-asr-flash / -filetrans / -streaming，分别复用 Fun 短音频、异步文件和 duplex WebSocket 契约，不能套用旧 Qwen3 Chat / Realtime API。域名支持宿主注入工作空间 apiBaseUrl / funWebSocketUrl，不猜工作空间 ID。短音频远端文件上限 2 GB / 5 分钟；Base64 文档仍要求编码后 10 MB，内联原始限制 7.5 MB。文件转写≤2 GB / 12h，分离建议≤2h。
+
+| 协议事件 | 字段与状态规则 |
+|---|---|
+| 短音频 JSON / SSE result | output.text 累计文本；sentence 或分离时 sentences 数组；sentence_end:boolean，speaker_id:integer/null，begin_time/end_time 毫秒。短于一分钟可直接返回 JSON，不能强制只读 SSE |
+| 句末 | 合并去重句子，保留 speaker_id；usage.duration 秒，3.1 另有 input/output/total_tokens |
+| HTTP / SSE 错误 | code/message 非成功时抛错；畸形 JSON 或无文本拒绝 |
+| 文件提交/轮询 | input.file_urls:string[]（单文件），parameters 必须传对象；PENDING→RUNNING→SUCCEEDED/FAILED；results[].subtask_status 单独核对，成功读取 transcription_url |
+| WS | run-task→task-started→result-generated→finish-task→task-finished；task-failed 终止；未知事件沿共享状态机处理 |
+| 取消/断连/超时 | 使用 AbortSignal / 共享 WebSocket 生命周期释放；不创建第二个计费任务 |
+
+新增 keepDialect 和即时 vocabulary 参数；实时支持 vadModel。短音频说话人分离发送 speaker_diarization_enabled，文件转写发送 diarization_enabled。文件 channel_id 必须是整数数组，公共单声道选择 channelId 映射为 [channelId]；旧 Qwen3 file_url 契约不改变。短音频 sample_rate 按官方字符串发送，用户上下文 type=input_text。speakerId 作为可选公共输出字段，旧调用兼容。短音频按 tokens 计费，文件与实时不能沿用其 token 单价；未新增不可靠费用计算器。
+
+精确测试复用既有共享异步/实时失败、取消与释放测试，并补充 3.1 JSON/SSE、说话人分离、空 parameters 与新参数路由。样本区分字面与字段构造。
+
+### 2026-09-24 实时空文本中间帧实测补充
+
+以合成语音、合法 `SpeechRecognitionRealtimeStart` 在 SDK 0.6.0 直调 `qwen-audio-3.1-asr-flash-streaming`，复现句首事件之后继续返回 `text=""`、`sentence_end=false`、`end_time=null`、无 `sentence_begin` 的中间帧。官方事件页（https://help.aliyun.com/zh/model-studio/fun-asr-server-events，2026-09-24 核对）说明只有新句首个中间结果包含句首标记；空文本后续帧来自本次实测，并非官方字面示例。
+
+|事件|前置状态|字段与空值|状态/输出|错误与资源|
+|---|---|---|---|---|
+|空文本中间帧|任务已开始|text 是空字符串，sentence_end=false；sentence_begin 可省略，end_time 可为 null|保持会话，继续等待，不产生 partial/final|不关闭连接|
+|缺 text 或缺句子状态的无文本帧|任务已开始|缺字段/类型错误不能等同空字符串|invalid_response|失败并释放连接|
+|空 final 或全程无 final|任务已开始|sentence_end=true 但无文字，或 task-finished 前无 final|仍拒绝空结果|失败并释放连接|
+
+fixture `asr-realtime-fun.json.emptyIntermediate` 是实测脱敏结构。共享 Fun Duplex parser 的两个 Fun-ASR ID 与 Qwen-Audio 3.1 streaming 均沿同一规则；Qwen Realtime 独立解析器不受影响。
+
+### 2026-09-28 文件转写恢复查询
+
+`BailianAsrOptions.resumeTaskId` 仅用于异步文件转写：有任务 ID 时直接 GET `/tasks/{task_id}`，跳过媒体读取、上传及 POST 提交。任务状态仍沿用 PENDING/RUNNING → SUCCEEDED/FAILED 的既有状态机；超时、取消和鉴权失败不重提任务。短音频协议拒绝恢复输入。官方未保证任务及结果永久保存；过期须返回失败，由调用方决定是否重新付费识别。
+
+依据：<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。
+
+## 2026-11-08 语音识别价格补全
+
+[模型调用计费](https://help.aliyun.com/zh/model-studio/model-pricing)“语音识别”部分，华北2（北京），无需登录；各模型信息页注明只展示原价、不含限时优惠。
+
+| 模型 | 价格 | 说明 |
+|---|---|---|
+| `qwen-audio-3.1-asr-flash` / `-filetrans` | 输入 0.8、输出 2.7 元/百万 tokens | 按 token 计费，免费额度 100 万 tokens |
+| `qwen-audio-3.1-asr-flash-streaming` | 输入 6、输出 4.5 元/百万 tokens | 同上 |
+| `qwen-audio-3.0-asr-flash` / `-filetrans` | 0.00022 元/秒 | 按输入音频秒数，输出不收费，无免费额度 |
+| `qwen-audio-3.0-asr-flash-streaming` | 0.00033 元/秒 | 同上 |
+| `fun-asr-realtime`、`qwen3-asr-flash-realtime`（含快照） | 0.00033 元/秒 | 复核一致，免费额度 36,000 秒 |
+
+**Qwen-Audio 3.1 的音频折算没有官方比例。** 计费页“千问Audio”（qwen-audio-turbo）与 [Qwen-ASR 接口](https://help.aliyun.com/zh/model-studio/qwen-asr-api-reference)（qwen3-asr-flash）写的是每秒 25 token，Qwen-Audio-Realtime 是每秒 12.5，都不是这个模型。它自己的[短音频接口](https://help.aliyun.com/zh/model-studio/qwen-audio-asr-http-api)与[流式事件](https://help.aliyun.com/zh/model-studio/qwen-audio-asr-streaming-server-events)只说按 token 计费、usage 返回 `input_tokens`，用量示例为 2 秒 85、9 秒 365 输入 token（message 版 2 秒 84），折合每秒约 40–42.5。示例数字明显高于下面的实测，不能直接当音频折算。
+
+2026-11-08 用开发版测试台实调 `qwen-audio-3.1-asr-flash`（系统合成的中文语音，未传上下文，SDK 从 usage 读出 token）：
+
+| 音频时长 | 计费时长 `duration` | `input_tokens` | 识别字数（含标点） | `output_tokens` |
+|---|---|---|---|---|
+| 4.85 秒 | 5 | 61 | 18 | 10 |
+| 30.6 秒 | 31 | 383 | 125 | 62 |
+
+即输入每秒 12.5 token（按实际时长，无固定开销；与 Qwen-Audio-Realtime 公布的每秒 12.5 一致；传上下文文字会另计输入），输出约 0.5–0.56 token/字。`-filetrans` 的查询结果不返回 token 用量，按同一模型同价沿用该比例；流式无法用同一方式实调，按官方流式示例取偏多的每秒 42.5。宿主付费授权据此估算，输出按每秒 6 字、每字 0.5 token：短音频与文件转写约 0.065 元/小时，流式约 0.97 元/小时。