@henjicc/ai-sdk 0.8.0 → 0.10.0

package/docs/model-adaptation/Wan-3.0/Wan-3.0_/347/231/276/347/202/274.md

@@ -0,0 +1,96 @@
+# Wan 3.0 · 百炼
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | 阿里云百炼（官方） |
+| 项目模型 ID | `bailian-wan-3.0`（通用标识 `wan-3.0`） |
+| 平台模型 ID | `wan3.0-video`（标准版）、`wan3.0-video-prime`（官方称“高速版”：能力对齐标准版，端到端更快，单价更高） |
+| 接口形态 | 异步任务（HTTP 只支持异步） |
+| 文档 / 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- 提交：`POST /api/v1/services/aigc/video-generation/video-synthesis`，请求头必须带 `X-DashScope-Async: enable`（缺少时报 “current user api does not support synchronous calls”）；成功返回 `output.task_id` 与 `output.task_status: PENDING`
+- 查询：`GET /api/v1/tasks/{task_id}`；官方建议约 15 秒查询一次，查询 RPS 默认 20；`task_id` 24 小时内可查
+- 官方示例使用空间专属域名 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`；项目沿用百炼供应商统一的 `https://dashscope.aliyuncs.com`（官方保证历史地址可用，见 [百炼.md](../供应商/百炼.md) 第 1 节）。模型、Endpoint 与 API Key 必须同属北京地域
+- 结果 `output.video_url` 为 MP4（H.264），24 小时有效，按统一媒体转存链路落盘
+- 生成通常 1–5 分钟，最长可出 30 秒视频，30 fps
+
+## 2. 能力（按 `input.media[].type` 组合）
+
+| 场景 | media |
+|---|---|
+| 文生视频 | 不传 media，只传 `prompt` |
+| 首帧 / 首尾帧 | `first_frame` 1 张（+ `last_frame` 1 张）；不可与其他类型混用 |
+| 参考生视频 | `reference_image` ≤ 10、`reference_video` ≤ 5（单段 1–15 秒，总 ≤ 15 秒）、`reference_audio` ≤ 5（同上），自由组合；提示词用“图1”“视频1”“音频1”指代，图 / 视频 / 音频分别计数 |
+| 文件 / 网页生视频 | `file`（docx、pdf、pptx 等 ≤ 100MB / 50 页）或 `link`（公开网页）二选一，可再组合参考素材；此时 `prompt_extend` 必须为 true |
+| 视频编辑 / 延长 | 至少 1 个 `reference_video`，提示词写编辑或延长意图；延长需 `ratio: adaptive` |
+
+`prompt` 与 `media` 至少填一项；`prompt` ≤ 20000 字符，超出自动截断。
+
+输入格式：图片支持公网 URL、`oss://` 临时 URL 与 `data:{MIME};base64,` Data URI（JPEG/JPG/PNG/BMP/WEBP，单边 240–8000 px，长宽比 ≤ 8:1，≤ 20MB）；**视频、音频、文件只收公网 URL 或 `oss://` 临时 URL**。
+
+## 3. 请求参数
+
+| 字段 | 取值 | 项目处理 |
+|---|---|---|
+| `model` | `wan3.0-video` / `wan3.0-video-prime` | 由「版本」切换 |
+| `input.prompt` | string | 空提示词不发送 |
+| `input.media` | 见第 2 节 | 文/图生视频：1 张发 `first_frame`、2 张再加 `last_frame`；参考模式发 `reference_image`（最多 10 张） |
+| `parameters.resolution` | `1080P`（默认，最贵）/ `720P` / `480P` | 默认 720P，始终显式发送 |
+| `parameters.ratio` | `adaptive`（默认）/ `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` | 「智能」发 `adaptive` |
+| `parameters.duration` | 2–30，默认 5；`-1` 智能时长；有视频输入时输入总时长 + 输出时长 ≤ 30 | 2–30 |
+| `parameters.audio` | boolean，默认 true，开关同价 | 开关 |
+| `parameters.watermark` | boolean，默认 false | 固定 false |
+| `parameters.prompt_extend` | boolean，默认 true | 不发送（用官方默认） |
+| `parameters.seed` | -1 或 0–2147483647 | 不显示、不发送 |
+
+## 4. 价格
+
+来源：[模型价格](https://help.aliyun.com/zh/model-studio/model-pricing)「万相3.0-视频生成」（2026-11-07 读取，无需登录），华北2（北京），输入视频与输出视频同价，按秒计费，失败不计费：
+
+| 分辨率 | wan3.0-video（原价，当前限时 7 折） | wan3.0-video-prime |
+|---|---|---|
+| 480P | ¥0.3/秒 | ¥0.45/秒 |
+| 720P | ¥0.6/秒 | ¥0.9/秒 |
+| 1080P | ¥1.2/秒 | ¥1.8/秒 |
+
+- 计费时长 = 输入视频时长 + 输出视频时长；读不到参考视频时长时按输出时长估，封顶合计 15 秒。
+- 北京地域标准版有 30 秒免费额度（90 天内），Prime 无。
+- 项目按标准版**原价**预估，折扣期内实际账单更低；新加坡等地域单价不同，项目只用北京。
+
+## 5. 事件 / 状态矩阵
+
+| 状态 | 前置 | 字段契约 | 空值语义 | 下一状态 | 对外输出 | 终态 / 错误 |
+|---|---|---|---|---|---|---|
+| 提交成功 | — | `output.task_id` string、`output.task_status: PENDING`、`request_id` | 缺 `task_id` 判 `invalid_response` | PENDING | pending + taskId | 否 |
+| 提交失败 | — | 顶层 `code` / `message` / `request_id` | — | — | 无 | 是；`Arrearage`、`AccessDenied.Unpurchased`、`Model.AccessDenied` 与“模型未开通”文案按 `providerAccessErrors` 归类为不可重试 |
+| `PENDING` | 提交 | `output.task_status` | 无结果 | RUNNING | 无 | 否，继续查询 |
+| `RUNNING` | PENDING | 同上 | 无结果 | SUCCEEDED / FAILED | 无 | 否，继续查询 |
+| `SUCCEEDED` | RUNNING | `output.video_url` 必有；`usage.duration` / `output_video_duration` / `SR` / `ratio` | `video_url` 缺失或非 http(s) 判 `empty_result` | — | completed，URL 为视频 | 是 |
+| `FAILED` | PENDING / RUNNING | `output.code` / `output.message` | message 缺失时用固定原因 | — | 无 | 是，`provider_task_failed`（`code: message`），不续查 |
+| `CANCELED` | PENDING | — | — | — | 无 | 是 |
+| `UNKNOWN` | 任意 | 只有 `task_id` / `task_status` | 任务不存在或超过 24 小时查询期 | 保持 | 无 | 计入连续查询失败，连续 20 次后 `provider_task_unreachable` |
+| 缺状态 / 查询 HTTP 5xx / 网络错误 | 任意 | — | — | 保持 | 无 | 同上 |
+
+不变量：只有 `SUCCEEDED` 且带 `video_url` 才算有效 final；用户取消只停止本地查询（官方取消接口见「管理异步任务」，SDK 未接）；SDK 只看当次状态，不依赖状态顺序。
+
+## 6. 项目适配
+
+- 素材尺寸前置校验（2026-11-08）：`imageConstraints` 图片单边 240–8000 px、长宽比 ≤ 8:1。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+- 一个产品模型，`role: 'mode'` 版本（标准 / Prime）+ `role: 'mode'` 模式（文/图生视频、参考生视频），与 APIMart、Fal 同家族入口一致（KIE 把 Prime 拆成独立模型 `kie-wan-3.0-prime`）。
+- 图片走 Data URI；参考视频（≤ 5）、参考音频（≤ 5）由百炼预处理按请求的 `model` 申请临时存储凭证（`/api/v1/uploads?action=getPolicy`）上传成 `oss://`，请求体含 `oss://` 时提交自动带 `X-DashScope-OssResourceResolve: enable`。视频编辑 / 延长不单设模式：参考模式带上视频、提示词写明意图即可（延长需「智能」比例）。
+- 未接入：`file` / `link`、`duration: -1`、`seed`、`prompt_extend` 开关、地域与业务空间域名配置。有视频输入时官方要求输入总时长 + 输出时长 ≤ 30 秒：读得到素材时长时，提交前把输出时长收进这个范围。
+- Fixture：`packages/ai-sdk/tests/fixtures/bailian/video-*.json`（提交成功、提交失败、成功、失败、UNKNOWN 均为官方原样示例）；状态迁移与请求头测试：`packages/ai-sdk/tests/providers/video-async-official.test.ts`；请求构建与价格：`packages/ai-sdk/tests/catalog/official-videos.test.ts`。未做真实付费调用。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 万相 3.0 视频生成 API 参考 | https://help.aliyun.com/zh/model-studio/wan3-video-generation-api-reference | 否 |
+| 模型价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| 模型列表 | https://help.aliyun.com/zh/model-studio/models | 否 |
+| 上传文件获取临时 URL | https://help.aliyun.com/zh/model-studio/get-temporary-file-url | 否 |
+| 控制台模型卡片 | https://bailian.console.aliyun.com/cn-beijing/model/market/detail/wan3.0-video | 是 |

package/docs/model-adaptation/Wan-3.0-Prime/Wan-3.0-Prime_KIE.md

@@ -0,0 +1,20 @@
+# Wan 3.0 Prime · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 项目模型 | `kie-wan-3.0-prime`，通用标识 `wan-3.0-prime` |
+| model ID | `wan/3-0-video-prime` |
+| 文档与价格 | 公开，无需登录 |
+| 定价（每秒，按输出时长） | 480p $0.0612、720p $0.126、1080p $0.252 |
+
+## 请求契约
+
+字段、枚举、互斥规则与 [Wan 3.0](../Wan-3.0/Wan-3.0_KIE.md) 逐项一致（2026-11-07 对比两份官方 schema），只有 model ID 与单价不同。项目两者共用 `catalog/kie/wan30.ts` 构建请求。
+
+## 原始链接索引
+
+均公开，无需登录：
+- [Wan 3.0 Video Prime](https://docs.kie.ai/market/wan/3-0-video-prime.md)
+- [模型页](https://kie.ai/wan3.0-video-prime)
+- [实时价格页](https://kie.ai/pricing)（2026-11-07 核对 3 行 wan3.0 video prime 价格）

package/docs/model-adaptation/Whisper-Large-v3/Whisper-Large-v3_Groq.md

@@ -1,80 +1,80 @@
-# Whisper Large v3 · Groq
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-09-21 |
-| 模态 | ASR（同步文件转写 / 音频译英文） |
-| 供应商 | GroqCloud |
-| 平台模型 ID | `whisper-large-v3` |
-| 转写端点 | 支持 |
-| 翻译端点 | 支持，输出英文 |
-| 公开价格 | `$0.111 / hour` |
-| 免费政策 | Free Plan 持续性限流额度，不是一次性试用金 |
-| 文档/价格 | 公开无需登录；Key/用量需登录 |
-
-## 1. 端点与鉴权
-
-```text
-POST https://api.groq.com/openai/v1/audio/transcriptions
-POST https://api.groq.com/openai/v1/audio/translations
-Authorization: Bearer <GROQ_API_KEY>
-Content-Type: multipart/form-data
-```
-
-两个端点都传 `model=whisper-large-v3`，且 `file` / `url` 二选一。`url` 可为普通 URL 或
-Base64URL。`/audio/transcriptions` 返回原语言文本，`/audio/translations` 返回英文翻译；后者
-不是可任意选择目标语言的翻译 API。
-
-可选字段包括 `language`（ISO-639-1）、`prompt`（最多 224 tokens）、
-`response_format=json|verbose_json|text`、`temperature=0..1` 和
-`timestamp_granularities[]=segment|word`。官方未公开独立 WebSocket/SSE 实时 ASR，请求是同步
-HTTP 文件处理。
-
-## 2. 响应与时间戳
-
-- `json` 最小结果包含 `text`；`text` 格式返回纯文本。
-- `verbose_json` 可返回段/词时间戳和段级统计。
-- 官方参数表要求时间戳使用 `verbose_json`，但 Python 示例注释误写为 `json`；适配
-  应以参数表和真实 API 验证为准。
-
-## 3. 文件限制
-
-- Free Tier 最大 25 MB，Developer Tier 最大 100 MB；附件上传最大 25 MB，超过时可使用
-  `url`。Groq Models 表对本模型也明确列 100 MB 最大文件。
-- 支持 `flac/mp3/mp4/mpeg/mpga/m4a/ogg/wav/webm`；多音轨文件只处理第一条音轨。
-- 最短 0.01 秒，每次最少按 10 秒计费；服务端下采样为 16 kHz 单声道。
-- 长音频需客户端分块并拼接结果。
-
-## 4. 价格、额度与选型
-
-| 项目 | 官方当前值 |
-|---|---|
-| 价格 | `$0.111 / hour` |
-| 参考速度 | 189x real-time |
-| 参考 WER | 10.3% |
-| Free Plan | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD |
-| Developer Plan | 200K ASH / 300 RPM |
-
-官方建议在多语种且对转写错误更敏感时选本模型；Turbo 的单价更低、参考速度更高。
-速度/WER 是官方比较指标，不是 SLA。实际组织限流以登录后 Limits 页为准。
-
-## 5. 错误与适配要点
-
-错误体是 `{error:{message,type}}`。需处理 400/401/403/404/413/422/429、498 容量不足、
-499 调用方取消与 500/502/503。Say-It/SDK 接入属于简单 Bearer + multipart HTTP；应把
-“转写”和“译英文”建模为明确能力，而不是向 Turbo 也暴露一个必然失败的翻译开关。
-中国大陆网络与付款可用性未经官方承诺或本轮实测。
-
-## 6. 原始链接索引
-
-| 信息 | 链接 | 登录 |
-|---|---|---|
-| ASR API、参数与文件限制 | https://console.groq.com/docs/speech-to-text | 否 |
-| 模型价格与 Developer Plan | https://console.groq.com/docs/models | 否 |
-| Free Plan 限流 | https://console.groq.com/docs/rate-limits | 否 |
-| 错误码 | https://console.groq.com/docs/errors | 否 |
-| API Key | https://console.groq.com/keys | **是** |
-
-## 2026-09-21 文件传输边界复核
-
-SDK 本地 multipart 默认上限为 25,000,000 字节（十进制保守解释官方 25 MB），付费账号也不能据 100 MB URL 限额扩大附件上传限制。分块上传不改变格式或模型参数。
+# Whisper Large v3 · Groq
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-09-21 |
+| 模态 | ASR（同步文件转写 / 音频译英文） |
+| 供应商 | GroqCloud |
+| 平台模型 ID | `whisper-large-v3` |
+| 转写端点 | 支持 |
+| 翻译端点 | 支持，输出英文 |
+| 公开价格 | `$0.111 / hour` |
+| 免费政策 | Free Plan 持续性限流额度，不是一次性试用金 |
+| 文档/价格 | 公开无需登录；Key/用量需登录 |
+
+## 1. 端点与鉴权
+
+```text
+POST https://api.groq.com/openai/v1/audio/transcriptions
+POST https://api.groq.com/openai/v1/audio/translations
+Authorization: Bearer <GROQ_API_KEY>
+Content-Type: multipart/form-data
+```
+
+两个端点都传 `model=whisper-large-v3`，且 `file` / `url` 二选一。`url` 可为普通 URL 或
+Base64URL。`/audio/transcriptions` 返回原语言文本，`/audio/translations` 返回英文翻译；后者
+不是可任意选择目标语言的翻译 API。
+
+可选字段包括 `language`（ISO-639-1）、`prompt`（最多 224 tokens）、
+`response_format=json|verbose_json|text`、`temperature=0..1` 和
+`timestamp_granularities[]=segment|word`。官方未公开独立 WebSocket/SSE 实时 ASR，请求是同步
+HTTP 文件处理。
+
+## 2. 响应与时间戳
+
+- `json` 最小结果包含 `text`；`text` 格式返回纯文本。
+- `verbose_json` 可返回段/词时间戳和段级统计。
+- 官方参数表要求时间戳使用 `verbose_json`，但 Python 示例注释误写为 `json`；适配
+  应以参数表和真实 API 验证为准。
+
+## 3. 文件限制
+
+- Free Tier 最大 25 MB，Developer Tier 最大 100 MB；附件上传最大 25 MB，超过时可使用
+  `url`。Groq Models 表对本模型也明确列 100 MB 最大文件。
+- 支持 `flac/mp3/mp4/mpeg/mpga/m4a/ogg/wav/webm`；多音轨文件只处理第一条音轨。
+- 最短 0.01 秒，每次最少按 10 秒计费；服务端下采样为 16 kHz 单声道。
+- 长音频需客户端分块并拼接结果。
+
+## 4. 价格、额度与选型
+
+| 项目 | 官方当前值 |
+|---|---|
+| 价格 | `$0.111 / hour` |
+| 参考速度 | 189x real-time |
+| 参考 WER | 10.3% |
+| Free Plan | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD |
+| Developer Plan | 200K ASH / 300 RPM |
+
+官方建议在多语种且对转写错误更敏感时选本模型；Turbo 的单价更低、参考速度更高。
+速度/WER 是官方比较指标，不是 SLA。实际组织限流以登录后 Limits 页为准。
+
+## 5. 错误与适配要点
+
+错误体是 `{error:{message,type}}`。需处理 400/401/403/404/413/422/429、498 容量不足、
+499 调用方取消与 500/502/503。Say-It/SDK 接入属于简单 Bearer + multipart HTTP；应把
+“转写”和“译英文”建模为明确能力，而不是向 Turbo 也暴露一个必然失败的翻译开关。
+中国大陆网络与付款可用性未经官方承诺或本轮实测。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| ASR API、参数与文件限制 | https://console.groq.com/docs/speech-to-text | 否 |
+| 模型价格与 Developer Plan | https://console.groq.com/docs/models | 否 |
+| Free Plan 限流 | https://console.groq.com/docs/rate-limits | 否 |
+| 错误码 | https://console.groq.com/docs/errors | 否 |
+| API Key | https://console.groq.com/keys | **是** |
+
+## 2026-09-21 文件传输边界复核
+
+SDK 本地 multipart 默认上限为 25,000,000 字节（十进制保守解释官方 25 MB），付费账号也不能据 100 MB URL 限额扩大附件上传限制。分块上传不改变格式或模型参数。

package/docs/model-adaptation/Whisper-Large-v3-Turbo/Whisper-Large-v3-Turbo_Groq.md

@@ -1,79 +1,79 @@
-# Whisper Large v3 Turbo · Groq
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-09-21 |
-| 模态 | ASR（同步文件转写） |
-| 供应商 | GroqCloud |
-| 平台模型 ID | `whisper-large-v3-turbo` |
-| 翻译端点 | **不支持** |
-| 公开价格 | `$0.04 / hour` |
-| 免费政策 | Free Plan 持续性限流额度，不是一次性试用金 |
-| 文档/价格 | 公开无需登录；Key/用量需登录 |
-
-## 1. 端点与鉴权
-
-```text
-POST https://api.groq.com/openai/v1/audio/transcriptions
-Authorization: Bearer <GROQ_API_KEY>
-Content-Type: multipart/form-data
-```
-
-必填 `model=whisper-large-v3-turbo`，且 `file` / `url` 二选一。`url` 可为普通 URL 或
-Base64URL。可选字段包括 `language`（ISO-639-1）、`prompt`（最多 224 tokens）、
-`response_format=json|verbose_json|text`、`temperature=0..1` 和
-`timestamp_granularities[]=segment|word`。
-
-本模型不能调用 `/audio/translations`。官方未公开独立 WebSocket/SSE 实时 ASR，请求是同步
-HTTP 文件转写。
-
-## 2. 响应与时间戳
-
-- `json` 最小结果包含 `text`；`text` 格式返回纯文本。
-- `verbose_json` 可返回段/词时间戳和段级统计。
-- 官方参数表要求时间戳使用 `verbose_json`，但 Python 示例注释误写为 `json`；适配
-  应以参数表和真实 API 验证为准。
-
-## 3. 文件限制
-
-- Free Tier 最大 25 MB，Developer Tier 公开总限制为 100 MB；附件上传最大 25 MB，
-  超过时可使用 `url`。Models 表的 Turbo 单模型文件大小栏为 `-`，100 MB 不应作为
-  Turbo 永久的硬编码常量。
-- 支持 `flac/mp3/mp4/mpeg/mpga/m4a/ogg/wav/webm`；多音轨文件只处理第一条音轨。
-- 最短 0.01 秒，每次最少按 10 秒计费；服务端下采样为 16 kHz 单声道。
-- 长音频需客户端分块并拼接结果。
-
-## 4. 价格、额度与选型
-
-| 项目 | 官方当前值 |
-|---|---|
-| 价格 | `$0.04 / hour` |
-| 参考速度 | 216x real-time |
-| 参考 WER | 12% |
-| Free Plan | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD |
-| Developer Plan | 400K ASH / 400 RPM |
-
-Turbo 是官方建议的多语种性价比选项；如果任务对错词率更敏感或需音频译英文，应选
-`whisper-large-v3`。速度/WER 是官方比较指标，不是 SLA。实际组织限流以登录后
-Limits 页为准。
-
-## 5. 错误与适配要点
-
-错误体是 `{error:{message,type}}`。需处理 400/401/403/404/413/422/429、498 容量不足、
-499 调用方取消与 500/502/503。Say-It/SDK 接入属于简单 Bearer + multipart HTTP，但需在发送前
-按账户等级校验文件大小，传递 `AbortSignal`，并对 429/5xx 执行受控重试。中国大陆网络与
-付款可用性未经官方承诺或本轮实测。
-
-## 6. 原始链接索引
-
-| 信息 | 链接 | 登录 |
-|---|---|---|
-| ASR API、参数与文件限制 | https://console.groq.com/docs/speech-to-text | 否 |
-| 模型价格与 Developer Plan | https://console.groq.com/docs/models | 否 |
-| Free Plan 限流 | https://console.groq.com/docs/rate-limits | 否 |
-| 错误码 | https://console.groq.com/docs/errors | 否 |
-| API Key | https://console.groq.com/keys | **是** |
-
-## 2026-09-21 文件传输边界复核
-
-SDK 本地 multipart 默认上限为 25,000,000 字节。官方 100 MB 开发者限制不等于附件上传限制，超过 25 MB 应使用 URL。分块上传不转码。
+# Whisper Large v3 Turbo · Groq
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-09-21 |
+| 模态 | ASR（同步文件转写） |
+| 供应商 | GroqCloud |
+| 平台模型 ID | `whisper-large-v3-turbo` |
+| 翻译端点 | **不支持** |
+| 公开价格 | `$0.04 / hour` |
+| 免费政策 | Free Plan 持续性限流额度，不是一次性试用金 |
+| 文档/价格 | 公开无需登录；Key/用量需登录 |
+
+## 1. 端点与鉴权
+
+```text
+POST https://api.groq.com/openai/v1/audio/transcriptions
+Authorization: Bearer <GROQ_API_KEY>
+Content-Type: multipart/form-data
+```
+
+必填 `model=whisper-large-v3-turbo`，且 `file` / `url` 二选一。`url` 可为普通 URL 或
+Base64URL。可选字段包括 `language`（ISO-639-1）、`prompt`（最多 224 tokens）、
+`response_format=json|verbose_json|text`、`temperature=0..1` 和
+`timestamp_granularities[]=segment|word`。
+
+本模型不能调用 `/audio/translations`。官方未公开独立 WebSocket/SSE 实时 ASR，请求是同步
+HTTP 文件转写。
+
+## 2. 响应与时间戳
+
+- `json` 最小结果包含 `text`；`text` 格式返回纯文本。
+- `verbose_json` 可返回段/词时间戳和段级统计。
+- 官方参数表要求时间戳使用 `verbose_json`，但 Python 示例注释误写为 `json`；适配
+  应以参数表和真实 API 验证为准。
+
+## 3. 文件限制
+
+- Free Tier 最大 25 MB，Developer Tier 公开总限制为 100 MB；附件上传最大 25 MB，
+  超过时可使用 `url`。Models 表的 Turbo 单模型文件大小栏为 `-`，100 MB 不应作为
+  Turbo 永久的硬编码常量。
+- 支持 `flac/mp3/mp4/mpeg/mpga/m4a/ogg/wav/webm`；多音轨文件只处理第一条音轨。
+- 最短 0.01 秒，每次最少按 10 秒计费；服务端下采样为 16 kHz 单声道。
+- 长音频需客户端分块并拼接结果。
+
+## 4. 价格、额度与选型
+
+| 项目 | 官方当前值 |
+|---|---|
+| 价格 | `$0.04 / hour` |
+| 参考速度 | 216x real-time |
+| 参考 WER | 12% |
+| Free Plan | 20 RPM / 2K RPD / 7.2K ASH / 28.8K ASD |
+| Developer Plan | 400K ASH / 400 RPM |
+
+Turbo 是官方建议的多语种性价比选项；如果任务对错词率更敏感或需音频译英文，应选
+`whisper-large-v3`。速度/WER 是官方比较指标，不是 SLA。实际组织限流以登录后
+Limits 页为准。
+
+## 5. 错误与适配要点
+
+错误体是 `{error:{message,type}}`。需处理 400/401/403/404/413/422/429、498 容量不足、
+499 调用方取消与 500/502/503。Say-It/SDK 接入属于简单 Bearer + multipart HTTP，但需在发送前
+按账户等级校验文件大小，传递 `AbortSignal`，并对 429/5xx 执行受控重试。中国大陆网络与
+付款可用性未经官方承诺或本轮实测。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| ASR API、参数与文件限制 | https://console.groq.com/docs/speech-to-text | 否 |
+| 模型价格与 Developer Plan | https://console.groq.com/docs/models | 否 |
+| Free Plan 限流 | https://console.groq.com/docs/rate-limits | 否 |
+| 错误码 | https://console.groq.com/docs/errors | 否 |
+| API Key | https://console.groq.com/keys | **是** |
+
+## 2026-09-21 文件传输边界复核
+
+SDK 本地 multipart 默认上限为 25,000,000 字节。官方 100 MB 开发者限制不等于附件上传限制，超过 25 MB 应使用 URL。分块上传不转码。

package/docs/model-adaptation/Z-Image-Turbo/Z-Image-Turbo_APIMart.md

@@ -1,88 +1,88 @@
-# Z-Image Turbo · APIMart
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 图片 |
-| 供应商 | APIMart（聚合平台） |
-| 平台模型 ID | `z-image-turbo` |
-| 接口形态 | **异步任务** |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-| 模型名 | 说明 | 生成张数 | 计费方式 |
-|---|---|---|---|
-| `z-image-turbo` | 轻量快速图片生成，支持中英双语 | **固定 1 张** | 固定价格 |
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.apimart.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /v1/images/generations` → `{ code, data: [{ status: "submitted", task_id }] }`
-- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
-- **结果存储**：图片已镜像到平台 CDN，文档称**长期有效**
-- **计费规则**：按成功生成的图片张数计费，失败不扣费
-
-## 2. 能力清单
-
-仅**文生图**。APIMart 上 Z-Image-Turbo **没有参考图 / 图生图参数**。
-
-## 3. 请求参数（Body）
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `model` | string | 必填 | — | `z-image-turbo` |
-| `prompt` | string | 必填 | — | **最多 800 字符** |
-| `size` | string | 可选 | `1:1` | 宽高比：`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`（共 7 个，**没有 21:9 / 7:9 / 9:21**） |
-| `resolution` | string | 可选 | `1K` | `1K` / `2K` |
-| `prompt_extend` | boolean | 可选 | `false` | 智能改写提示词。开启后效果更好，**费用会增加** |
-| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审提示词与输入图 |
-
-**不支持 `n` 参数**——固定每次 1 张。
-
-### 尺寸对照表
-
-| 比例 | 1K | 2K |
-|---|---|---|
-| 1:1 | 1024×1024 | 2048×2048 |
-| 4:3 | 1152×864 | 2048×1536 |
-| 3:4 | 864×1152 | 1536×2048 |
-| 16:9 | 1280×720 | 2048×1152 |
-| 9:16 | 720×1280 | 1152×2048 |
-| 3:2 | 1248×832 | 2048×1360 |
-| 2:3 | 832×1248 | 1360×2048 |
-
-> 官方百炼是按「总像素档 + 精确 `宽*高`」控制，APIMart 换成了「比例 + 1K/2K 档位」，两边的可选集合不一样。
-
-## 4. 响应结构
-
-提交返回 `task_id`；轮询 `GET /v1/tasks/{task_id}`，`status=completed` 后读 `result.images[].url`（数组）。
-
-## 5. 价格
-
-来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)（2026-08-22 读取，1 Credit ≈ $0.1）。
-
-| 规格 | 我们的价格 | 官方价 | 节省 |
-|---|---|---|---|
-| 默认 | 0.1 Credits/张 ≈ **$0.01/张** | $0.0125/张 | 20% |
-| `prompt_extend` | 0.2 Credits/张 ≈ **$0.02/张** | $0.025/张 | 20% |
-
-> 与百炼官方一致：开启 `prompt_extend` 后价格翻倍。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口两个字段都没有。
-- `prompt_extend` **翻倍计费**，需谨慎默认（APIMart 默认 `false`，与百炼默认一致）。
-- 固定 1 张，UI 不要出现数量选择。
-- 比例集合只有 7 个，比百炼官方（11 个）少；不要把 21:9 之类的比例透出到这个供应商。
-- 提示词硬上限 800 字符。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Z-Image-Turbo 图像生成 API | https://docs.apimart.ai/cn/api-reference/images/z-image-turbo/generation | 否 |
-| 同页纯 Markdown | https://docs.apimart.ai/cn/api-reference/images/z-image-turbo/generation.md | 否 |
-| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
-| 定价中心（搜 Z-IMAGE-TURBO） | https://apimart.ai/zh/pricing | 否 |
-| API Key 管理 | https://apimart.ai/keys | **是** |
+# Z-Image Turbo · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `z-image-turbo` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+| 模型名 | 说明 | 生成张数 | 计费方式 |
+|---|---|---|---|
+| `z-image-turbo` | 轻量快速图片生成，支持中英双语 | **固定 1 张** | 固定价格 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/images/generations` → `{ code, data: [{ status: "submitted", task_id }] }`
+- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
+- **结果存储**：图片已镜像到平台 CDN，文档称**长期有效**
+- **计费规则**：按成功生成的图片张数计费，失败不扣费
+
+## 2. 能力清单
+
+仅**文生图**。APIMart 上 Z-Image-Turbo **没有参考图 / 图生图参数**。
+
+## 3. 请求参数（Body）
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | `z-image-turbo` |
+| `prompt` | string | 必填 | — | **最多 800 字符** |
+| `size` | string | 可选 | `1:1` | 宽高比：`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`（共 7 个，**没有 21:9 / 7:9 / 9:21**） |
+| `resolution` | string | 可选 | `1K` | `1K` / `2K` |
+| `prompt_extend` | boolean | 可选 | `false` | 智能改写提示词。开启后效果更好，**费用会增加** |
+| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审提示词与输入图 |
+
+**不支持 `n` 参数**——固定每次 1 张。
+
+### 尺寸对照表
+
+| 比例 | 1K | 2K |
+|---|---|---|
+| 1:1 | 1024×1024 | 2048×2048 |
+| 4:3 | 1152×864 | 2048×1536 |
+| 3:4 | 864×1152 | 1536×2048 |
+| 16:9 | 1280×720 | 2048×1152 |
+| 9:16 | 720×1280 | 1152×2048 |
+| 3:2 | 1248×832 | 2048×1360 |
+| 2:3 | 832×1248 | 1360×2048 |
+
+> 官方百炼是按「总像素档 + 精确 `宽*高`」控制，APIMart 换成了「比例 + 1K/2K 档位」，两边的可选集合不一样。
+
+## 4. 响应结构
+
+提交返回 `task_id`；轮询 `GET /v1/tasks/{task_id}`，`status=completed` 后读 `result.images[].url`（数组）。
+
+## 5. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)（2026-08-22 读取，1 Credit ≈ $0.1）。
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 | 0.1 Credits/张 ≈ **$0.01/张** | $0.0125/张 | 20% |
+| `prompt_extend` | 0.2 Credits/张 ≈ **$0.02/张** | $0.025/张 | 20% |
+
+> 与百炼官方一致：开启 `prompt_extend` 后价格翻倍。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口两个字段都没有。
+- `prompt_extend` **翻倍计费**，需谨慎默认（APIMart 默认 `false`，与百炼默认一致）。
+- 固定 1 张，UI 不要出现数量选择。
+- 比例集合只有 7 个，比百炼官方（11 个）少；不要把 21:9 之类的比例透出到这个供应商。
+- 提示词硬上限 800 字符。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Z-Image-Turbo 图像生成 API | https://docs.apimart.ai/cn/api-reference/images/z-image-turbo/generation | 否 |
+| 同页纯 Markdown | https://docs.apimart.ai/cn/api-reference/images/z-image-turbo/generation.md | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（搜 Z-IMAGE-TURBO） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |