@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/201/253/345/261/261/345/274/225/346/223/216.md

@@ -1,183 +1,191 @@
-# 火山引擎 · 供应商基础文档
-
-## 2026-09-11 文本检索核对
-
-方舟当前 `doubao-embedding-vision-251215` 通过 `POST https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal` 调用，Bearer API Key。SDK 本轮只暴露文本：`input: [{type:"text",text}]`，固定 float，维度 1024/2048；响应 `data.embedding` 是单个融合向量，故每次只接受一条文本，拒绝把多个独立文档合并。usage 使用 prompt_tokens/total_tokens。省略维度时供应商默认 2048。
-
-- [官方接口字段](https://www.volcengine.com/docs/82379/1523520)：HTTP 成功但缺向量、空向量或非数值向量均判错误；HTTP 失败、取消、超时不产生成功结果、不自动重试。
-- [模型使用说明](https://www.volcengine.com/docs/82379/1409291)、[官方价格](https://www.volcengine.com/docs/82379/1544106)：文本输入 0.70 元/百万 tokens，图片 1.80 元/百万 tokens（本入口不收图片）。
-- [官方 OpenViking 配置](https://github.com/volcengine/OpenViking/blob/main/docs/en/guides/01-configuration.md)：VikingDB Rerank 使用 AK/SK，与方舟 Bearer 是不同服务；本轮未实现其签名协议，不宣称火山没有重排模型。
-
-官方页面 HTML 中 MDContent 可读取，浏览器路径本次连接失败。模拟字段 fixture，不是真实付费请求。
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-31 |
-| 供应商类型 | 模型原厂/云平台（方舟 + 豆包语音） |
-| 项目内 `providerId` | `volcengine` |
-| 生成 Base URL | `https://ark.cn-beijing.volces.com/api/v3` |
-| 鉴权 | `Authorization: Bearer <ARK_API_KEY>` |
-| 当前项目范围 | Seedream 同步图片生成与编辑；SeedASR 2.0 文件/实时识别 |
-| 文档/价格可见性 | 公开，无需登录；API Key、用量和账单需登录 |
-
-## 1. 服务面与鉴权边界
-
-火山方舟和豆包语音是同一供应商下的不同服务面，端点、资源 ID 和 API Key 头不能混用。
-
-### 1.1 方舟生成
-
-模型运行时的主 Base URL：
-
-```text
-https://ark.cn-beijing.volces.com/api/v3
-```
-
-火山引擎还提供 `https://ark.cn-beijing.volcengineapi.com/` 用于部分 OpenAPI/HMAC 管理接口，不要与 Bearer API Key 的模型生成 Base URL 混用。
-
-```text
-Authorization: Bearer <ARK_API_KEY>
-Content-Type: application/json
-```
-
-### 1.2 豆包语音 SeedASR 2.0
-
-```text
-文件：https://openspeech.bytedance.com/api/v3/auc/bigmodel/{submit|query}
-实时：wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
-
-X-Api-Key: <Speech API Key>
-X-Api-Resource-Id: <SeedASR 2.0 resource id>
-X-Api-Request-Id: <UUID>
-```
-
-P0 只支持新版控制台的单头 `X-Api-Key`，不要求旧版 `X-Api-App-Key + X-Api-Access-Key`。文件资源 ID 为 `volc.seedasr.auc`，实时小时版为 `volc.seedasr.sauc.duration`。`volc.bigasr.*` 是同页列出的 1.0 资源，不可用于 SeedASR 2.0。
-
-## 2. 图片生成
-
-```text
-POST /api/v3/images/generations
-```
-
-当前 Seedream 5.0 Pro/Lite 使用同一个同步端点，通过 body 的 `model` 区分模型。
-
-### 2.1 输入媒体
-
-`image` 接受单个字符串或字符串数组，可使用：
-
-- 服务端可访问的 HTTP/HTTPS URL。
-- `data:image/<format>;base64,<data>` Data URI，格式名需小写。
-
-因此，当前图片生成不需要先接 Files API。如使用 TOS 私有存储，可生成华北2（`cn-beijing`）内网 GET 预签名 URL，但需确保 TOS 与方舟在同一地域。
-
-### 2.2 结果
-
-`response_format` 官方支持：
-
-| 值 | 结果 |
-|---|---|
-| `url` | `data[].url`，链接在生成后 24 小时内有效 |
-| `b64_json` | `data[].b64_json` |
-
-Henji-AI 当前产品约定不向用户暴露 `output_format`，图片模型固定请求 `url` 以进入统一媒体转存链路。
-
-同步成功后不需要轮询。结果中还可出现 `size`、`output_format`、图层位置和层级信息，按具体模型功能解析。
-
-## 3. Files API 的边界
-
-方舟公共 Files API：
-
-```text
-POST /api/v3/files
-GET  /api/v3/files/{file_id}
-GET  /api/v3/files
-DELETE /api/v3/files/{file_id}
-```
-
-上传支持本地二进制 `file`、HTTP/HTTPS `url` 和 `tos://` URI，返回 File ID。默认托管空间单文件不超过 512 MB；使用用户 TOS 时视频可到 2 GB。默认保留 7 天，`expire_at` 可设为 1–30 天。
-
-但官方当前将 File ID 主要用于 Responses API / Chat API 的多模态理解，不是 `images/generations` 的通用输入字段。因此：
-
-- 不把 `/api/v3/files` 盲目接成 Seedream 图片生成的通用上传。
-- 只有某个生成模型的官方文档明确接受 File ID 时，才在该分支使用。
-- 当前图片生成保持公网 URL/Data URI 方案。
-
-## 4. 视频等异步生成
-
-方舟的视频生成与图片同步接口不是同一个运行契约。接入 Seedance 或其他视频模型前，必须单独核对当前官方文档的提交端点、任务 ID、查询端点、终态和 `usage.completion_tokens`。不复用图片 provider 的“同步必定完成”假设。
-
-## 5. SeedASR 2.0
-
-| 能力 | SDK `modelId` | 端点/协议 | P0 输入 |
-|---|---|---|---|
-| 录音文件识别 | `seedasr-2.0-file` | HTTP submit/query | HTTP(S) 远端 URL；`raw/wav/mp3/ogg` |
-| 双向实时识别 | `seedasr-2.0-realtime` | 二进制 WebSocket | PCM S16LE、16 kHz、16 bit、mono |
-
-### 5.1 文件 submit/query
-
-提交 UUID 同时是 `X-Api-Request-Id` 和后续查询任务 ID；提交成功 body 为空，必须读取 `X-Api-Status-Code`。查询的 `20000001/20000002` 是处理中/排队，`20000000` 才是成功终态；`result.text`、`result.utterances` 和 `audio_info.duration` 归一到统一 ASR 输出。没有官方 P0 取消端点，用户取消只中止本地查询链。
-
-### 5.2 实时二进制协议
-
-首帧、普通音频和最后音频分别使用 type `1/2/2`；服务端完整响应/错误响应为 type `9/15`。JSON 与 PCM 都按当前官方附件 gzip。SDK 保留最后一块真实音频，`finish()` 以负 sequence 发送；取消只关闭 WebSocket，不伪造正常终帧。服务端 `utterances[].definite=true` 是句段 final，整个会话 terminal 以二进制帧 last 标志为准。
-
-严格字段、状态矩阵、附件差异和 fixture 分类分别见两份模型文档：
-
-- `SeedASR-2.0-File/SeedASR-2.0-File_火山引擎.md`
-- `SeedASR-2.0-Realtime/SeedASR-2.0-Realtime_火山引擎.md`
-
-## 6. 计价
-
-火山方舟价格的权威入口是官方模型价格页，未提供一个使用 ARK API Key 查询所有生成模型实时单价的简单公共 API。
-
-| 类型 | 计费 |
-|---|---|
-| 图片 | 按成功输出数量/像素档位；组图按实际成功张数 |
-| 图层拆分 | 各图层可能按实际像素档分别计费 |
-| 视频 | 常见为 token 单价 × token 用量；用量受时长、尺寸、帧率和是否含输入视频影响 |
-
-准确价格以页面最新表格与实际账单为准。文档 API 的 `Result.UpdatedTime` 可用于判断页面时效。
-
-豆包语音当前公开的 SeedASR 2.0 小时版价格与试用：
-
-| 能力 | 后付费 | 免费试用 | 有效期 |
-|---|---:|---:|---|
-| 文件识别 | 0.8 元/小时 | 20 小时 | 开通后 6 个月 |
-| 实时识别（小时版） | 1 元/小时 | 20 小时 | 开通后 6 个月 |
-
-免费试用需要在豆包语音控制台手动开通，不是每月刷新。实时并发版使用另一资源 ID 和计费方式，不能套用小时版价格。
-
-## 7. 余额与用量
-
-方舟有用量统计和 `GetInferenceUsage` 等云 OpenAPI，但这些管理面接口常需火山引擎 AccessKey/SecretKey 签名，不是生成 Bearer API Key 的同一权限。当前不为低优先级余额查询引入云账号高权限。
-
-## 8. 项目当前实现
-
-| 能力 | 状态 | 说明 |
-|---|---|---|
-| Seedream 同步生成 | 已接入 | `providers/volcengine.ts` |
-| 多 URL 结果解析 | 已接入 | 递归收集 `data[]` 等结构 |
-| 本地图片 | 已接入 | 按官方契约转 Data URI |
-| Files API | 不作为图片生成公共上传 | 避免将理解 API 的 File ID 误发给生成 API |
-| 视频异步生成 | 未接入 | 待确定具体方舟视频模型时按官方契约实现 |
-| SeedASR 2.0 文件识别 | 已接入 SDK P0 | 仅远端 URL；submit/query；新版 `X-Api-Key` |
-| SeedASR 2.0 实时识别 | 已接入 SDK P0 | 二进制 WS；固定 PCM S16LE 16 kHz mono |
-| 余额查询 | 暂缓 | 需云账号级签名与权限 |
-
-## 9. 原始链接索引
-
-| 信息 | 链接 | 登录 |
-|---|---|---|
-| Base URL 与鉴权 | https://www.volcengine.com/docs/82379/1298459 | 否 |
-| 图片生成 API | https://www.volcengine.com/docs/82379/1541523 | 否 |
-| 模型价格 | https://www.volcengine.com/docs/82379/1544106 | 否 |
-| Files API 教程 | https://www.volcengine.com/docs/82379/1885708 | 否 |
-| 上传文件 API | https://www.volcengine.com/docs/82379/1870405 | 否 |
-| TOS 内网预签名 URL | https://www.volcengine.com/docs/82379/2551760 | 否 |
-| SeedASR 2.0 文件 API | https://docs.volcengine.com/docs/6561/1354868?lang=zh | 否 |
-| SeedASR 2.0 流式 API/二进制协议 | https://docs.volcengine.com/docs/6561/1354869?lang=zh | 否 |
-| 双向流式优化示例/附件 | https://docs.volcengine.com/docs/6561/2630027?lang=zh | 否 |
-| 豆包语音计费与试用 | https://docs.volcengine.com/docs/6561/1359369?lang=zh | 否 |
-| API Key | https://console.volcengine.com/ark/region:cn-beijing/apiKey | 是 |
-| 豆包语音控制台 | https://console.volcengine.com/speech/new/overview | 是 |
-
-> 火山文档页是 SPA。需要机器可读源文时，可使用官方内容接口：`https://docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=<id>&type=online`。
+# 火山引擎 · 供应商基础文档
+
+## 2026-09-11 文本检索核对
+
+方舟当前 `doubao-embedding-vision-251215` 通过 `POST https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal` 调用，Bearer API Key。SDK 本轮只暴露文本：`input: [{type:"text",text}]`，固定 float，维度 1024/2048；响应 `data.embedding` 是单个融合向量，故每次只接受一条文本，拒绝把多个独立文档合并。usage 使用 prompt_tokens/total_tokens。省略维度时供应商默认 2048。
+
+- [官方接口字段](https://www.volcengine.com/docs/82379/1523520)：HTTP 成功但缺向量、空向量或非数值向量均判错误；HTTP 失败、取消、超时不产生成功结果、不自动重试。
+- [模型使用说明](https://www.volcengine.com/docs/82379/1409291)、[官方价格](https://www.volcengine.com/docs/82379/1544106)：文本输入 0.70 元/百万 tokens，图片 1.80 元/百万 tokens（本入口不收图片）。
+- [官方 OpenViking 配置](https://github.com/volcengine/OpenViking/blob/main/docs/en/guides/01-configuration.md)：VikingDB Rerank 使用 AK/SK，与方舟 Bearer 是不同服务；本轮未实现其签名协议，不宣称火山没有重排模型。
+
+官方页面 HTML 中 MDContent 可读取，浏览器路径本次连接失败。模拟字段 fixture，不是真实付费请求。
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 供应商类型 | 模型原厂/云平台（方舟 + 豆包语音） |
+| 项目内 `providerId` | `volcengine` |
+| 生成 Base URL | `https://ark.cn-beijing.volces.com/api/v3` |
+| 鉴权 | `Authorization: Bearer <ARK_API_KEY>` |
+| 当前项目范围 | Seedream 同步图片生成与编辑；Seedance 2.5 / 2.0 系列异步视频生成；SeedASR 2.0 文件/实时识别 |
+| 文档/价格可见性 | 公开，无需登录；API Key、用量和账单需登录 |
+
+## 1. 服务面与鉴权边界
+
+火山方舟和豆包语音是同一供应商下的不同服务面，端点、资源 ID 和 API Key 头不能混用。
+
+### 1.1 方舟生成
+
+模型运行时的主 Base URL：
+
+```text
+https://ark.cn-beijing.volces.com/api/v3
+```
+
+火山引擎还提供 `https://ark.cn-beijing.volcengineapi.com/` 用于部分 OpenAPI/HMAC 管理接口，不要与 Bearer API Key 的模型生成 Base URL 混用。
+
+```text
+Authorization: Bearer <ARK_API_KEY>
+Content-Type: application/json
+```
+
+### 1.2 豆包语音 SeedASR 2.0
+
+```text
+文件：https://openspeech.bytedance.com/api/v3/auc/bigmodel/{submit|query}
+实时：wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
+
+X-Api-Key: <Speech API Key>
+X-Api-Resource-Id: <SeedASR 2.0 resource id>
+X-Api-Request-Id: <UUID>
+```
+
+P0 只支持新版控制台的单头 `X-Api-Key`，不要求旧版 `X-Api-App-Key + X-Api-Access-Key`。文件资源 ID 为 `volc.seedasr.auc`，实时小时版为 `volc.seedasr.sauc.duration`。`volc.bigasr.*` 是同页列出的 1.0 资源，不可用于 SeedASR 2.0。
+
+## 2. 图片生成
+
+```text
+POST /api/v3/images/generations
+```
+
+当前 Seedream 5.0 Pro/Lite 使用同一个同步端点，通过 body 的 `model` 区分模型。
+
+### 2.1 输入媒体
+
+`image` 接受单个字符串或字符串数组，可使用：
+
+- 服务端可访问的 HTTP/HTTPS URL。
+- `data:image/<format>;base64,<data>` Data URI，格式名需小写。
+
+因此，当前图片生成不需要先接 Files API。如使用 TOS 私有存储，可生成华北2（`cn-beijing`）内网 GET 预签名 URL，但需确保 TOS 与方舟在同一地域。
+
+### 2.2 结果
+
+`response_format` 官方支持：
+
+| 值 | 结果 |
+|---|---|
+| `url` | `data[].url`，链接在生成后 24 小时内有效 |
+| `b64_json` | `data[].b64_json` |
+
+Henji-AI 当前产品约定不向用户暴露 `output_format`，图片模型固定请求 `url` 以进入统一媒体转存链路。
+
+同步成功后不需要轮询。结果中还可出现 `size`、`output_format`、图层位置和层级信息，按具体模型功能解析。
+
+## 3. Files API 的边界
+
+方舟公共 Files API：
+
+```text
+POST /api/v3/files
+GET  /api/v3/files/{file_id}
+GET  /api/v3/files
+DELETE /api/v3/files/{file_id}
+```
+
+上传支持本地二进制 `file`、HTTP/HTTPS `url` 和 `tos://` URI，返回 File ID。默认托管空间单文件不超过 512 MB；使用用户 TOS 时视频可到 2 GB。默认保留 7 天，`expire_at` 可设为 1–30 天。
+
+但官方当前将 File ID 主要用于 Responses API / Chat API 的多模态理解，不是 `images/generations` 的通用输入字段。因此：
+
+- 不把 `/api/v3/files` 盲目接成 Seedream 图片生成的通用上传。
+- 只有某个生成模型的官方文档明确接受 File ID 时，才在该分支使用。
+- 当前图片生成保持公网 URL/Data URI 方案。
+
+## 4. 视频等异步生成
+
+方舟的视频生成与图片同步接口不是同一个运行契约（2026-11-07 已接入 Seedance 2.5 / 2.0 / 2.0 Fast / 2.0 Mini）：
+
+```text
+POST   /api/v3/contents/generations/tasks          → { "id": "cgt-..." }
+GET    /api/v3/contents/generations/tasks/{id}     → status: queued / running / succeeded / failed / cancelled / expired
+DELETE /api/v3/contents/generations/tasks/{id}     → 只能取消 queued 任务
+```
+
+`providers/volcengine.ts` 按路由区分：视频任务路由提交后返回 pending，`continuePolling` 只对该路由查询；图片路由仍同步完成、不支持轮询。成功结果读 `content.video_url`（可选 `content.last_frame_url`），失败读 `error.code/message`。参考视频只收公网 URL / `asset://`，不收 Base64：本地视频经设置里的“通用文件上传服务”（KIE / Fal，按首选与换用设置）托管成公网地址后提交，一家都没配置时提交前提示去设置；图片、音频走 Data URI。完整字段、价格与状态矩阵见 `Seedance-2.5/Seedance-2.5_火山引擎.md` 等模型文档。
+
+## 5. SeedASR 2.0
+
+| 能力 | SDK `modelId` | 端点/协议 | P0 输入 |
+|---|---|---|---|
+| 录音文件识别 | `seedasr-2.0-file` | HTTP submit/query | HTTP(S) 远端 URL；`raw/wav/mp3/ogg` |
+| 双向实时识别 | `seedasr-2.0-realtime` | 二进制 WebSocket | PCM S16LE、16 kHz、16 bit、mono |
+
+### 5.1 文件 submit/query
+
+提交 UUID 同时是 `X-Api-Request-Id` 和后续查询任务 ID；提交成功 body 为空，必须读取 `X-Api-Status-Code`。查询的 `20000001/20000002` 是处理中/排队，`20000000` 才是成功终态；`result.text`、`result.utterances` 和 `audio_info.duration` 归一到统一 ASR 输出。没有官方 P0 取消端点，用户取消只中止本地查询链。
+
+### 5.2 实时二进制协议
+
+首帧、普通音频和最后音频分别使用 type `1/2/2`；服务端完整响应/错误响应为 type `9/15`。JSON 与 PCM 都按当前官方附件 gzip。SDK 保留最后一块真实音频，`finish()` 以负 sequence 发送；取消只关闭 WebSocket，不伪造正常终帧。服务端 `utterances[].definite=true` 是句段 final，整个会话 terminal 以二进制帧 last 标志为准。
+
+严格字段、状态矩阵、附件差异和 fixture 分类分别见两份模型文档：
+
+- `SeedASR-2.0-File/SeedASR-2.0-File_火山引擎.md`
+- `SeedASR-2.0-Realtime/SeedASR-2.0-Realtime_火山引擎.md`
+
+## 6. 计价
+
+火山方舟价格的权威入口是官方模型价格页，未提供一个使用 ARK API Key 查询所有生成模型实时单价的简单公共 API。
+
+| 类型 | 计费 |
+|---|---|
+| 图片 | 按成功输出数量/像素档位；组图按实际成功张数 |
+| 图层拆分 | 各图层可能按实际像素档分别计费 |
+| 视频 | 常见为 token 单价 × token 用量；用量受时长、尺寸、帧率和是否含输入视频影响 |
+
+准确价格以页面最新表格与实际账单为准。文档 API 的 `Result.UpdatedTime` 可用于判断页面时效。
+
+豆包语音当前公开的 SeedASR 2.0 小时版价格与试用：
+
+| 能力 | 后付费 | 免费试用 | 有效期 |
+|---|---:|---:|---|
+| 文件识别 | 0.8 元/小时 | 20 小时 | 开通后 6 个月 |
+| 实时识别（小时版） | 1 元/小时 | 20 小时 | 开通后 6 个月 |
+
+免费试用需要在豆包语音控制台手动开通，不是每月刷新。实时并发版使用另一资源 ID 和计费方式，不能套用小时版价格。
+
+## 7. 余额与用量
+
+方舟有用量统计和 `GetInferenceUsage` 等云 OpenAPI，但这些管理面接口常需火山引擎 AccessKey/SecretKey 签名，不是生成 Bearer API Key 的同一权限。当前不为低优先级余额查询引入云账号高权限。
+
+## 8. 项目当前实现
+
+| 能力 | 状态 | 说明 |
+|---|---|---|
+| Seedream 同步生成 | 已接入 | `providers/volcengine.ts` |
+| 多 URL 结果解析 | 已接入 | 递归收集 `data[]` 等结构 |
+| 本地图片 | 已接入 | 按官方契约转 Data URI |
+| Files API | 不作为图片生成公共上传 | 避免将理解 API 的 File ID 误发给生成 API |
+| 视频异步生成 | 已接入（未真实付费验证） | Seedance 2.5 / 2.0 系列；提交 + 轮询；参考视频经通用文件上传服务托管，2.5 支持视频编辑 / 延长任务类型 |
+| SeedASR 2.0 文件识别 | 已接入 SDK P0 | 仅远端 URL；submit/query；新版 `X-Api-Key` |
+| SeedASR 2.0 实时识别 | 已接入 SDK P0 | 二进制 WS；固定 PCM S16LE 16 kHz mono |
+| 余额查询 | 暂缓 | 需云账号级签名与权限 |
+
+## 9. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| Base URL 与鉴权 | https://www.volcengine.com/docs/82379/1298459 | 否 |
+| 图片生成 API | https://www.volcengine.com/docs/82379/1541523 | 否 |
+| 模型价格 | https://www.volcengine.com/docs/82379/1544106 | 否 |
+| Files API 教程 | https://www.volcengine.com/docs/82379/1885708 | 否 |
+| 上传文件 API | https://www.volcengine.com/docs/82379/1870405 | 否 |
+| TOS 内网预签名 URL | https://www.volcengine.com/docs/82379/2551760 | 否 |
+| SeedASR 2.0 文件 API | https://docs.volcengine.com/docs/6561/1354868?lang=zh | 否 |
+| SeedASR 2.0 流式 API/二进制协议 | https://docs.volcengine.com/docs/6561/1354869?lang=zh | 否 |
+| 双向流式优化示例/附件 | https://docs.volcengine.com/docs/6561/2630027?lang=zh | 否 |
+| 豆包语音计费与试用 | https://docs.volcengine.com/docs/6561/1359369?lang=zh | 否 |
+| API Key | https://console.volcengine.com/ark/region:cn-beijing/apiKey | 是 |
+| 豆包语音控制台 | https://console.volcengine.com/speech/new/overview | 是 |
+
+> 火山文档页是 SPA。需要机器可读源文时，可使用官方内容接口：`https://docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=<id>&type=online`。