@henjicc/ai-sdk 0.2.8 → 0.3.0

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/241/205/345/237/272/346/265/201/345/212/250.md

@@ -1,88 +1,110 @@
-# 硅基流动 · 供应商基础文档
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-31 |
-| 供应商 | SiliconFlow / SiliconCloud |
-| 建议 `providerId` | `siliconflow` |
-| Base URL | `https://api.siliconflow.cn/v1` |
-| 鉴权 | `Authorization: Bearer <SILICONFLOW_API_KEY>` |
-| 已核验 ASR 类型 | 同步文件语音转写 API |
-| 文档/价格可见性 | 公开，无需登录；API Key、实名、用量和账单需登录 |
-
-## 1. ASR 端点与请求
-
-```text
-POST https://api.siliconflow.cn/v1/audio/transcriptions
-Authorization: Bearer <SILICONFLOW_API_KEY>
-Content-Type: multipart/form-data
-```
-
-| 字段 | 类型 | 要求 |
-|---|---|---|
-| `file` | binary file | 必填；时长不超过 1 小时，文件不超过 50 MB |
-| `model` | enum string | 必填；`FunAudioLLM/SenseVoiceSmall` 或 `TeleAI/TeleSpeechASR` |
-
-官方端点参考目前只公开了 `file` 和 `model`，没有公开 `language`、`prompt`、
-`response_format`、词级时间戳、说话人分离或热词参数。cURL 使用 MP3 为示例，但页面未给出
-完整 MIME/容器白名单；不应仅根据开源上游模型能力自行扩展公开云 API 参数。
-
-成功响应是 `application/json`：
-
-```json
-{
-  "text": "<string>"
-}
-```
-
-响应头 `x-siliconcloud-trace-id` 是服务端生成的请求追踪标识，可在排障时提供给官方，
-不应当成稳定业务 ID。官方未公开独立 WebSocket、SSE、异步任务或实时麦克风 ASR
-协议；本端点应按同步文件转写建模。
-
-## 2. 模型、价格与免费政策
-
-| 平台模型 ID | API 明确列举 | 当前价格证据 | 结论 |
-|---|---:|---|---|
-| `FunAudioLLM/SenseVoiceSmall` | 是 | 公开价格页语音模型标注“免费” | 自有 Key 调用按当前免费模型政策处理 |
-| `TeleAI/TeleSpeechASR` | 是 | 通用价格页当前未找到该 ID；官方“说点啥”用例将它列入该客户端的免费服务 | **自有 Key 的通用计费未确认**，上线前必须在控制台/账单复核 |
-
-免费模型不是一次性试用金：官方 Rate Limits 页明确说免费模型调用账单消耗为 0，
-同时要求账号完成实名认证。免费模型使用固定 Rate Limits，但公开页未给这两个 ASR
-模型的精确数值；不应把其它模型的 RPM/RPD 直接套用。模型转写页还明确保留定期上下线
-和调整服务能力的权利，因此发布前应再做模型可用性查询。
-
-## 3. 错误契约
-
-官方转写 API 参考和通用错误页表明错误体并非始终同一形状：
-
-- JSON 形状可为 `{ "code": 20012, "message": "...", "data": null }`；
-- 部分鉴权/权限/路由错误在 API 参考中展示为纯字符串；
-- 429 错误示例含 `message` 和 `data`，需从 `message` 区分 RPM/RPD/TPM/TPD/IPM/IPD；
-- 503/504 通常表示服务高负载，500 是未知服务异常。
-
-常见 HTTP 状态：400 参数，401 凭证，403 余额/权限/实名，429 限流，500 未知服务错误，
-503/504 过载。SDK 的 `provider_http_error` 诊断文本需保留 HTTP status、可用的
-`code/message/data`、纯文本 fallback 和脱敏后的 `x-siliconcloud-trace-id`；当前通用
-`AiRuntimeError` 不提供结构化供应商错误 metadata，不可只按一种 JSON 错误结构解析。
-
-## 4. Say-It/SDK 接入边界
-
-接入复杂度低：标准 Bearer Key + `multipart/form-data` + JSON 或文本错误，无 HMAC、无二进制
-私有帧。与 OpenAI/Groq 语音转写形状接近，但当前公开字段仅有 `file/model`，不能把
-OpenAI 的 `language/prompt/response_format/temperature` 透传过来。
-
-中国大陆使用 `api.siliconflow.cn`，需 SiliconCloud 账号与 API Key；免费模型需实名认证。
-本轮没有发起真实或付费请求，运营商网络可达性、账户实际限流和 TeleSpeechASR 自有 Key
-计费均未实测。
-
-## 5. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| 语音转文字 API、模型 enum、输入限制、响应字段 | https://docs.siliconflow.cn/docs/api/audio-transcriptions-post | 否 |
-| 当前公开价格 | https://siliconflow.cn/pricing | 否 |
-| 免费模型、实名与 Rate Limits 规则 | https://docs.siliconflow.cn/cn/userguide/rate-limits/rate-limit-and-upgradation | 否 |
-| 通用错误体与状态说明 | https://docs.siliconflow.cn/cn/faqs/error-code | 否 |
-| TeleSpeechASR/SenseVoiceSmall 客户端免费服务用例 | https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-BiBiKeyboard | 否 |
-| API Key 管理 | https://cloud.siliconflow.cn/account/ak | **是** |
-| 实名认证 | https://cloud.siliconflow.cn/account/authentication | **是** |
+# 硅基流动 · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-31 |
+| 供应商 | SiliconFlow / SiliconCloud |
+| 建议 `providerId` | `siliconflow` |
+| Base URL | `https://api.siliconflow.cn/v1` |
+| 鉴权 | `Authorization: Bearer <SILICONFLOW_API_KEY>` |
+| 已核验 ASR 类型 | 同步文件语音转写 API |
+| 文档/价格可见性 | 公开，无需登录；API Key、实名、用量和账单需登录 |
+
+## 1. ASR 端点与请求
+
+```text
+POST https://api.siliconflow.cn/v1/audio/transcriptions
+Authorization: Bearer <SILICONFLOW_API_KEY>
+Content-Type: multipart/form-data
+```
+
+| 字段 | 类型 | 要求 |
+|---|---|---|
+| `file` | binary file | 必填；时长不超过 1 小时，文件不超过 50 MB |
+| `model` | enum string | 必填；`FunAudioLLM/SenseVoiceSmall` 或 `TeleAI/TeleSpeechASR` |
+
+官方端点参考目前只公开了 `file` 和 `model`，没有公开 `language`、`prompt`、
+`response_format`、词级时间戳、说话人分离或热词参数。cURL 使用 MP3 为示例，但页面未给出
+完整 MIME/容器白名单；不应仅根据开源上游模型能力自行扩展公开云 API 参数。
+
+成功响应是 `application/json`：
+
+```json
+{
+  "text": "<string>"
+}
+```
+
+响应头 `x-siliconcloud-trace-id` 是服务端生成的请求追踪标识，可在排障时提供给官方，
+不应当成稳定业务 ID。官方未公开独立 WebSocket、SSE、异步任务或实时麦克风 ASR
+协议；本端点应按同步文件转写建模。
+
+## 2. 模型、价格与免费政策
+
+| 平台模型 ID | API 明确列举 | 当前价格证据 | 结论 |
+|---|---:|---|---|
+| `FunAudioLLM/SenseVoiceSmall` | 是 | 公开价格页语音模型标注“免费” | 自有 Key 调用按当前免费模型政策处理 |
+| `TeleAI/TeleSpeechASR` | 是 | 通用价格页当前未找到该 ID；官方“说点啥”用例将它列入该客户端的免费服务 | **自有 Key 的通用计费未确认**，上线前必须在控制台/账单复核 |
+
+免费模型不是一次性试用金：官方 Rate Limits 页明确说免费模型调用账单消耗为 0，
+同时要求账号完成实名认证。免费模型使用固定 Rate Limits，但公开页未给这两个 ASR
+模型的精确数值；不应把其它模型的 RPM/RPD 直接套用。模型转写页还明确保留定期上下线
+和调整服务能力的权利，因此发布前应再做模型可用性查询。
+
+## 3. 错误契约
+
+官方转写 API 参考和通用错误页表明错误体并非始终同一形状：
+
+- JSON 形状可为 `{ "code": 20012, "message": "...", "data": null }`；
+- 部分鉴权/权限/路由错误在 API 参考中展示为纯字符串；
+- 429 错误示例含 `message` 和 `data`，需从 `message` 区分 RPM/RPD/TPM/TPD/IPM/IPD；
+- 503/504 通常表示服务高负载，500 是未知服务异常。
+
+常见 HTTP 状态：400 参数，401 凭证，403 余额/权限/实名，429 限流，500 未知服务错误，
+503/504 过载。SDK 的 `provider_http_error` 诊断文本需保留 HTTP status、可用的
+`code/message/data`、纯文本 fallback 和脱敏后的 `x-siliconcloud-trace-id`；当前通用
+`AiRuntimeError` 不提供结构化供应商错误 metadata，不可只按一种 JSON 错误结构解析。
+
+## 4. Say-It/SDK 接入边界
+
+接入复杂度低：标准 Bearer Key + `multipart/form-data` + JSON 或文本错误，无 HMAC、无二进制
+私有帧。与 OpenAI/Groq 语音转写形状接近，但当前公开字段仅有 `file/model`，不能把
+OpenAI 的 `language/prompt/response_format/temperature` 透传过来。
+
+中国大陆使用 `api.siliconflow.cn`，需 SiliconCloud 账号与 API Key；免费模型需实名认证。
+本轮没有发起真实或付费请求，运营商网络可达性、账户实际限流和 TeleSpeechASR 自有 Key
+计费均未实测。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 语音转文字 API、模型 enum、输入限制、响应字段 | https://docs.siliconflow.cn/docs/api/audio-transcriptions-post | 否 |
+| 当前公开价格 | https://siliconflow.cn/pricing | 否 |
+| 免费模型、实名与 Rate Limits 规则 | https://docs.siliconflow.cn/cn/userguide/rate-limits/rate-limit-and-upgradation | 否 |
+| 通用错误体与状态说明 | https://docs.siliconflow.cn/cn/faqs/error-code | 否 |
+| TeleSpeechASR/SenseVoiceSmall 客户端免费服务用例 | https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-BiBiKeyboard | 否 |
+| API Key 管理 | https://cloud.siliconflow.cn/account/ak | **是** |
+| 实名认证 | https://cloud.siliconflow.cn/account/authentication | **是** |
+# 2026-09-11：Embedding / Rerank 核查
+
+官方公开 API：https://api-docs.siliconflow.cn/docs/api/embeddings-post 、https://api-docs.siliconflow.cn/docs/api/rerank-post 。国内根地址 `https://api.siliconflow.cn/v1`，Bearer，同步 JSON POST `/embeddings` 或 `/rerank`。
+
+- 文本 Qwen3 Embedding 8B/4B/0.6B：`Qwen/Qwen3-Embedding-{8B,4B,0.6B}`，32768 token，支持 dimensions 枚举。8B：64/128/256/512/768/1024/1536/2048/2560/4096；4B 去掉4096；0.6B 到1024。发送 input 字符串数组、encoding_format=float，读取 data[].index/embedding。BGE/BCE 也有 API 字段说明，暂不机械加入所有历史模型。
+- 文本 Qwen3 Reranker 同尺寸 ID `Qwen/Qwen3-Reranker-*`：query、documents、top_n、instruction；不能发送仅 BGE/BCE 支持的 overlap_tokens/max_chunks_per_doc。读取 results[].index/relevance_score，usage 可能位于 meta.tokens（与 billed_units 分开，不能混为实际用量）。
+- 国内价格已于 2026-09-11 使用用户已登录的 BrowserOS neo，在[模型广场](https://cloud.siliconflow.cn/me/models?types=embedding)逐个打开模型详情核验。在线推理价格按明细行的 `/ K Tokens` 单位换算为百万输入 tokens，见下表；不是国际站美元价格，也不是真实调用账单。
+- 多模态 Qwen3-VL-Embedding/Reranker-8B 另有接口变体；本次文本能力不宣称支持图片/视频。发布公告 https://www.siliconflow.cn/news/gnuv7wmztvwaq78ozfhjybmi 标明文本0.7元/百万、视觉1.8元/百万；不能借用该价格给纯文本 Qwen3。
+- 同步终态与验证：非2xx/非法JSON/供应商error拒绝；向量非空且索引完整唯一；重排索引有效唯一且分数有限；取消/超时由 capability client 统一传递。官方示例与字段构造正例、synthetic-negative 分开标注。
+
+| 精确模型 ID | 控制台输入价格（元/千 tokens） | 元/百万输入 tokens |
+|---|---:|---:|
+| Qwen/Qwen3-Embedding-8B | 0.000280 | 0.28 |
+| Qwen/Qwen3-Embedding-4B | 0.000140 | 0.14 |
+| Qwen/Qwen3-Embedding-0.6B | 0.000070 | 0.07 |
+| Qwen/Qwen3-Reranker-8B | 0.000280 | 0.28 |
+| Qwen/Qwen3-Reranker-4B | 0.000140 | 0.14 |
+| Qwen/Qwen3-Reranker-0.6B | 0.000070 | 0.07 |
+| BAAI/bge-m3 | 0.000000 | 0（当前免费） |
+| BAAI/bge-reranker-v2-m3 | 0.000000 | 0（当前免费） |
+
+控制台表头单位按钮显示 `M Tokens`，实际价格单元格明确显示 `/ K Tokens`；以上按单元格原值和单位保存、换算，不把 0.000280 误记为每百万价格。免费结论仅针对上述无 `Pro/` 前缀的两个模型；不能推及 Pro 版本或所有 BGE 模型。未触发推理、充值或修改账号配置，也不保存账号信息。列表中 BCE Embedding/Reranker 已标记 Deprecated，本轮不添加。

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//351/255/224/346/220/255.md

@@ -1,207 +1,207 @@
-# 魔搭 ModelScope · 供应商基础文档
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-30 |
-| 供应商类型 | 开源模型托管平台（API-Inference 服务） |
-| 覆盖模态 | **仅图片**（无视频、无音频） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-| 结算方式 | **魔粒积分，不是货币** |
-
-## 1. 接入协议
-
-- **Base URL**：`https://api-inference.modelscope.cn`
-- **鉴权**：`Authorization: Bearer <MODELSCOPE_TOKEN>`
-- **提交**：`POST /v1/images/generations`，请求头 `X-ModelScope-Async-Mode: true` → 返回 `{ "task_id": "..." }`
-- **查询**：`GET /v1/tasks/<task_id>`，请求头 `X-ModelScope-Task-Type: image_generation`
-- **状态字段**：`task_status`，枚举 `SUCCEED` / `FAILED`（官方示例每 5 秒轮询一次）
-- **结果字段**：`output_images`（字符串数组）
-
-### 提交路由的历史问题（已修正）
-
-代码曾把提交路由写成 `/api/v1/jobs/createTask`——那是 **KIE 的路由格式**，在一次批量改动里被复制串了供应商。已改为官方的 `/v1/images/generations`。
-
-该常量现在只有 `packages/ai-sdk/src/catalog/modelscope/utils.ts` 一份实现；所有魔搭模型的真实 builder 直接复用它。`packages/ai-sdk/tests/catalog/modelscope.test.ts` 同时验证共享函数和 catalog builder，避免路由或图片来源静默分叉。
-
-> ⚠️ 修正**尚未用真实 token 实测确认**——本机网络无法连通 `api-inference.modelscope.cn`，且未配置魔搭 Token。依据是官方文档与每个模型页示例代码的一致写法（无一例外）。首次真实调用时优先验证这一项。
-
-## 2. 硬前提（不满足则完全不可用）
-
-1. 魔搭账号**必须绑定阿里云账号**
-2. 该阿里云账号**必须已完成实名认证**
-
-## 3. 文件上传
-
-魔搭没有独立的文件上传端点。官方做法是把本地图片转成 `data:<mime>;base64,...` 直接放进 `image_url` 字段，文档提供了 `image_to_data_url()` 工具函数。
-
-本项目的处理（`upload.ts` → `uploadForHostedUrl`）：**优先借用 KIE 的上传服务**换公网 URL，KIE Key 未配置或上传失败时**静默退回 data URI**。因为有兜底，魔搭模型不会像 PPIO 那样因为缺 KIE Key 直接失败。
-
-请求体里图片来源有三个键，builder 必须都认：生成页提交是 `uploadedFilePaths`，画布节点是 `images`，旧工程可能直接存 `image_url`。历史动态运行时副本曾漏掉 `uploadedFilePaths`；SDK 直连后已删除该副本，并由真实 catalog builder 测试锁定行为。
-
-## 4. 请求参数（全模型通用）
-
-魔搭 API-Inference 是统一接口，所有图像模型共用同一套参数，差异只在 `model` 值和尺寸上限。
-
-| 字段 | 类型 | 必填 | 默认 | 约束 |
-|---|---|---|---|---|
-| `model` | string | ✅ | — | 魔搭 AIGC 模型 ID，如 `Qwen/Qwen-Image` |
-| `prompt` | string | ✅ | — | < 2000 字符；多数模型英文效果更好 |
-| `negative_prompt` | string | | — | < 2000 字符 |
-| `size` | string | | — | `WxH` 格式，**上限按模型分档，见下表** |
-| `seed` | int | | — | [0, 2³¹−1] |
-| `steps` | int | | 30 | [1, 100] |
-| `guidance` | float | | 3.5 | [1.5, 20] |
-| `image_url` | string \| **string[]** | | — | 仅图片编辑模型；公网 URL 或 base64 data URL |
-| `loras` | string \| dict | | — | 单个 `"<repo-id>"`；多个 `{"<id1>":0.6,"<id2>":0.4}`；**最多 6 个，权重和必须 = 1.0**，须与基模型兼容 |
-
-**没有 `n` 或图片数量参数——一次只出一张。**
-
-### `image_url` 支持数组（已确认）
-
-`Qwen/Qwen-Image-Edit-2509` 的官方示例代码里 `image_url` 就是数组，并明确给出了双图编辑的注释示例。官方参数表把类型写成 `string` 是**表述滞后**，以模型页示例为准。本项目发送数组的做法是正确的。
-
-### 尺寸上限分档
-
-| 模型family | `size` 范围 |
-|---|---|
-| SD 系列 | [64×64, 2048×2048] |
-| FLUX | **[64×64, 1024×1024]** |
-| Qwen-Image | [64×64, 1664×1664] |
-| Z-Image-Turbo | **[512×512, 2048×2048]** |
-
-> 已按模型分档：`buildModelscopeRequest` 接受 `sizeBounds`，各模型在 builder 里下发自己的上下界。此前统一用 `[64, 2048]`，FLUX 超过 1024 会被拒、Z-Image-Turbo 低于 512 不合法。
-
-## 5. 计费：魔粒，不是钱
-
-魔搭**不按人民币计价、没有充值入口**。消耗的是「魔粒」积分，主要靠每日登录和社区行为免费获取。
-
-### 扣减档位
-
-| 档位（`CostTier`） | 魔粒/次 | 项目已适配模型 |
-|---|---|---|
-| 轻量模型 | 0.5 | — |
-| 主流模型 `standard` | 1 | Z-Image-Turbo、FLUX.1-Krea-dev、majicMIX_realistic、14_ckpt_SD_XL |
-| 旗舰模型 `ultra` | 2 | Qwen-Image、Qwen-Image-Edit-2509 |
-
-### 魔粒获取
-
-| 行为 | 额度 | 有效期 | 频次 |
-|---|---|---|---|
-| 注册并登录 | **200/日** | 24 小时 | 每日 1 次 |
-| 绑定阿里云账号 | **+50/日** | 24 小时 | 每日 1 次 |
-| 验证邮箱 / 编辑个人介绍 / 配置个人主页 | 各 50 | 90 天 | 各首次 |
-| 发表评论 | 5/次 | 短期 | ≤2 次/日 |
-| 收藏 / 喜欢 | 2/次 | 短期 | ≤20 次/日 |
-| 邀请好友 / 受邀注册 | 20/人、50 | 长期 | 50 人/月、首次 |
-
-**日常稳态免费额度 = 250 魔粒/天**（登录 200 + 绑定阿里云 50，均为短期魔粒，24 小时过期不累积）。换算到本项目：
-
-- 旗舰档（Qwen-Image / Qwen-Image-Edit-2509）：**约 125 次/天**
-- 主流档（Z-Image-Turbo / FLUX / majicMIX / SDXL）：**约 250 次/天**
-
-### 其他计费规则
-
-- **没有固定的每日调用次数上限**，上限由魔粒余额决定
-- 短期/长期魔粒消耗时等价，系统自动优先扣最临近过期的
-- **失败返还**：系统原因导致的推理失败全额返还；用户主动取消的推理任务也全额返还
-- **并发是动态限流的**，官方只承诺「保障开发者单并发正常使用」，并明确说明「请勿用于需要高并发以及 SLA 保障的线上任务」
-
-> 已修正：`Currency` 类型增加非货币单位 `魔粒`，`priceDisplay` 对其不做汇率换算、按「数量 + 单位」渲染。固定 catalog 模型按官方档位标注（Qwen 系 2 魔粒，其余 1 魔粒）。自定义入口不再假定主流档 1 魔粒：保存前校验成功时持久化接口返回的 `CostTier` 与 `EstimatedMagicGrainCost` 并交给 SDK 计价；旧记录或校验为 `unknown` 时不显示确定金额，避免误导。
-
-### 高并发替代路径：API-Provider
-
-在个人中心托管外部供应商（DashScope、DeepSeek 等）的 API Key，然后用 `model='<模型ID>:<Provider名>'` 调用，走同一套接口和魔搭 Token 鉴权，**不受免费流控限制，平台不收费**，费用由外部供应商结算。目前官方文档只演示了 LLM，未见图像模型的 Provider 支持。
-
-## 6. 可用性判定方法
-
-「模型在魔搭有页面」和「模型支持 API-Inference 调用」是两回事，必须确认后者。权威判定接口（无需登录）：
-
-```
-GET https://www.modelscope.cn/api/v1/inference/list_model_providers?ModelId=<id>
-```
-
-三种响应（2026-08-26 实测）：
-
-| 情况 | 响应 |
-|---|---|
-| 支持 API-Inference | `200` + `Data.Providers` 数组，含 `CostTier` 与 `EstimatedMagicGrainCost` |
-| 模型存在但未开放 API-Inference | `200` + `Data.Providers: null, TotalCount: 0` |
-| **模型 ID 查不到** | **`HTTP 500`**（不是 404，也不是 200+空结果；用多个不存在的 ID 复现一致） |
-
-500 同时也是通用服务端错误码，无法从状态码本身区分「拼错了」和「魔搭挂了」，提示文案需要同时覆盖两种可能。
-
-另有 `GET /api/v1/inference/<ns>/<name>/api_inference_example` 返回官方示例代码与 `InferenceType`。
-
-**自定义模型入口已接入该校验**（`src/services/modelscopeCustomModels/availability.ts`，走 `nativeFetch` PAL 通道，未新增 IPC）：保存前查询，`unavailable` 与 `not-found` 直接拦下并给出对应提示；`available` 将 `CostTier` 与 `EstimatedMagicGrainCost` 随模型配置持久化并注册到 SDK；`unknown`（断网/超时/其他非 2xx）放行但警告，并把价格保持为未知——校验跑不通是我们这边的问题，不该因此挡住用户，也不能伪装成 1 魔粒。
-
-> API-Inference 只覆盖魔搭挑选的一个子集（依据点赞/下载热度），官方明确说明「随着新模型的推出，比较早的模型可能逐渐从 API-Inference 下架」。已实测不支持的热门模型包括 `black-forest-labs/FLUX.1-dev`、`FLUX.1-Kontext-dev`、`Tencent-Hunyuan/HunyuanImage-3.0`、`stabilityai/stable-diffusion-3.5-large`、`HiDream-ai/HiDream-O1-Image`。
->
-> 注意 `black-forest-labs/FLUX.1-dev` 曾被用作添加表单的占位示例，而它恰恰**不支持** API-Inference，已改为 `Tongyi-MAI/Z-Image-Turbo`。
-
-## 7. 在售模型（已适配）
-
-| Model ID | 类型 | 档位 | 魔粒/次 |
-|---|---|---|---|
-| `Qwen/Qwen-Image` | 文生图 | ultra | 2 |
-| `Qwen/Qwen-Image-Edit-2509` | 图生图 | ultra | 2 |
-| `Tongyi-MAI/Z-Image-Turbo` | 文生图 | standard | 1 |
-| `black-forest-labs/FLUX.1-Krea-dev` | 文生图 | standard | 1 |
-| `MusePublic/majicMIX_realistic` | 文生图 | standard | 1 |
-| `MusePublic/14_ckpt_SD_XL` | 文生图 | standard | 1 |
-
-全部经 `list_model_providers` 确认当前可用。
-
-### 当前可用、项目尚未接入
-
-| Model ID | 类型 | 魔粒/次 | 说明 |
-|---|---|---|---|
-| `Qwen/Qwen-Image-2512` | 文生图 | 2 | Qwen-Image 的 12 月更新版，可直接替代 `Qwen/Qwen-Image` |
-| `Qwen/Qwen-Image-Edit-2511` | 图生图 | 2 | 2509 的直接后继，同样支持数组多图编辑 |
-| `krea/Krea-2-Turbo` | 文生图 | 1 | |
-| `black-forest-labs/FLUX.2-klein-base-9B` | 文生图 | 2 | |
-| `FireRedTeam/FireRed-Image-Edit-1.1` | 图生图 | 2 | |
-| `Tongyi-MAI/Z-Image` | 文生图 | 1 | 非 Turbo 版 |
-| `MAILAND/majicflus_v1` | 文生图 | 1 | |
-
-## 8. 主清单模型的覆盖情况
-
-项目「常用优秀模型清单」共 18 个，**魔搭只提供其中 1 个**：
-
-| 清单模型 | 魔搭 |
-|---|---|
-| Z-Image Turbo | ✅ 提供，见 [Z-Image-Turbo_魔搭.md](../Z-Image-Turbo/Z-Image-Turbo_魔搭.md) |
-| 其余 17 个 | ❌ 全部没有 |
-
-原因是结构性的：魔搭 API-Inference 只服务**魔搭上托管的开源权重模型**，而清单里基本全是闭源商业 API 模型。站内搜到的 Seedream / Nano Banana / Midjourney / Grok 条目**全是社区用户上传的风格 LoRA**，不是模型本体，也不支持 API-Inference。
-
-**视频类 9 个全部不可能**：魔搭 API-Inference 根本不提供视频生成——文档只定义了 `image_generation` 一种任务类型，覆盖范围明确写的是「开源大语言模型（LLM），多模态模型（MLLM），以及 AIGC 专区**文生图**模型」。MiniMax H3 是唯一一个权重真实存在于魔搭的清单视频模型，但不在 API-Inference 范围内。
-
-### 关于 Qwen Image 3.0
-
-**魔搭上没有 Qwen Image 3.0**，`Qwen/Qwen-Image-3.0` 这个 ID 不存在。
-
-Qwen 官方在魔搭的图像模型只有 4 个：`Qwen/Qwen-Image`、`Qwen/Qwen-Image-Edit-2509`、`Qwen/Qwen-Image-Edit-2511`、`Qwen/Qwen-Image-2512`。其中 `Qwen-Image-2512` 的模型卡自述是「Qwen-Image 文生图基础模型的 12 月更新版」，**不是** 3.0。清单里的 Qwen Image 3.0 是通义的闭源商业版本，两条线不同。
-
-> 若要在魔搭侧跟进 Qwen 图像新版本，正确的 ID 是 `Qwen/Qwen-Image-2512`（文生图）和 `Qwen/Qwen-Image-Edit-2511`（图片编辑）。
-
-## 9. 适配要点
-
-- 全部模型共用同一个端点与同一套参数，**只有 `model` 值和尺寸上限不同**；不要为每个模型复制一份 builder。
-- 尺寸边界必须按模型分档，不能统一用 [64, 2048]。
-- 计价不能用货币表达，应按魔粒档位展示。
-- 自定义模型入口在保存前调 `list_model_providers` 校验可用性；成功时复用并持久化返回的 `CostTier` / `EstimatedMagicGrainCost`，校验失败（`unknown`）时放行并警告、价格保持未知，不要当成不支持或默认成 1 魔粒。
-- 项目默认隐藏的参数（`seed`、负面提示词）：魔搭两个字段都有，按项目约定**不显示、不请求**。
-
-## 10. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| API-Inference 介绍与完整参数表 | https://www.modelscope.cn/docs/model-service/API-Inference/intro | 否 |
-| API-Inference 限制与覆盖范围 | https://www.modelscope.cn/docs/model-service/API-Inference/limits | 否 |
-| 魔粒说明（获取与消耗规则） | https://www.modelscope.cn/docs/magicube/intro | 否 |
-| API-Provider（高并发替代路径） | https://www.modelscope.cn/docs/model-service/API-Inference/api-provider | 否 |
-| 模型可用性判定接口 | https://www.modelscope.cn/api/v1/inference/list_model_providers?ModelId=&lt;id&gt; | 否 |
-| 官方示例代码接口 | https://www.modelscope.cn/api/v1/inference/&lt;ns&gt;/&lt;name&gt;/api_inference_example | 否 |
-| Qwen-Image-2512 模型卡 | https://www.modelscope.cn/models/Qwen/Qwen-Image-2512 | 否 |
-| Token 管理 | https://www.modelscope.cn/my/myaccesstoken | **是** |
+# 魔搭 ModelScope · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 供应商类型 | 开源模型托管平台（API-Inference 服务） |
+| 覆盖模态 | **仅图片**（无视频、无音频） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 结算方式 | **魔粒积分，不是货币** |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api-inference.modelscope.cn`
+- **鉴权**：`Authorization: Bearer <MODELSCOPE_TOKEN>`
+- **提交**：`POST /v1/images/generations`，请求头 `X-ModelScope-Async-Mode: true` → 返回 `{ "task_id": "..." }`
+- **查询**：`GET /v1/tasks/<task_id>`，请求头 `X-ModelScope-Task-Type: image_generation`
+- **状态字段**：`task_status`，枚举 `SUCCEED` / `FAILED`（官方示例每 5 秒轮询一次）
+- **结果字段**：`output_images`（字符串数组）
+
+### 提交路由的历史问题（已修正）
+
+代码曾把提交路由写成 `/api/v1/jobs/createTask`——那是 **KIE 的路由格式**，在一次批量改动里被复制串了供应商。已改为官方的 `/v1/images/generations`。
+
+该常量现在只有 `packages/ai-sdk/src/catalog/modelscope/utils.ts` 一份实现；所有魔搭模型的真实 builder 直接复用它。`packages/ai-sdk/tests/catalog/modelscope.test.ts` 同时验证共享函数和 catalog builder，避免路由或图片来源静默分叉。
+
+> ⚠️ 修正**尚未用真实 token 实测确认**——本机网络无法连通 `api-inference.modelscope.cn`，且未配置魔搭 Token。依据是官方文档与每个模型页示例代码的一致写法（无一例外）。首次真实调用时优先验证这一项。
+
+## 2. 硬前提（不满足则完全不可用）
+
+1. 魔搭账号**必须绑定阿里云账号**
+2. 该阿里云账号**必须已完成实名认证**
+
+## 3. 文件上传
+
+魔搭没有独立的文件上传端点。官方做法是把本地图片转成 `data:<mime>;base64,...` 直接放进 `image_url` 字段，文档提供了 `image_to_data_url()` 工具函数。
+
+本项目的处理（`upload.ts` → `uploadForHostedUrl`）：**优先借用 KIE 的上传服务**换公网 URL，KIE Key 未配置或上传失败时**静默退回 data URI**。因为有兜底，魔搭模型不会像 PPIO 那样因为缺 KIE Key 直接失败。
+
+请求体里图片来源有三个键，builder 必须都认：生成页提交是 `uploadedFilePaths`，画布节点是 `images`，旧工程可能直接存 `image_url`。历史动态运行时副本曾漏掉 `uploadedFilePaths`；SDK 直连后已删除该副本，并由真实 catalog builder 测试锁定行为。
+
+## 4. 请求参数（全模型通用）
+
+魔搭 API-Inference 是统一接口，所有图像模型共用同一套参数，差异只在 `model` 值和尺寸上限。
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `model` | string | ✅ | — | 魔搭 AIGC 模型 ID，如 `Qwen/Qwen-Image` |
+| `prompt` | string | ✅ | — | < 2000 字符；多数模型英文效果更好 |
+| `negative_prompt` | string | | — | < 2000 字符 |
+| `size` | string | | — | `WxH` 格式，**上限按模型分档，见下表** |
+| `seed` | int | | — | [0, 2³¹−1] |
+| `steps` | int | | 30 | [1, 100] |
+| `guidance` | float | | 3.5 | [1.5, 20] |
+| `image_url` | string \| **string[]** | | — | 仅图片编辑模型；公网 URL 或 base64 data URL |
+| `loras` | string \| dict | | — | 单个 `"<repo-id>"`；多个 `{"<id1>":0.6,"<id2>":0.4}`；**最多 6 个，权重和必须 = 1.0**，须与基模型兼容 |
+
+**没有 `n` 或图片数量参数——一次只出一张。**
+
+### `image_url` 支持数组（已确认）
+
+`Qwen/Qwen-Image-Edit-2509` 的官方示例代码里 `image_url` 就是数组，并明确给出了双图编辑的注释示例。官方参数表把类型写成 `string` 是**表述滞后**，以模型页示例为准。本项目发送数组的做法是正确的。
+
+### 尺寸上限分档
+
+| 模型family | `size` 范围 |
+|---|---|
+| SD 系列 | [64×64, 2048×2048] |
+| FLUX | **[64×64, 1024×1024]** |
+| Qwen-Image | [64×64, 1664×1664] |
+| Z-Image-Turbo | **[512×512, 2048×2048]** |
+
+> 已按模型分档：`buildModelscopeRequest` 接受 `sizeBounds`，各模型在 builder 里下发自己的上下界。此前统一用 `[64, 2048]`，FLUX 超过 1024 会被拒、Z-Image-Turbo 低于 512 不合法。
+
+## 5. 计费：魔粒，不是钱
+
+魔搭**不按人民币计价、没有充值入口**。消耗的是「魔粒」积分，主要靠每日登录和社区行为免费获取。
+
+### 扣减档位
+
+| 档位（`CostTier`） | 魔粒/次 | 项目已适配模型 |
+|---|---|---|
+| 轻量模型 | 0.5 | — |
+| 主流模型 `standard` | 1 | Z-Image-Turbo、FLUX.1-Krea-dev、majicMIX_realistic、14_ckpt_SD_XL |
+| 旗舰模型 `ultra` | 2 | Qwen-Image、Qwen-Image-Edit-2509 |
+
+### 魔粒获取
+
+| 行为 | 额度 | 有效期 | 频次 |
+|---|---|---|---|
+| 注册并登录 | **200/日** | 24 小时 | 每日 1 次 |
+| 绑定阿里云账号 | **+50/日** | 24 小时 | 每日 1 次 |
+| 验证邮箱 / 编辑个人介绍 / 配置个人主页 | 各 50 | 90 天 | 各首次 |
+| 发表评论 | 5/次 | 短期 | ≤2 次/日 |
+| 收藏 / 喜欢 | 2/次 | 短期 | ≤20 次/日 |
+| 邀请好友 / 受邀注册 | 20/人、50 | 长期 | 50 人/月、首次 |
+
+**日常稳态免费额度 = 250 魔粒/天**（登录 200 + 绑定阿里云 50，均为短期魔粒，24 小时过期不累积）。换算到本项目：
+
+- 旗舰档（Qwen-Image / Qwen-Image-Edit-2509）：**约 125 次/天**
+- 主流档（Z-Image-Turbo / FLUX / majicMIX / SDXL）：**约 250 次/天**
+
+### 其他计费规则
+
+- **没有固定的每日调用次数上限**，上限由魔粒余额决定
+- 短期/长期魔粒消耗时等价，系统自动优先扣最临近过期的
+- **失败返还**：系统原因导致的推理失败全额返还；用户主动取消的推理任务也全额返还
+- **并发是动态限流的**，官方只承诺「保障开发者单并发正常使用」，并明确说明「请勿用于需要高并发以及 SLA 保障的线上任务」
+
+> 已修正：`Currency` 类型增加非货币单位 `魔粒`，`priceDisplay` 对其不做汇率换算、按「数量 + 单位」渲染。固定 catalog 模型按官方档位标注（Qwen 系 2 魔粒，其余 1 魔粒）。自定义入口不再假定主流档 1 魔粒：保存前校验成功时持久化接口返回的 `CostTier` 与 `EstimatedMagicGrainCost` 并交给 SDK 计价；旧记录或校验为 `unknown` 时不显示确定金额，避免误导。
+
+### 高并发替代路径：API-Provider
+
+在个人中心托管外部供应商（DashScope、DeepSeek 等）的 API Key，然后用 `model='<模型ID>:<Provider名>'` 调用，走同一套接口和魔搭 Token 鉴权，**不受免费流控限制，平台不收费**，费用由外部供应商结算。目前官方文档只演示了 LLM，未见图像模型的 Provider 支持。
+
+## 6. 可用性判定方法
+
+「模型在魔搭有页面」和「模型支持 API-Inference 调用」是两回事，必须确认后者。权威判定接口（无需登录）：
+
+```
+GET https://www.modelscope.cn/api/v1/inference/list_model_providers?ModelId=<id>
+```
+
+三种响应（2026-08-26 实测）：
+
+| 情况 | 响应 |
+|---|---|
+| 支持 API-Inference | `200` + `Data.Providers` 数组，含 `CostTier` 与 `EstimatedMagicGrainCost` |
+| 模型存在但未开放 API-Inference | `200` + `Data.Providers: null, TotalCount: 0` |
+| **模型 ID 查不到** | **`HTTP 500`**（不是 404，也不是 200+空结果；用多个不存在的 ID 复现一致） |
+
+500 同时也是通用服务端错误码，无法从状态码本身区分「拼错了」和「魔搭挂了」，提示文案需要同时覆盖两种可能。
+
+另有 `GET /api/v1/inference/<ns>/<name>/api_inference_example` 返回官方示例代码与 `InferenceType`。
+
+**自定义模型入口已接入该校验**（`src/services/modelscopeCustomModels/availability.ts`，走 `nativeFetch` PAL 通道，未新增 IPC）：保存前查询，`unavailable` 与 `not-found` 直接拦下并给出对应提示；`available` 将 `CostTier` 与 `EstimatedMagicGrainCost` 随模型配置持久化并注册到 SDK；`unknown`（断网/超时/其他非 2xx）放行但警告，并把价格保持为未知——校验跑不通是我们这边的问题，不该因此挡住用户，也不能伪装成 1 魔粒。
+
+> API-Inference 只覆盖魔搭挑选的一个子集（依据点赞/下载热度），官方明确说明「随着新模型的推出，比较早的模型可能逐渐从 API-Inference 下架」。已实测不支持的热门模型包括 `black-forest-labs/FLUX.1-dev`、`FLUX.1-Kontext-dev`、`Tencent-Hunyuan/HunyuanImage-3.0`、`stabilityai/stable-diffusion-3.5-large`、`HiDream-ai/HiDream-O1-Image`。
+>
+> 注意 `black-forest-labs/FLUX.1-dev` 曾被用作添加表单的占位示例，而它恰恰**不支持** API-Inference，已改为 `Tongyi-MAI/Z-Image-Turbo`。
+
+## 7. 在售模型（已适配）
+
+| Model ID | 类型 | 档位 | 魔粒/次 |
+|---|---|---|---|
+| `Qwen/Qwen-Image` | 文生图 | ultra | 2 |
+| `Qwen/Qwen-Image-Edit-2509` | 图生图 | ultra | 2 |
+| `Tongyi-MAI/Z-Image-Turbo` | 文生图 | standard | 1 |
+| `black-forest-labs/FLUX.1-Krea-dev` | 文生图 | standard | 1 |
+| `MusePublic/majicMIX_realistic` | 文生图 | standard | 1 |
+| `MusePublic/14_ckpt_SD_XL` | 文生图 | standard | 1 |
+
+全部经 `list_model_providers` 确认当前可用。
+
+### 当前可用、项目尚未接入
+
+| Model ID | 类型 | 魔粒/次 | 说明 |
+|---|---|---|---|
+| `Qwen/Qwen-Image-2512` | 文生图 | 2 | Qwen-Image 的 12 月更新版，可直接替代 `Qwen/Qwen-Image` |
+| `Qwen/Qwen-Image-Edit-2511` | 图生图 | 2 | 2509 的直接后继，同样支持数组多图编辑 |
+| `krea/Krea-2-Turbo` | 文生图 | 1 | |
+| `black-forest-labs/FLUX.2-klein-base-9B` | 文生图 | 2 | |
+| `FireRedTeam/FireRed-Image-Edit-1.1` | 图生图 | 2 | |
+| `Tongyi-MAI/Z-Image` | 文生图 | 1 | 非 Turbo 版 |
+| `MAILAND/majicflus_v1` | 文生图 | 1 | |
+
+## 8. 主清单模型的覆盖情况
+
+项目「常用优秀模型清单」共 18 个，**魔搭只提供其中 1 个**：
+
+| 清单模型 | 魔搭 |
+|---|---|
+| Z-Image Turbo | ✅ 提供，见 [Z-Image-Turbo_魔搭.md](../Z-Image-Turbo/Z-Image-Turbo_魔搭.md) |
+| 其余 17 个 | ❌ 全部没有 |
+
+原因是结构性的：魔搭 API-Inference 只服务**魔搭上托管的开源权重模型**，而清单里基本全是闭源商业 API 模型。站内搜到的 Seedream / Nano Banana / Midjourney / Grok 条目**全是社区用户上传的风格 LoRA**，不是模型本体，也不支持 API-Inference。
+
+**视频类 9 个全部不可能**：魔搭 API-Inference 根本不提供视频生成——文档只定义了 `image_generation` 一种任务类型，覆盖范围明确写的是「开源大语言模型（LLM），多模态模型（MLLM），以及 AIGC 专区**文生图**模型」。MiniMax H3 是唯一一个权重真实存在于魔搭的清单视频模型，但不在 API-Inference 范围内。
+
+### 关于 Qwen Image 3.0
+
+**魔搭上没有 Qwen Image 3.0**，`Qwen/Qwen-Image-3.0` 这个 ID 不存在。
+
+Qwen 官方在魔搭的图像模型只有 4 个：`Qwen/Qwen-Image`、`Qwen/Qwen-Image-Edit-2509`、`Qwen/Qwen-Image-Edit-2511`、`Qwen/Qwen-Image-2512`。其中 `Qwen-Image-2512` 的模型卡自述是「Qwen-Image 文生图基础模型的 12 月更新版」，**不是** 3.0。清单里的 Qwen Image 3.0 是通义的闭源商业版本，两条线不同。
+
+> 若要在魔搭侧跟进 Qwen 图像新版本，正确的 ID 是 `Qwen/Qwen-Image-2512`（文生图）和 `Qwen/Qwen-Image-Edit-2511`（图片编辑）。
+
+## 9. 适配要点
+
+- 全部模型共用同一个端点与同一套参数，**只有 `model` 值和尺寸上限不同**；不要为每个模型复制一份 builder。
+- 尺寸边界必须按模型分档，不能统一用 [64, 2048]。
+- 计价不能用货币表达，应按魔粒档位展示。
+- 自定义模型入口在保存前调 `list_model_providers` 校验可用性；成功时复用并持久化返回的 `CostTier` / `EstimatedMagicGrainCost`，校验失败（`unknown`）时放行并警告、价格保持未知，不要当成不支持或默认成 1 魔粒。
+- 项目默认隐藏的参数（`seed`、负面提示词）：魔搭两个字段都有，按项目约定**不显示、不请求**。
+
+## 10. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| API-Inference 介绍与完整参数表 | https://www.modelscope.cn/docs/model-service/API-Inference/intro | 否 |
+| API-Inference 限制与覆盖范围 | https://www.modelscope.cn/docs/model-service/API-Inference/limits | 否 |
+| 魔粒说明（获取与消耗规则） | https://www.modelscope.cn/docs/magicube/intro | 否 |
+| API-Provider（高并发替代路径） | https://www.modelscope.cn/docs/model-service/API-Inference/api-provider | 否 |
+| 模型可用性判定接口 | https://www.modelscope.cn/api/v1/inference/list_model_providers?ModelId=&lt;id&gt; | 否 |
+| 官方示例代码接口 | https://www.modelscope.cn/api/v1/inference/&lt;ns&gt;/&lt;name&gt;/api_inference_example | 否 |
+| Qwen-Image-2512 模型卡 | https://www.modelscope.cn/models/Qwen/Qwen-Image-2512 | 否 |
+| Token 管理 | https://www.modelscope.cn/my/myaccesstoken | **是** |