@henjicc/ai-sdk 0.2.8 → 0.4.0

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 | **是** |