@henjicc/ai-sdk 0.8.0 → 0.10.0

package/docs/model-adaptation/MiniMax-H3/MiniMax-H3_Fal.md

@@ -1,108 +1,112 @@
-# MiniMax H3 · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-30 |
-| 模态 | 视频 |
-| 供应商 | fal.ai（聚合平台） |
-| 平台模型 ID | `minimax/h3/text-to-video`、`minimax/h3/image-to-video`、`minimax/h3/reference-to-video` |
-| 接口形态 | 队列异步（推荐）或同步直连 |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-## 1. 接入协议（Fal 通用）
-
-- **鉴权**：`Authorization: Key $FAL_KEY`
-- **同步**：`POST https://fal.run/<endpoint-id>`；**队列**：`POST https://queue.fal.run/<endpoint-id>`，`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）、`GET .../requests/{id}`
-- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
-
-## 2. 能力清单
-
-| 能力 | endpoint id |
-|---|---|
-| 文生视频 | `minimax/h3/text-to-video` |
-| 图生视频（首帧 / 首尾帧） | `minimax/h3/image-to-video` |
-| 参考生视频（图 + 视频 + 音频） | `minimax/h3/reference-to-video` |
-
-## 3. 请求参数
-
-### 3.1 三个端点共有
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `prompt` | string | 必填 | — | 视频描述。`reference-to-video` 中用 **`Image 1` / `Video 1` / `Audio 1`** 按模态与顺序引用素材 |
-| `duration` | integer | 可选 | `5` | **5 ~ 15**（**注意下限是 5，不是 4**；APIMart / KIE 都是 4） |
-| `resolution` | string | 可选 | **`2K`** | `480P` / `768P` / `2K` / `4K`。**`480P` 与 `768P` 是原生生成；`2K` 与 `4K` 是在 768P 基础上超分** |
-| `seed` | integer | 可选 | 随机 | **本项目规则：绝对不显示**，不下发 |
-| `enable_prompt_expansion` | boolean | 可选 | **`true`** | 生成前用视觉语言模型扩写提示词 |
-| `enable_safety_checker` | boolean | 可选 | `true` | 安全检查 |
-| `prompt_expansion_mode` | string | 可选 | `balanced` | `fast`（fal 自家扩写，约 1 s）/ `quality`（**始终用 MiniMax 的 H3-Context-IR，约 30 s**）/ `balanced`（参考生视频、以及 5 秒以上的图生视频（480P 除外）用 H3-Context-IR；所有文生视频用 fal 自家扩写） |
-
-### 3.2 仅 `text-to-video` 与 `reference-to-video`
-
-| 字段 | 类型 | 默认 | 取值 |
-|---|---|---|---|
-| `aspect_ratio` | string | 文生 **`16:9`**；参考 **`adaptive`** | 文生：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`（**无 `adaptive`**）；参考：另含 `adaptive` |
-
-### 3.3 仅 `image-to-video`
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `image_url` | string | 可选 | 首帧图 URL。**提供时输出比例跟随该图**；**省略时该请求按文生视频处理（默认 16:9）** |
-| `end_image_url` | string | 可选 | 尾帧图 URL，用于首尾帧生成 |
-
-> 该端点**没有 `aspect_ratio`**。
-
-### 3.4 仅 `reference-to-video`
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `reference_image_urls` | string[] | 主体 / 风格参考图，prompt 中以 `Image 1`、`Image 2` 引用 |
-| `reference_video_urls` | string[] | 运动 / 参考视频片段，单段 2–15 s，合计 ≤ 15 s，prompt 中以 `Video 1` 引用 |
-| `reference_audio_urls` | string[] | 参考音频，单段 2–15 s，合计 ≤ 15 s，prompt 中以 `Audio 1` 引用。**音频不能是唯一的参考输入，必须至少配一张参考图或一个参考视频** |
-
-> **参考图 / 视频 / 音频合计最多 12 个文件。**
-
-## 4. 响应结构
-
-```json
-{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" },
-  "expanded_prompt": "（扩写后实际下发给模型的提示词）" }
-```
-
-`expanded_prompt` 是可选字段：当提示词扩写被关闭、扩写未改动提示词、或扩写由 MiniMax 托管 API 内部完成时为 `null`。
-
-## 5. 价格
-
-来源：三个端点的 `llms.txt`（2026-08-30 重新读取）。本次核价确认四档视频秒价及参考图加价规则均如下，静态估价应先按时长乘秒价，再追加超过 5 张的参考图费用。
-
-| 分辨率 | 单价 |
-|---|---|
-| 480p | **$0.05 / 秒** |
-| 768p | **$0.06 / 秒** |
-| 2K | **$0.13 / 秒** |
-| 4K | **$0.16 / 秒** |
-
-`reference-to-video` 额外：**前 5 张参考图免费，之后每张 $0.08**；这笔参考图费用按张追加一次，不再乘视频时长。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**有 `seed`**（不下发），无负面提示词。
-- **`duration` 下限是 5**（APIMart / KIE 是 4），跨供应商的时长选项要按供应商裁剪。
-- **Fal 独有 `480P` 与 `4K` 档位**（APIMart / KIE 只有 768P / 2K）；且文档明确 2K/4K 是 768P 超分而非原生。
-- `prompt_expansion_mode` 是 Fal 独有的封装：`quality` 相当于自动帮你调了 Context-IR，省去 APIMart 上手动两步。默认 `balanced` 会按端点与时长自动切换，行为不完全可预测——若要结果稳定应显式指定。
-- `image-to-video` 的 `image_url` **是可选的**，不传会静默退化成文生视频，参数校验要覆盖。
-- 比例参数只在文生视频与参考生视频显示；图生视频端点没有 `aspect_ratio`，输出比例跟随输入图。
-- 三种输入形态是三个独立 endpoint，需要路由。
-- 路由、请求与计价必须共用同一套图片来源解析，兼容生成提交的 `uploadedFilePaths`、画布的 `images` 与对话面板的 `uploadedImages`，并忽略空值。
-- `reference-to-video` 的素材在 prompt 中用 `Image 1` / `Video 1` / `Audio 1` 引用（**注意与 Seedance 的 `@Image1` 写法不同**）。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| 文生视频 schema + 价格 | https://fal.ai/models/minimax/h3/text-to-video/llms.txt | 否 |
-| 图生视频 schema + 价格 | https://fal.ai/models/minimax/h3/image-to-video/llms.txt | 否 |
-| 参考生视频 schema + 价格 | https://fal.ai/models/minimax/h3/reference-to-video/llms.txt | 否 |
-| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
-| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+# MiniMax H3 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `minimax/h3/text-to-video`、`minimax/h3/image-to-video`、`minimax/h3/reference-to-video` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议（Fal 通用）
+
+- **鉴权**：`Authorization: Key $FAL_KEY`
+- **同步**：`POST https://fal.run/<endpoint-id>`；**队列**：`POST https://queue.fal.run/<endpoint-id>`，`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）、`GET .../requests/{id}`
+- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
+
+## 2. 能力清单
+
+| 能力 | endpoint id |
+|---|---|
+| 文生视频 | `minimax/h3/text-to-video` |
+| 图生视频（首帧 / 首尾帧） | `minimax/h3/image-to-video` |
+| 参考生视频（图 + 视频 + 音频） | `minimax/h3/reference-to-video` |
+
+## 3. 请求参数
+
+### 3.1 三个端点共有
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 视频描述。`reference-to-video` 中用 **`Image 1` / `Video 1` / `Audio 1`** 按模态与顺序引用素材 |
+| `duration` | integer | 可选 | `5` | **5 ~ 15**（**注意下限是 5，不是 4**；APIMart / KIE 都是 4） |
+| `resolution` | string | 可选 | **`2K`** | `480P` / `768P` / `2K` / `4K`。**`480P` 与 `768P` 是原生生成；`2K` 与 `4K` 是在 768P 基础上超分** |
+| `seed` | integer | 可选 | 随机 | **本项目规则：绝对不显示**，不下发 |
+| `enable_prompt_expansion` | boolean | 可选 | **`true`** | 生成前用视觉语言模型扩写提示词 |
+| `enable_safety_checker` | boolean | 可选 | `true` | 安全检查 |
+| `prompt_expansion_mode` | string | 可选 | `balanced` | `fast`（fal 自家扩写，约 1 s）/ `quality`（**始终用 MiniMax 的 H3-Context-IR，约 30 s**）/ `balanced`（参考生视频、以及 5 秒以上的图生视频（480P 除外）用 H3-Context-IR；所有文生视频用 fal 自家扩写） |
+
+### 3.2 仅 `text-to-video` 与 `reference-to-video`
+
+| 字段 | 类型 | 默认 | 取值 |
+|---|---|---|---|
+| `aspect_ratio` | string | 文生 **`16:9`**；参考 **`adaptive`** | 文生：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`（**无 `adaptive`**）；参考：另含 `adaptive` |
+
+### 3.3 仅 `image-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_url` | string | 可选 | 首帧图 URL。**提供时输出比例跟随该图**；**省略时该请求按文生视频处理（默认 16:9）** |
+| `end_image_url` | string | 可选 | 尾帧图 URL，用于首尾帧生成 |
+
+> 该端点**没有 `aspect_ratio`**。
+
+### 3.4 仅 `reference-to-video`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `reference_image_urls` | string[] | 主体 / 风格参考图，prompt 中以 `Image 1`、`Image 2` 引用 |
+| `reference_video_urls` | string[] | 运动 / 参考视频片段，单段 2–15 s，合计 ≤ 15 s，prompt 中以 `Video 1` 引用 |
+| `reference_audio_urls` | string[] | 参考音频，单段 2–15 s，合计 ≤ 15 s，prompt 中以 `Audio 1` 引用。**音频不能是唯一的参考输入，必须至少配一张参考图或一个参考视频** |
+
+> **参考图 / 视频 / 音频合计最多 12 个文件。**
+
+## 4. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" },
+  "expanded_prompt": "（扩写后实际下发给模型的提示词）" }
+```
+
+`expanded_prompt` 是可选字段：当提示词扩写被关闭、扩写未改动提示词、或扩写由 MiniMax 托管 API 内部完成时为 `null`。
+
+## 5. 价格
+
+来源：三个端点的 `llms.txt`（2026-08-30 重新读取）。本次核价确认四档视频秒价及参考图加价规则均如下，静态估价应先按时长乘秒价，再追加超过 5 张的参考图费用。
+
+| 分辨率 | 单价 |
+|---|---|
+| 480p | **$0.05 / 秒** |
+| 768p | **$0.06 / 秒** |
+| 2K | **$0.13 / 秒** |
+| 4K | **$0.16 / 秒** |
+
+`reference-to-video` 额外：**前 5 张参考图免费，之后每张 $0.08**；这笔参考图费用按张追加一次，不再乘视频时长。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**有 `seed`**（不下发），无负面提示词。
+- **`duration` 下限是 5**（APIMart / KIE 是 4），跨供应商的时长选项要按供应商裁剪。
+- **Fal 独有 `480P` 与 `4K` 档位**（APIMart / KIE 只有 768P / 2K）；且文档明确 2K/4K 是 768P 超分而非原生。
+- `prompt_expansion_mode` 是 Fal 独有的封装：`quality` 相当于自动帮你调了 Context-IR，省去 APIMart 上手动两步。默认 `balanced` 会按端点与时长自动切换，行为不完全可预测——若要结果稳定应显式指定。
+- `image-to-video` 的 `image_url` **是可选的**，不传会静默退化成文生视频，参数校验要覆盖。
+- 比例参数只在文生视频与参考生视频显示；图生视频端点没有 `aspect_ratio`，输出比例跟随输入图。
+- 三种输入形态是三个独立 endpoint，需要路由。
+- 路由、请求与计价必须共用同一套图片来源解析，兼容生成提交的 `uploadedFilePaths`、画布的 `images` 与对话面板的 `uploadedImages`，并忽略空值。
+- `reference-to-video` 的素材在 prompt 中用 `Image 1` / `Video 1` / `Audio 1` 引用（**注意与 Seedance 的 `@Image1` 写法不同**）。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema + 价格 | https://fal.ai/models/minimax/h3/text-to-video/llms.txt | 否 |
+| 图生视频 schema + 价格 | https://fal.ai/models/minimax/h3/image-to-video/llms.txt | 否 |
+| 参考生视频 schema + 价格 | https://fal.ai/models/minimax/h3/reference-to-video/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+
+## 2026-10-12 提示词扩写
+
+三个端点均使用 `prompt_expansion_mode=disabled/fast/balanced/quality`；关闭映射 disabled，开启映射选中档位，不再发送 enable_prompt_expansion。target_audio_url 本批未接入。来源：[文生](https://fal.ai/models/minimax/h3/text-to-video/llms.txt)、[图生](https://fal.ai/models/minimax/h3/image-to-video/llms.txt)、[参考](https://fal.ai/models/minimax/h3/reference-to-video/llms.txt)（公开无需登录）。

package/docs/model-adaptation/MiniMax-H3/MiniMax-H3_KIE.md

@@ -1,111 +1,118 @@
-# MiniMax H3 · KIE
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 视频 |
-| 供应商 | KIE.ai（聚合平台） |
-| 平台模型 ID | `minimax-h3/text-to-video`、`minimax-h3/image-to-video`、`minimax-h3/reference-to-video` |
-| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.kie.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model, callBackUrl?, input }`
-- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
-- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: ["https://....mp4"] }`
-
-## 2. 能力清单
-
-| 能力 | model |
-|---|---|
-| 文生视频 | `minimax-h3/text-to-video` |
-| 图生视频（首帧 / 尾帧 / 首尾帧） | `minimax-h3/image-to-video` |
-| 参考生视频（图 + 视频 + 音频） | `minimax-h3/reference-to-video` |
-
-> KIE 上**没有 Context-IR 提示词增强，也没有 Regeneration 再生成**（APIMart 有）。
-
-## 3. 请求参数
-
-### 3.1 `minimax-h3/text-to-video`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `input.prompt` | string | 必填 | — | 1–7000 字符 |
-| `input.aspect_ratio` | string | **必填** | — | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。**文生视频必填，不支持 `adaptive`** |
-| `input.duration` | integer | **必填** | `6` | 枚举 4–15 的整数（注意 **KIE 默认是 6**，APIMart / Fal 是 5） |
-| `input.resolution` | string | 可选 | `2K` | `768P` / `2K` |
-
-### 3.2 `minimax-h3/image-to-video`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `input.prompt` | string | 必填 | — | 1–7000 字符 |
-| `input.first_frame_url` | string | 可选 | — | 首帧图 URL。支持 HTTP / HTTPS / OSS；JPG、JPEG、PNG、WEBP、HEIC、HEIF；≤ 30 MB；边长 256–5760 px；宽高比 0.4–2.5。**注意：首尾帧必须二选一** |
-| `input.last_frame_url` | string | 可选 | — | 尾帧图 URL，**可单独传**，限制同上。**注意：首尾帧必须二选一** |
-| `input.duration` | integer | **必填** | `6` | 4–15 |
-| `input.resolution` | string | 可选 | `2K` | `768P` / `2K` |
-
-> ⚠️ KIE 的文档在这里自相矛盾：`last_frame_url` 描述既说「可单独传」又说「首尾帧必须二选一」；同时该端点**没有 `aspect_ratio`**。接入前需实测确认能否同时传首尾帧。
-
-### 3.3 `minimax-h3/reference-to-video`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `input.prompt` | string | 必填 | — | 1–7000 字符 |
-| `input.reference_image_urls` | array | 可选 | — | **最多 9 张**。HTTP / HTTPS / OSS；JPG、JPEG、PNG、WEBP、HEIC、HEIF；≤ 30 MB；边长 256–5760 px；宽高比 0.4–2.5 |
-| `input.reference_video_urls` | array | 可选 | — | **最多 3 个**。MP4 / MOV；视频编码 H.264 / H.265，音频编码 AAC / MP3；单个 ≤ 50 MB；单段 2–15 s，合计 ≤ 15 s；边长 256–5760 px；宽高比 0.4–2.5；帧率 23.976–60 |
-| `input.reference_audio_urls` | array | 可选 | — | **最多 3 个**。WAV / MP3；单个 ≤ 15 MB；单段 2–15 s，合计 ≤ 15 s。**不能单独传入，必须同时传 `reference_image_urls` 或 `reference_video_urls`** |
-| `input.aspect_ratio` | string | 可选 | **`adaptive`** | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
-| `input.duration` | integer | **必填** | `6` | 4–15 |
-| `input.resolution` | string | 可选 | `2K` | `768P` / `2K` |
-
-## 4. 响应结构
-
-`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://....mp4"] }`。
-
-## 5. 价格
-
-来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `h3`；1 Credit = $0.005）。
-
-**计费公式（KIE 页面明示）**：
-`总价 = 单价 × (生成视频时长 + 输入视频时长) + 额外图片费用`
-- 输入图片：**前 5 张免费**，超出部分单独计费
-- 输入音频：**免费**
-
-| 规格 | 积分 | 我们的价格 |
-|---|---|---|
-| 文生视频 768p | 16 /秒 | **$0.08/秒** |
-| 文生视频 2K | 26 /秒 | **$0.13/秒** |
-| 图生视频 768p | 16 /秒 | **$0.08/秒** |
-| 图生视频 2K | 26 /秒 | **$0.13/秒** |
-| 参考生视频 768p | 16 /秒 | **$0.08/秒** |
-| 参考生视频 2K | 26 /秒 | **$0.13/秒** |
-| 视频输入 768p | 16 /秒 | **$0.08/秒** |
-| 视频输入 2k | 26 /秒 | **$0.13/秒** |
-| 图片输入（768p / 2k，超出免费额度后） | 8 /张 | **$0.04/张** |
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本组接口都没有这两个字段。
-- **`duration` 在 KIE 是必填且默认 6 秒**，与 APIMart / Fal 的 5 秒默认不同，跨供应商不能共用默认值。
-- 文生视频的 `aspect_ratio` **必填且不支持 `adaptive`**；图生视频端点**根本没有 `aspect_ratio`**；参考生视频默认 `adaptive`。三个端点行为都不一样。
-- `resolution` 默认 `2K`（最贵档），控成本要显式下发 `768P`。
-- 图生视频端点关于首尾帧的描述自相矛盾，接入前必须实测。
-- 输入视频时长会**叠加进计费秒数**；输入图片前 5 张免费。
-- `resultJson` 是 JSON 字符串，必须二次 parse。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| MiniMax H3 文生视频 | https://docs.kie.ai/cn/market/minimax-h3/text-to-video | 否 |
-| MiniMax H3 图生视频 | https://docs.kie.ai/cn/market/minimax-h3/image-to-video | 否 |
-| MiniMax H3 参考生视频 | https://docs.kie.ai/cn/market/minimax-h3/reference-to-video | 否 |
-| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
-| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
-| 定价页（搜 `h3`，含计费公式） | https://kie.ai/pricing | 否 |
-| API Key 管理 | https://kie.ai/api-key | **是** |
+# MiniMax H3 · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `minimax-h3/text-to-video`、`minimax-h3/image-to-video`、`minimax-h3/reference-to-video` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model, callBackUrl?, input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: ["https://....mp4"] }`
+
+## 2. 能力清单
+
+| 能力 | model |
+|---|---|
+| 文生视频 | `minimax-h3/text-to-video` |
+| 图生视频（首帧 / 尾帧 / 首尾帧） | `minimax-h3/image-to-video` |
+| 参考生视频（图 + 视频 + 音频） | `minimax-h3/reference-to-video` |
+
+> KIE 上**没有 Context-IR 提示词增强，也没有 Regeneration 再生成**（APIMart 有）。
+
+## 3. 请求参数
+
+### 3.1 `minimax-h3/text-to-video`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 1–7000 字符 |
+| `input.aspect_ratio` | string | **必填** | — | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。**文生视频必填，不支持 `adaptive`** |
+| `input.duration` | integer | **必填** | `6` | 枚举 4–15 的整数（注意 **KIE 默认是 6**，APIMart / Fal 是 5） |
+| `input.resolution` | string | 可选 | `2K` | `768P` / `2K` |
+
+### 3.2 `minimax-h3/image-to-video`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 1–7000 字符 |
+| `input.first_frame_url` | string | 可选 | — | 首帧图 URL。支持 HTTP / HTTPS / OSS；JPG、JPEG、PNG、WEBP、HEIC、HEIF；≤ 30 MB；边长 256–5760 px；宽高比 0.4–2.5。**注意：首尾帧必须二选一** |
+| `input.last_frame_url` | string | 可选 | — | 尾帧图 URL，**可单独传**，限制同上。**注意：首尾帧必须二选一** |
+| `input.duration` | integer | **必填** | `6` | 4–15 |
+| `input.resolution` | string | 可选 | `2K` | `768P` / `2K` |
+
+> ⚠️ KIE 的文档在这里自相矛盾：`last_frame_url` 描述既说「可单独传」又说「首尾帧必须二选一」；同时该端点**没有 `aspect_ratio`**。接入前需实测确认能否同时传首尾帧。
+
+### 3.3 `minimax-h3/reference-to-video`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 1–7000 字符 |
+| `input.reference_image_urls` | array | 可选 | — | **最多 9 张**。HTTP / HTTPS / OSS；JPG、JPEG、PNG、WEBP、HEIC、HEIF；≤ 30 MB；边长 256–5760 px；宽高比 0.4–2.5 |
+| `input.reference_video_urls` | array | 可选 | — | **最多 3 个**。MP4 / MOV；视频编码 H.264 / H.265，音频编码 AAC / MP3；单个 ≤ 50 MB；单段 2–15 s，合计 ≤ 15 s；边长 256–5760 px；宽高比 0.4–2.5；帧率 23.976–60 |
+| `input.reference_audio_urls` | array | 可选 | — | **最多 3 个**。WAV / MP3；单个 ≤ 15 MB；单段 2–15 s，合计 ≤ 15 s。**不能单独传入，必须同时传 `reference_image_urls` 或 `reference_video_urls`** |
+| `input.aspect_ratio` | string | 可选 | **`adaptive`** | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
+| `input.duration` | integer | **必填** | `6` | 4–15 |
+| `input.resolution` | string | 可选 | `2K` | `768P` / `2K` |
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://....mp4"] }`。
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `h3`；1 Credit = $0.005）。
+
+**计费公式（KIE 页面明示）**：
+`总价 = 单价 × (生成视频时长 + 输入视频时长) + 额外图片费用`
+- 输入图片：**前 5 张免费**，超出部分单独计费
+- 输入音频：**免费**
+
+| 规格 | 积分 | 我们的价格 |
+|---|---|---|
+| 文生视频 768p | 16 /秒 | **$0.04/秒** |
+| 文生视频 2K | 26 /秒 | **$0.065/秒** |
+| 图生视频 768p | 16 /秒 | **$0.04/秒** |
+| 图生视频 2K | 26 /秒 | **$0.065/秒** |
+| 参考生视频 768p | 16 /秒 | **$0.04/秒** |
+| 参考生视频 2K | 26 /秒 | **$0.065/秒** |
+| 视频输入 768p | 16 /秒 | **$0.04/秒** |
+| 视频输入 2k | 26 /秒 | **$0.065/秒** |
+| 图片输入（768p / 2k，超出免费额度后） | 8 /张 | **$0.02/张** |
+
+## 6. 适配要点
+
+- 素材尺寸前置校验（2026-11-08）：图片与参考视频边长 256–5760 px、宽高比 0.4–2.5（`imageConstraints` / `videoConstraints`）。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本组接口都没有这两个字段。
+- **`duration` 在 KIE 是必填且默认 6 秒**，与 APIMart / Fal 的 5 秒默认不同，跨供应商不能共用默认值。
+- 文生视频的 `aspect_ratio` **必填且不支持 `adaptive`**；图生视频端点**根本没有 `aspect_ratio`**；参考生视频默认 `adaptive`。三个端点行为都不一样。
+- `resolution` 默认 `2K`（最贵档），控成本要显式下发 `768P`。
+- 图生视频端点关于首尾帧的描述自相矛盾，接入前必须实测。
+- 输入视频时长会**叠加进计费秒数**；输入图片前 5 张免费。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+- 官方格式核对（2026-11-08）：图生视频字段按官方 OpenAPI 用 `first_frame_url` / `last_frame_url`；此前误用 APIMart 的 `first_frame_image`，平台把请求当成文生视频并报 “aspect_ratio is required for text-to-video”（2026-11-08 实调）。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| MiniMax H3 文生视频 | https://docs.kie.ai/cn/market/minimax-h3/text-to-video | 否 |
+| MiniMax H3 图生视频 | https://docs.kie.ai/cn/market/minimax-h3/image-to-video | 否 |
+| MiniMax H3 参考生视频 | https://docs.kie.ai/cn/market/minimax-h3/reference-to-video | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `h3`，含计费公式） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |
+
+## 2026-10-12 价格复核
+
+本次按 t170 已确认表更新 calculator 与基础报价；输入视频计费公式不变。官方来源：[https://kie.ai/pricing](https://kie.ai/pricing)（公开无需登录），不使用会员专属折扣或第三方对比列。

package/docs/model-adaptation/MiniMax-H3/MiniMax-H3_/347/231/276/347/202/274.md

@@ -0,0 +1,65 @@
+# MiniMax H3 · 百炼
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | 阿里云百炼（托管，推理服务供应商为 MiniMax） |
+| 项目模型 ID | `bailian-minimax-h3`（通用标识 `minimax-h3`） |
+| 平台模型 ID | `MiniMax/MiniMax-H3` |
+| 接口形态 | 异步任务（HTTP 只支持异步） |
+| 文档 / 价格可见性 | 公开，无需登录 |
+| 开通 | 需在百炼控制台搜索 “MiniMax”，在模型卡片上单击“立即开通”并确认授权；未开通时返回未开通错误，应用提示用户去开通 |
+
+## 1. 接入协议
+
+- 提交：`POST /api/v1/services/aigc/video-generation/video-synthesis`，请求头必须带 `X-DashScope-Async: enable`；返回 `output.task_id`、`output.task_status: PENDING`
+- 查询：`GET /api/v1/tasks/{task_id}`；官方建议约 15 秒查询一次，`task_id` 24 小时内可查；状态 PENDING → RUNNING → SUCCEEDED / FAILED（另有 CANCELED、UNKNOWN）
+- 官方示例用空间专属域名 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`；项目沿用百炼统一的 `https://dashscope.aliyuncs.com`（与万相 3.0 相同，见 [百炼.md](../供应商/百炼.md) 第 1 节）。只适用北京地域
+- 结果 `output.video_url`（MP4，H.264，30 天有效）；`usage` 给出 `output_seconds`、`input_seconds`（参考视频总秒数）、`image_count`（超过 5 张的计费图片数）、`SR`、`size`
+- 生成通常 1–5 分钟
+
+## 2. 能力（按 `input.media[].type` 组合）
+
+| 场景 | media |
+|---|---|
+| 文生视频 | 不传 media |
+| 首帧 / 尾帧 / 首尾帧 | `first_frame` ≤ 1、`last_frame` ≤ 1 |
+| 多模态参考生视频 | `image_url` ≤ 9、`feature`（参考视频）≤ 3、`driving_audio`（参考音频）≤ 3 |
+
+图生视频与参考生视频互斥，不能混用。项目“文/图生视频”模式下 1 张图为首帧、2 张为首尾帧（不提供单独的“仅尾帧”）；参考音频与 MiniMax 其他渠道一致要求搭配参考图或参考视频。
+
+素材限制：
+- 图片：JPG/JPEG/PNG/WEBP/HEIC/HEIF，宽高 256–5760 px，宽高比 0.4–2.5，≤ 30MB；URL 文档写 HTTP/HTTPS
+- 视频：MP4/MOV，H.264/H.265，单段 2–15 秒、合计 ≤ 15 秒，宽高 256–5760 px，宽高比 0.4–2.5，23.976–60 fps，≤ 50MB
+- 音频：WAV/MP3，单段 2–15 秒、合计 ≤ 15 秒，≤ 15MB
+
+## 3. 请求参数
+
+| 字段 | 取值 | 项目处理 |
+|---|---|---|
+| `model` | `MiniMax/MiniMax-H3` | 固定 |
+| `input.prompt` | 必填，≤ 7000 字符 | 空提示词在提交前拒绝 |
+| `parameters.resolution` | 必填，`768P` / `2K` | 「分辨率」，默认 2K（与其他渠道一致） |
+| `parameters.ratio` | `adaptive`（默认）、`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9` | 文生视频必须具体比例（智能比例落到 16:9）；图生视频由图片决定，界面隐藏且不发送；参考生视频智能比例发 `adaptive` |
+| `parameters.duration` | 必填，4–15 整数 | 「时长」，默认 6 |
+| `parameters.watermark` | 默认 false | 固定 false |
+
+## 4. 价格（北京，刊例价）
+
+| 项 | 价格 |
+|---|---|
+| 输出 768P | ¥0.50 / 秒 |
+| 输出 2K | ¥0.80 / 秒 |
+| 输入参考视频 | 按输入时长与生成分辨率同价（768P ¥0.50 / 秒、2K ¥0.80 / 秒） |
+| 输入图片 | 5 张以内免费，超出 ¥0.20 / 张 |
+| 输入音频 | 免费 |
+
+限流：RPM 300，同时处理中任务 5。
+
+## 原始链接索引
+
+| 内容 | 链接 | 需登录 |
+|---|---|---|
+| API 文档 | https://help.aliyun.com/zh/model-studio/minimax-video-generation-api-reference | 否 |
+| 模型信息与价格 | https://help.aliyun.com/zh/model-studio/minimax-h3 | 否 |

package/docs/model-adaptation/MiniMax-H3-Max/MiniMax-H3-Max_APIMart.md

@@ -0,0 +1,78 @@
+# MiniMax H3 Max · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 项目模型 ID | `apimart-minimax-h3-max`（通用标识 `minimax-h3-max`） |
+| 平台模型 ID | `MiniMax-H3-Max`（大小写不敏感） |
+| 接口形态 | 异步任务 |
+| 文档 / 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- 提交：`POST /v1/videos/generations` → `data[0].task_id`；请求体 ≤ 64 MB
+- 查询：`GET /v1/tasks/{task_id}`，每 5–10 秒，建议超时 15 分钟
+- 组合违规（首尾帧与参考素材混用、只传参考音频等）同步返回 400，不建任务、不扣费
+
+## 2. 与 MiniMax-H3 的差异
+
+| 能力 | `MiniMax-H3` | `MiniMax-H3-Max` |
+|---|---|---|
+| 分辨率 | 2K / 768P | 480P / 768P / 1080P，默认 768P |
+| 时长 | 4–15 秒 | 5–15 秒 |
+| 首帧 / 尾帧 / 首尾帧 | 支持 | 支持 |
+| 中间帧 | 支持 | 不支持 |
+| 多模态参考 | 图、视频、音频 | 图（≤ 9）、视频（≤ 3，单段 2–15 秒，总 ≤ 15 秒）、音频（同上，需搭配图或视频） |
+| 输入图片费用 | 5 张以内免费 | 2 张以内免费 |
+| Regeneration 源任务 | 可以 | 不可以 |
+
+## 3. 请求参数
+
+| 字段 | 取值 | 说明 |
+|---|---|---|
+| `model` | `MiniMax-H3-Max` | 必填 |
+| `prompt` | ≤ 7000 字符 | 任何场景必填 |
+| `duration` | 5–15 | 默认 5，不支持 4 |
+| `resolution` | `480P` / `768P` / `1080P` | 2K / 1440P / 2048P 返回 400 |
+| `aspect_ratio`（或 `size` / `ratio`） | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16`；参考模式另有 `adaptive` | 文生不传或 adaptive 回落 16:9；图生被忽略；参考模式默认 adaptive |
+| `first_frame_image` / `last_frame_image` / `image_with_roles` | 公网 URL | 首尾帧各 ≤ 1，可单独传尾帧 |
+| `image_urls` | ≤ 9 | 一律作为参考图 |
+| `video_urls` / `video_url` | ≤ 3 段 | 提交时读取时长计费，读不到返回 400 |
+| `audio_urls` / `audio_url` | ≤ 3 段 | 不能单独使用 |
+| `watermark`（`aigc_watermark`） | 默认 false | 1080P 时必须省略；项目不请求 |
+| `webhook` | | 项目不请求 |
+
+图片：JPG/JPEG/PNG/WEBP/HEIC/HEIF，≤ 30 MB，宽高 256–5760 px，宽高比 0.4–2.5。视频：MP4/MOV，H.264/H.265，≤ 50 MB，23.976–60 fps。音频：WAV/MP3，≤ 15 MB。
+
+## 4. 价格
+
+来源：[MiniMax H3 Max 模型页](https://apimart.ai/zh/model/minimax-h3-max)（2026-11-07 读取，黄金价 = 当前价）；定价中心起步价 `MiniMax-H3-Max $0.0377/秒` 一致。
+
+| 项目 | 单价 |
+|---|---|
+| 480P / 768P / 1080P 生成 | $0.03768 / $0.05712 / $0.128 每秒 |
+| 参考图片（首尾帧与参考图合计，前 2 张免费） | $0.05712 / 张 |
+| 参考视频（按源视频时长）480P / 768P / 1080P | $0.04232 / $0.11088 / $0.11936 每秒 |
+| 参考音频 | 免费 |
+
+总费用 = 生成单价 × 时长 + 超额图片单价 × max(0, 输入图片张数 − 2) + 参考视频单价 × 参考视频总时长（API 文档计费说明）。
+
+## 5. 项目适配
+
+- 素材尺寸前置校验（2026-11-08）：`imageConstraints` 宽高 256–5760 px、宽高比 0.4–2.5；文档未写视频尺寸，不校验视频。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+- 新建独立模型而不并入 `apimart-minimax-h3`：项目对极速 / Turbo / Fast 档一贯单独建模（Kling 3.0 Turbo、Seedance 2.0 Fast），且两者分辨率、时长、帧控制、免费图片数与参考视频计价都不同，合并会让一个模型同时维护两套互斥的分辨率与计价表。
+- `role: 'mode'` 模式：文/图生视频（0 张文生，1 张首帧，2 张首尾帧）与参考生视频。
+- 比例默认“智能”：文生发 16:9，图生不发，参考模式发 `adaptive`。
+- 不显示、不请求：`watermark`、`webhook`。
+
+- 界面与请求一致（2026-11-08“所选即所发”离线检查）：首帧 / 首尾帧时不发送比例（由图片决定），非参考模式带图时隐藏比例参数。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| API 文档 | https://docs.apimart.ai/cn/api-reference/videos/minimax-h3/max | 否 |
+| 模型页（价格） | https://apimart.ai/zh/model/minimax-h3-max | 否 |
+| 定价中心（起步价） | https://apimart.ai/zh/pricing | 否 |