@henjicc/ai-sdk 0.2.8

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

@@ -0,0 +1,234 @@
+# MiniMax H3 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `MiniMax-H3`、`MiniMax-H3-Context-IR`、`MiniMax-H3-Regeneration` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> APIMart 上 MiniMax H3 是**三个模型、三份文档**：视频生成、**Context-IR 提示词增强**、**Regeneration 再生成（768P → 2K）**。后两个是上一版适配遗漏的能力。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/videos/generations` → `{ code: 200, data: [{ status: "submitted", task_id }] }`
+- **查询**：`GET /v1/tasks/{task_id}`。**建议每 5~10 秒轮询一次，客户端超时设为 15 分钟**
+- **结果**：`result.videos[0].url` 为 mp4 地址；**视频 URL 约 24 小时有效**，请及时转存。任务失败自动退款
+- **回调**：用 `webhook` 参数（**不要传官方的 `callback_url`**，该字段由平台内部使用，不接受用户传入）
+- 与 MiniMax-Hailuo-02 / MiniMax-Hailuo-2.3 共用统一提交与查询接口
+
+---
+
+## 2. 模型 A：`MiniMax-H3`（视频生成）
+
+### 2.1 生成模式（靠字段自动路由，**无需 `mode` 字段**）
+
+| 模式 | 触发条件 | 能力 |
+|---|---|---|
+| 文生视频（T2V） | 只传 `prompt` 及通用字段 | 纯文本驱动生成 |
+| 图生视频（I2V） | `first_frame_image` / `last_frame_image`（或 `image_with_roles` 的 `first_frame` / `last_frame`） | 首帧、尾帧、首尾帧控制 |
+| 多模态参考（R2V） | `image_urls` / `video_urls` / `audio_urls`，或 `image_with_roles` 的 `reference_image` | 参考图 + 参考视频 + 参考音频 |
+
+> ⚠️ **严格互斥**：图生视频字段与多模态参考字段**不能同时出现，混用返回 400**。
+> ⚠️ **不能只给音频**：传了 `audio_urls` 时必须至少再配一个参考图或参考视频。
+
+### 2.2 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | 固定 `MiniMax-H3`。**必须显式传递** |
+| `prompt` | string | **必填** | — | **任何场景都必填且不能为空**，单条 ≤ **7000** 字符 |
+| `duration` | integer | 可选 | `5` | **4 ~ 15 的整数** |
+| `resolution` | string | 可选 | **`2K`** | `2K`（默认）/ `768P` |
+| `aspect_ratio` | string | 可选 | 见「宽高比规则」 | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。**也可用 `size` 或 `ratio` 传，效果相同** |
+| `watermark` | boolean | 可选 | `false` | AIGC 水印。兼容字段名 `aigc_watermark` |
+| `webhook` | string | 可选 | — | 任务终态时主动推送 |
+| `first_frame_image` | string | 可选 | — | 首帧图 URL |
+| `last_frame_image` | string | 可选 | — | 尾帧图 URL，可与首帧组合实现首尾帧控制 |
+| `image_urls` | string[] | 可选 | — | **一律按参考图（`reference_image`）处理，不管传几张，不会按张数自动当成首帧 / 首尾帧**。≤ **9** 张 |
+| `video_urls` | string[] | 可选 | — | 参考视频，≤ **3** 个 |
+| `audio_urls` | string[] | 可选 | — | 参考音频，≤ **3** 个。**不能单独使用，必须搭配参考图或参考视频** |
+| `image_with_roles` | object[] | 可选 | — | `{ url, role }`，`role` ∈ `first_frame`（也接受 `first`）/ `last_frame`（也接受 `last`）/ `reference_image`（也接受 `reference`）。可替代上面三个字段 |
+| `nsfw_check` | boolean | 可选 | `false` | 提交前内容审核 |
+
+### 2.3 宽高比规则（**易踩坑**）
+
+| 场景 | `aspect_ratio` 行为 |
+|---|---|
+| 文生视频（只有 prompt） | **必须是具体比例；不传或传 `adaptive` 会回落到 `16:9`** |
+| 图生视频（有首 / 尾帧） | **由输入图片决定，传什么都会被忽略**（恒 `adaptive`） |
+| 多模态参考生视频 | 可选，默认 `adaptive`；也可显式指定具体比例 |
+
+### 2.4 输入媒体限制
+
+**请求体总大小 ≤ 64 MB。大文件请使用公网 URL，不要使用 Base64。**
+
+| 图片 | 限制 |
+|---|---|
+| 格式 | JPG / JPEG / PNG / WEBP / HEIC / HEIF |
+| 单文件 | ≤ 30 MB |
+| 宽高 | 256 ~ 5760 px |
+| 长宽比（宽/高） | 0.4 ~ 2.5 |
+| 数量 | 首帧 ≤ 1、尾帧 ≤ 1、参考图 ≤ 9 |
+
+| 视频（仅多模态参考场景） | 限制 |
+|---|---|
+| 格式 | MP4（`.mp4`）、MOV（`.mov`） |
+| 编码 | 视频 H.264/AVC、H.265/HEVC；音频 AAC、MP3 |
+| 单文件 | ≤ 50 MB |
+| 个数 | ≤ 3 |
+| 时长 | 单段 2 ~ 15 s；**总时长 ≤ 15 s** |
+| 宽高 / 长宽比 / 帧率 | 256 ~ 5760 px / 0.4 ~ 2.5 / 23.976 ~ 60 |
+
+| 音频（仅多模态参考场景） | 限制 |
+|---|---|
+| 格式 | WAV、MP3 |
+| 单文件 | ≤ 15 MB |
+| 个数 | ≤ 3 |
+| 时长 | 单段 2 ~ 15 s；总时长 ≤ 15 s |
+
+### 2.5 参数约束（违反返回 400，敏感内容可能 422，**均不产生计费**）
+
+| 参数 | 约束 |
+|---|---|
+| `prompt` | 任何场景必填且非空，≤ 7000 字符 |
+| `duration` | 仅接受 4 ~ 15 的整数 |
+| `resolution` | `2K`（默认）或 `768P` |
+| `aspect_ratio` | 见「宽高比规则」 |
+| 首尾帧与参考素材 | **互斥**，不能混用 |
+| `audio_urls` | 不能单独输入 |
+| 参考图 / 参考视频 / 参考音频 | ≤ 9 / ≤ 3 / ≤ 3 |
+| 参考视频探测失败 | 返回 `input_video_probe_failed`（URL 不可访问或文件损坏），**未扣费** |
+
+---
+
+## 3. 模型 B：`MiniMax-H3-Context-IR`（提示词增强）
+
+多模态上下文理解，产出增强后的**结构化提示词**（**不生成视频**）。通常 20~40 秒出结果。
+
+**结果在 `result.prompt`（不是 `result.videos`）**，把它**原样**作为 `MiniMax-H3` 的 `prompt` 即可继续生成。
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | 固定 `MiniMax-H3-Context-IR` |
+| `prompt` | string | 必填 | — | 原始想法描述，**≤ 7000 字符** |
+| `duration` | integer | 可选 | `5` | 目标视频时长 4~15，影响增强结果中的节奏描述 |
+| `aspect_ratio` | string | 条件 | — | 目标画幅。**纯文本输入时必填，且不能是 `adaptive`** |
+| `first_frame_image` / `last_frame_image` | string | 可选 | — | 首帧 / 尾帧图 URL |
+| `image_urls` | string[] | 可选 | — | 参考图，≤ 9 张 |
+| `image_with_roles` | object[] | 可选 | — | 同生成接口 |
+| `video_urls` | string[] | 可选 | — | 参考视频，≤ 3 段；单段 2~15 s，总时长 ≤ 15 s |
+| `audio_urls` | string[] | 可选 | — | 参考音频，≤ 3 段；**不能单独输入** |
+| `nsfw_check` | boolean | 可选 | `false` | — |
+
+素材字段与视频生成**校验规则一致**（首尾帧与参考互斥、不能只给音频）。
+
+**计费：按 token（H3 家族中唯一按 token 结算的模型）**——输入 **$0.87 / 百万 tokens**，输出 **$3.45 / 百万 tokens**。典型一次调用（约 5.6k 输入 + 3.4k 输出）约 **$0.0167**。
+
+---
+
+## 4. 模型 C：`MiniMax-H3-Regeneration`（768P → 2K 再生成）
+
+> ⚠️ **不是通用超分。** 源视频必须是 **MiniMax-H3 生成的 768P 成片**，外部视频（手机拍摄、其他模型生成等）会被拒绝。
+
+**推荐用法：只传 `source_task_id`**，服务端自动回填 `prompt`、素材与源视频。
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `model` | string | 必填 | 固定 `MiniMax-H3-Regeneration` |
+| `source_task_id` | string | 必填 | 上一条**成功的 MiniMax-H3 · 768P** 任务 ID。传入后**无需**再传 `prompt`、源视频与参考素材 |
+| `nsfw_check` | boolean | 可选 | — |
+
+`source_task_id` 须**同时满足**以下条件，否则**同步 400**（不建任务、不扣费）：归属当前账号；模型为 `MiniMax-H3`；状态为成功（`completed`）；分辨率为 `768P`。
+
+**源视频规格**（不符会在任务失败时返回原因并退款）：
+
+| 项目 | 要求 |
+|---|---|
+| 音轨 | **必须有**，不支持无音轨视频 |
+| 帧率 | 24 fps |
+| 宽 / 高 | 均能被 32 整除 |
+| 面积 | ≤ 768 × 1344（1,032,192 像素） |
+| 总帧数 | 107 ~ 362 帧，每档递增 17 帧（约 4 ~ 15 秒） |
+
+**计费**（按秒，结构与 H3 生成同构，单价不同）：
+
+| 项目 | 单价 |
+|---|---|
+| 输出（768P → 2K） | **$0.045 / 秒** |
+| 输入参考视频 | **$0.045 / 秒** |
+| 输入图片 | 5 张以内免费，超出 **$0.0225 / 张** |
+| 输入音频 | 免费 |
+
+> 原 768P 任务用过的素材在再生成时会**重新计费**，不只收输出秒数。
+> 算例：5 秒源视频无额外素材 = $0.225；10 秒源视频 + 2 张图 = $0.45（图 ≤ 5 免费）。
+
+### Full 2K Workflow（官方推荐的省钱路径）
+
+① `Context-IR` 增强 prompt → ② `MiniMax-H3` 用 `768P` 出预览 → ③ `Regeneration` 升 2K。
+**三步单价合计等于直出 2K，但试错成本更低。**
+
+---
+
+## 5. 价格（定价中心）
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → 视频标签页（2026-08-30 复核，1 Credit ≈ $0.1）。定价中心与模型文档对 H3 生成的按秒口径一致；Context-IR 的「按次 / 按 token」冲突仍保留如下，不能混用。
+
+**MINIMAX-H3**（7 个档位）
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 / 2K | 0.9144 Credits/秒 ≈ **$0.09144/秒** | $0.1143 | 20% |
+| 768P | 0.5712 Credits/秒 ≈ **$0.05712/秒** | $0.0714 | 20% |
+| 输入参考图（**前 5 张免费**） | 0.2288 Credits/张 ≈ **$0.02288/张** | $0.0286 | 20% |
+| 输入参考视频（规格与生成视频相同，**与生成时长叠加计费**，参考视频最多 15 秒） | 默认/2K 0.9144 Credits/秒 ≈ $0.09144/秒；768P 0.5712 ≈ $0.05712/秒 | — | 20% |
+
+**MINIMAX-H3-REGENERATION**（5 个档位）
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 / 2K | 0.3432 Credits/秒 ≈ **$0.03432/秒** | $0.0429 | 20% |
+| 输入参考图（**前 5 张免费**） | 0.1712 Credits/张 ≈ **$0.01712/张** | $0.0214 | 20% |
+| 输入参考视频（与生成时长叠加计费，最多 15 秒） | 0.3432 Credits/秒 ≈ $0.03432/秒 | $0.0429 | 20% |
+
+**MINIMAX-H3-CONTEXT-IR**
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 | 0.8 Credits/次 ≈ **$0.08/次** | $0.1 | 20% |
+
+> 定价中心的 Context-IR 是「按次」，而 API 文档写的是「按 token」（约 $0.0167/次）。两处口径不同，以定价中心与任务返回的 `cost` 为准。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 这三个模型都没有这两个字段。
+- **`aspect_ratio` 的行为按模式变化**：文生视频不传会回落 `16:9`；图生视频**传了也被忽略**。UI 上在图生视频模式下应禁用比例选择，否则用户以为选了却没生效。
+- **`image_urls` 永远是参考图**，不会因为传 1 张就变成首帧——首帧必须显式用 `first_frame_image` 或 `image_with_roles`。这是与 Seedance 完全不同的语义。
+- 首尾帧与多模态参考**严格互斥**，混用直接 400。
+- 请求体总大小 ≤ 64 MB，禁止 Base64 大文件。
+- `resolution` **默认 `2K`**（最贵的档），若产品要控成本必须显式下发 `768P`。
+- Context-IR 与 Regeneration 是两条独立能力：前者只产出文本、后者只接受本平台自家的 768P 任务 ID。要做「预览再升级」的省钱链路就必须把三者串起来。
+- 参考视频与生成时长**叠加计费**，成本估算不能只算输出秒数。
+
+### SDK 参考视频时长契约（2026-08-30）
+
+- 估价会从 `uploadedVideoFilePaths`、`videos`、`uploadedVideos` 中选择非空且数量最完整的一组参考视频；空数组不能遮蔽另外两组已有值。
+- 宿主应按参考视频顺序注入 `__videoDurationSeconds: number[]`，SDK 只在数组条目数与参考视频数一致时求和；否则次优先使用宿主注入的 `__totalVideoDurationSeconds`。
+- 为兼容旧宿主，前两项不可用时仍接受 `__firstVideoDurationSeconds`，并按「首段时长 × 视频数」估算；这只是兼容近似值，不代表多段视频的真实总时长。
+- 参考视频模式最终估价为「所有参考视频真实总时长 + 输出时长」× 当前分辨率秒价；普通首尾帧模式不计参考视频输入时长。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| MiniMax-H3 视频生成 | https://docs.apimart.ai/cn/api-reference/videos/minimax-h3/generation | 否 |
+| MiniMax-H3 Context-IR 提示词增强 | https://docs.apimart.ai/cn/api-reference/videos/minimax-h3/context-ir | 否 |
+| MiniMax-H3 Regeneration 再生成 | https://docs.apimart.ai/cn/api-reference/videos/minimax-h3/regeneration | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（视频标签页搜 MINIMAX-H3） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

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

@@ -0,0 +1,108 @@
+# 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 | **是** |

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

@@ -0,0 +1,111 @@
+# 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 | **是** |

package/docs/model-adaptation/MiniMax-Speech/MiniMax-Speech_/346/264/276/346/254/247/344/272/221.md

@@ -0,0 +1,170 @@
+# MiniMax Speech · 派欧云 PPIO
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 音频（语音合成 + 声音克隆） |
+| 供应商 | 派欧云 PPIO |
+| 平台路由 | `/v3/[async/]minimax-speech-2.8-{hd,turbo}`、`/v3/minimax-voice-cloning` |
+| 接口形态 | 同步与异步双版本；声音克隆为同步 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+供应商公共协议见 [供应商/派欧云.md](../供应商/派欧云.md)。
+
+## 1. 能力与价格
+
+| 接口 | 路由 | 价格 |
+|---|---|---|
+| Speech 2.8 HD 同步 | `POST /v3/minimax-speech-2.8-hd` | ¥3.5 / 万字符 |
+| Speech 2.8 HD 异步 | `POST /v3/async/minimax-speech-2.8-hd` | ¥3.5 / 万字符 |
+| Speech 2.8 Turbo 同步 | `POST /v3/minimax-speech-2.8-turbo` | ¥2.0 / 万字符 |
+| Speech 2.8 Turbo 异步 | `POST /v3/async/minimax-speech-2.8-turbo` | ¥2.0 / 万字符 |
+| 声音克隆 | `POST /v3/minimax-voice-cloning` | **¥9.9 / 音色**（试听另计） |
+
+定价页还列着 `MiniMax speech-2.6-hd` ¥3.5/万字符 与 `speech-2.6-turbo` ¥2/万字符，说明 **2.6 仍在售**，但文档站已不再提供 2.6 的 API 参考页，**路由无法确认**（PPIO 对所有未知路径统一返回 400，无法靠探测区分）。
+
+计费字符数以响应里的 `extra_info.usage_characters` 为准。PPIO 公开商品注册表给出的结算表达式为 `(单价 × 字符数 + 999999) / 1000000`，即每次请求按实际字符费**向上取整到人民币分**；不能只做“最低 ¥0.01”而保留分以下的小数。
+
+## 2. 声音克隆 `/v3/minimax-voice-cloning`
+
+### `model` 字段枚举（已核实）
+
+```
+speech-2.6-hd | speech-2.6-turbo | speech-2.8-hd | speech-2.8-turbo
+```
+
+> ⚠️ **该文档页底部的 curl 示例里写的是 `"model": "speech-01-hd"`，那是 PPIO 没同步更新的过期示例，不要照抄。** 以正文参数表的枚举为准。曾有一次排查因为参照了含旧示例的过期资料，误判项目代码写错——项目当前的 4 个枚举值是正确的。
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `audio_url` | string | ✅ | — | mp3/m4a/wav；时长 10 秒 ~ 5 分钟；≤20MB |
+| `clone_prompt` | object | | — | `{ prompt_audio_url 必填（示例音频 <8s）, prompt_text 必填（对应文本，句末需有标点）}`，提升音色相似度与稳定性 |
+| `text` | string | | — | 复刻试听文本，≤2000 字符 |
+| `model` | string | 传 `text` 时必填 | — | 上述 4 个枚举值 |
+| `accuracy` | float | | `0.7` | 文本校验准确率阈值 `[0, 1]` |
+| `need_noise_reduction` | boolean | | `false` | 降噪 |
+| `need_volume_normalization` | boolean | | `false` | 音量归一化 |
+
+响应：`{ demo_audio_url, voice_id }`
+
+### 两个业务硬约束
+
+1. ⚠️ **仅个人认证 / 企业认证用户可调用**（需实名认证）
+2. ⚠️ **复刻出的是临时音色，必须在 168 小时（7 天）内在任意 T2A 合成接口中实际使用一次（试听不算），否则音色被删除**
+
+### 计费
+
+¥9.9 / 音色。**试听单独计费**——文档明确写「试听将根据字符数正常收取语音合成费用，定价与 T2A 各接口一致」，即传了 `text` 会额外按 HD ¥3.5/万字符或 Turbo ¥2/万字符扣费。试听字符费也按单次请求向上取整到分，再与 ¥9.9 音色费相加；例如 Turbo 60 字符原始金额 ¥0.012，实际计为 ¥0.02，总计 ¥9.92。
+
+## 3. 语音合成（同步）
+
+**模型版本在路由里，请求体没有 `model` 字段。**
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `text` | string | ✅ | — | < 10000 字符（>3000 建议流式）；支持换行分段、`<#x#>` 停顿标记、语气词标签 |
+| `stream` | boolean | | `false` | |
+| `output_format` | string | | **`hex`** | `url` / `hex`；仅非流式生效，流式只能 hex；返回的 url 有效期 24 小时 |
+| `voice_setting` | object | | — | 见下 |
+| `audio_setting` | object | | — | 见下 |
+| `voice_modify` | object | | — | `pitch` / `timbre` / `intensity` 各 `[-100, 100]`；`sound_effects` 枚举 `spacious_echo` / `auditorium_echo` / `lofi_telephone` / `robotic`（单次仅一种） |
+| `timber_weights` | object[] | | — | 混合音色 `{ weight 必填 integer, voice_id 必填 string }` |
+| `subtitle_enable` | boolean | | `false` | |
+| `aigc_watermark` | boolean | | `false` | |
+| `language_boost` | string | | `null` | 41 个枚举值（`Chinese`、`Chinese,Yue`、`English`、`Japanese`、…、`auto`） |
+| `pronunciation_dict` | object | | — | `tone` string[]，如 `["燕少飞/(yan4)(shao3)(fei1)", "omg/oh my god"]` |
+| `stream_options` | object | | — | `exclude_aggregated_audio` boolean 默认 false |
+
+### `voice_setting`
+
+| 字段 | 默认 | 约束 |
+|---|---|---|
+| `voice_id` | — | **必填**；系统音色 / 复刻音色 / 文生音色；用混合音色时置空并改用 `timber_weights` |
+| `vol` | `1` | `(0, 10]` |
+| `pitch` | `0` | `[-12, 12]` |
+| `speed` | `1` | `[0.5, 2]` |
+| `emotion` | — | `happy` / `sad` / `angry` / `fearful` / `disgusted` / `surprised` / `calm` / `fluent` / `whisper` |
+| `latex_read` | `false` | |
+| `text_normalization` | `false` | |
+
+> ⚠️ **`emotion` 仅对 `speech-2.6-hd/turbo` 与 `speech-01-hd/turbo` 生效，2.8 系列不支持情绪控制**；其中 `fluent` / `whisper` 仅 2.6 系列生效。项目当前只接了 2.8 路由，因此**情绪参数在当前配置下是无效的**，参数面板不应展示。
+
+### `audio_setting`
+
+| 字段 | 默认 | 约束 |
+|---|---|---|
+| `format` | `mp3` | `mp3` / `pcm` / `flac` / `wav`（wav 仅非流式） |
+| `bitrate` | `128000` | `32000` / `64000` / `128000` / `256000`（仅 mp3 生效） |
+| `channel` | `1` | `1` / `2` |
+| `sample_rate` | `32000` | `8000` / `16000` / `22050` / `24000` / `32000` / `44100` |
+| `force_cbr` | `false` | 仅流式 + mp3 生效 |
+
+### 语气词标签（仅 2.8 系列支持）
+
+```
+(laughs) (chuckle) (coughs) (clear-throat) (groans) (breath) (pant)
+(inhale) (exhale) (gasps) (sniffs) (sighs) (snorts) (burps)
+(lip-smacking) (humming) (hissing) (emm) (whistles) (sneezes)
+(crying) (applause)
+```
+
+### 响应
+
+```json
+{
+  "data": { "audio": "...", "status": 2, "subtitle_file": "..." },
+  "trace_id": "...",
+  "base_resp": { "status_code": 0, "status_msg": "success" },
+  "extra_info": {
+    "usage_characters": 100,
+    "audio_length": 1000, "audio_size": 12345, "bitrate": 128000,
+    "word_count": 50, "audio_format": "mp3", "audio_channel": 1,
+    "audio_sample_rate": 32000, "invisible_character_ratio": 0
+  }
+}
+```
+
+`extra_info.usage_characters` 是**计费字符数**。
+
+## 4. 语音合成（异步）—— 与同步有多处差异
+
+本项目走的是异步路由，以下差异必须注意：
+
+| 差异点 | 同步 | 异步 |
+|---|---|---|
+| `stream` / `output_format` / `timber_weights` / `subtitle_enable` / `stream_options` | 有 | **没有** |
+| `text` 上限 | < 10000 字符 | **5 万字符** |
+| `text_file_id` | 无 | **有**，与 `text` 二选一必填；txt <100000 字符 或 zip；zip 内 json 支持 `title`/`content`/`extra` 三字段，三者齐全则产出 3 组共 9 个文件 |
+| `voice_setting` | 可选 | **整个 object 必填** |
+| `voice_setting` 内字段 | `latex_read` / `text_normalization` | **`english_normalization`**（默认 false） |
+| 采样率字段名 | `sample_rate` | **`audio_sample_rate`** |
+| `format` 枚举 | mp3/pcm/flac/wav | mp3/pcm/flac/wav/**pcmu_raw**/**pcmu_wav**/**opus** |
+
+- `pcmu_*` 为 G.711 μ-law 8kHz
+- `opus` 仅支持采样率 8000/12000/16000/24000/48000，其他值会报错
+- ⚠️ `audio_setting.channel` 文档正文写「可选范围 [1,2]，默认值为 1」但 default 标注为 `2`，**文档自相矛盾，建议显式传值**
+
+响应：`{ task_id, details: { usage_characters } }`，再走 `/v3/async/task-result` 取 `audios[].audio_url`。
+
+## 5. 适配要点
+
+- **`emotion` 在 2.8 上不生效**，当前项目只接 2.8 路由，该参数应隐藏或在切到 2.6 时才显示。
+- 同步与异步的字段名不同（`sample_rate` vs `audio_sample_rate`、`text_normalization` vs `english_normalization`），不能共用同一个 builder 分支。
+- 声音克隆的 168 小时失效规则需要在产品侧提示用户，否则会出现「克隆成功但过几天音色不见了」。
+- 声音克隆试听会额外产生 TTS 费用，计价展示应体现 ¥9.9 音色费 + 试听字符费两部分。
+- `audio_url` 字段以 `_url` 结尾 → 走 `public-url` 模式，**声音克隆依赖 KIE API Key**。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 声音克隆 | https://ppio.com/docs/models/reference-minimax-voice-cloning | 否 |
+| Speech 2.8 HD 同步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-hd | 否 |
+| Speech 2.8 HD 异步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async | 否 |
+| Speech 2.8 Turbo 同步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-turbo | 否 |
+| Speech 2.8 Turbo 异步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-turbo-async | 否 |
+| 定价页（音频 tab） | https://ppio.com/pricing | 否 |
+| 模型注册表（含计费表达式） | https://api-server.ppio.com/v1/product/multimodal-model/list?returnSchema=true | 否 |