@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/Kling-3.0/Kling-3.0_KIE.md

@@ -0,0 +1,106 @@
+# Kling 3.0 · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `kling-3.0/video` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "kling-3.0/video", callBackUrl?, input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: ["https://....mp4"] }`
+
+## 2. 能力清单
+
+单端点承载：文生视频、图生视频（首帧 / 首尾帧）、有声视频、多镜头分镜、引用元素（含**视频角色主体**与**角色音频**）。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 必填 | — | 视频生成提示词。**当 `multi_shots=false` 时生效** |
+| `input.image_urls` | array | 可选 | — | 首尾帧图片链接。`multi_shots=false` 时：长度 2 → 索引 0 首帧、索引 1 尾帧；长度 1 → 作为首帧。**`multi_shots=true` 时只支持首帧** |
+| `input.sound` | boolean | **必填** | `false` | 是否开启音效。**`multi_shots=true` 时字段值默认为 `true`** |
+| `input.duration` | string | **必填** | `"5"` | **字符串枚举** `"3"` ~ `"15"` |
+| `input.aspect_ratio` | string | **必填** | `16:9` | `16:9`、`9:16`、`1:1` |
+| `input.mode` | string | **必填** | **`pro`** | `std` / `pro` / `4K`（**注意 4K 是大写**）。分辨率映射见下 |
+| `input.multi_shots` | boolean | **必填** | `false` | 是否多镜头 |
+| `input.multi_prompt` | array | **必填** | — | 镜头提示词。`multi_shots=true` 时生效。**最多 5 段**（APIMart 是 6 段），每段时长 1–12 秒 |
+| `input.kling_elements` | array | **必填** | — | 引用元素，**最多 3 个** |
+
+> ⚠️ KIE 把 `sound` / `duration` / `aspect_ratio` / `mode` / `multi_shots` / `multi_prompt` / `kling_elements` 都标成了 **required**，但显然 `multi_prompt` / `kling_elements` 在单镜头无元素时不应必填。接入前需实测最小请求体。
+
+### `mode` 的分辨率映射（文档明列）
+
+| mode | 16:9 | 9:16 | 1:1 |
+|---|---|---|---|
+| `std` | 1280×720 | 720×1280 | 720×720 |
+| `pro` | 1920×1080 | 1080×1920 | 1080×1080 |
+| `4K` | 3840×2160 | 2160×3840 | 2160×2160 |
+
+### `multi_prompt` 元素
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `prompt` | string | 必填 | 该镜头提示词，**单个镜头最多 500 字符，每个 `@element` 占 37 个字符** |
+| `duration` | integer | 必填 | 该镜头时长，**1–12 秒** |
+
+> 「如果需要使用 element，则需加在 prompt 后。」
+
+### `kling_elements` 元素
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `name` | string | 必填 | 元素名称，prompt 中用 `@` 前缀引用（如 `@element_dog`） |
+| `description` | string | 必填 | 元素描述 |
+| `element_input_urls` | array | 必填 | 元素图片链接，**需要 2–4 个 URL**。JPG / PNG，**每张 ≤ 10 MB** |
+| `element_input_audio_urls` | array | 可选 | **角色音频素材 URL 列表，音频时长必须为 5–30 秒**（APIMart 侧没有这个字段） |
+| `start_time` | integer | 可选 | 视频角色素材截取开始时间（毫秒），默认 `0`。**仅 `element_input_urls` 上传视频时生效** |
+| `end_time` | integer | 可选 | 截取结束时间（毫秒），默认 `8000`。必须大于 `start_time`，且 `end_time - start_time` 须在 **3000–8000 ms** |
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://....mp4"] }`。
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `kling 3`；1 Credit = $0.005）。
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| 720P 无声 | 14 /秒 | **$0.07/秒** | $0.084 | 16.7% |
+| 720P 有声 | 20 /秒 | **$0.1/秒** | $0.126 | 20.6% |
+| 1080P 无声 | 18 /秒 | **$0.09/秒** | $0.112 | 19.6% |
+| 1080P 有声 | 27 /秒 | **$0.135/秒** | $0.168 | 19.6% |
+| 4K 无声 | 67 /秒 | **$0.335/秒** | $0.42 | 20.2% |
+| 4K 有声 | 67 /秒 | **$0.335/秒** | $0.42 | 20.2% |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
+- **`duration` 是字符串**（`"5"`），而 APIMart 是整数——跨供应商序列化必须区分。
+- **`mode` 默认是 `pro`**（APIMart 默认 `std`），不显式下发会直接落到更贵的档位。
+- `4K` 是**大写**，APIMart 是小写 `4k`。
+- `multi_prompt` 上限 **5 段**（APIMart 6 段），单镜头 prompt ≤ 500 字符且 `@element` 按 37 字符计。
+- `multi_shots=true` 时 `sound` 默认变成 `true`，会静默产生有声视频与更高费用。
+- KIE 侧的引用元素支持**视频角色主体**（`start_time` / `end_time` 截取 3–8 秒）与**角色音频**，比 APIMart 更全。
+- 多个字段被标为 required 但语义上不合理，接入前实测最小请求体。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Kling 3.0 | https://docs.kie.ai/cn/market/kling/kling-3-0 | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `kling 3`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |

package/docs/model-adaptation/Kling-3.0/Kling-3.0_/346/264/276/346/254/247/344/272/221.md

@@ -0,0 +1,119 @@
+# Kling 3.0 · 派欧云 PPIO
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 视频 |
+| 供应商 | 派欧云 PPIO（聚合平台） |
+| 平台路由 | `/v3/async/kling-v3.0-{std,pro,4k}-{t2v,i2v}` + `/v3/async/kling-v3.0-motion-control` |
+| 接口形态 | **异步任务**：提交返回 `task_id`，轮询统一任务接口 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+供应商公共协议（Base URL、鉴权、轮询、结果解析、上传限制）见 [供应商/派欧云.md](../供应商/派欧云.md)。
+
+## 1. 能力与路由（共 7 条）
+
+| 变体 | 路由 | 静音单价 | 有音频单价 |
+|---|---|---|---|
+| Standard 文生视频 | `/v3/async/kling-v3.0-std-t2v` | ¥0.60/秒 | ¥0.90/秒 |
+| Standard 图生视频 | `/v3/async/kling-v3.0-std-i2v` | ¥0.60/秒 | ¥0.90/秒 |
+| Pro 文生视频 | `/v3/async/kling-v3.0-pro-t2v` | ¥0.80/秒 | ¥1.20/秒 |
+| Pro 图生视频 | `/v3/async/kling-v3.0-pro-i2v` | ¥0.80/秒 | ¥1.20/秒 |
+| 4K 文生视频 | `/v3/async/kling-v3.0-4k-t2v` | ¥3.00/秒 | ¥4.50/秒 |
+| 4K 图生视频 | `/v3/async/kling-v3.0-4k-i2v` | ¥3.00/秒 | ¥4.50/秒 |
+| 动作控制 | `/v3/async/kling-v3.0-motion-control` | Standard ¥0.90/秒 | Professional ¥1.20/秒 |
+
+### 项目适配状态：7 条路由全部覆盖
+
+`packages/ai-sdk/src/catalog/ppio/kling-3.0.model.ts` 的 `endpoints.selector` 用模板拼路由——按分辨率档位映射 `std`/`pro`/`4k`，按是否上传图片映射 `t2v`/`i2v`，动作控制单独返回固定路由。源码里只有两条字面量路由字符串，容易被 grep 误判为"只接了 2 条"，实际七条都能命中。
+
+`packages/ai-sdk/tests/catalog/ppio.test.ts` 直接执行 catalog 的真实 selector，逐条断言 7 种组合的落点。
+
+## 2. 计价（重要）
+
+**按秒计费，且 `sound` 字段直接决定单价档位**——SKU 计价表达式为 `has(body.sound) && body.sound == true`。开启音频比静音**贵 50%**，不是加价项而是换档。
+
+> 代码此前把 4K 写成 ¥2.94/¥4.41、动作控制写成 ¥0.9135/¥1.218，与定价页的 ¥3.0/¥4.5 与 ¥0.9/¥1.2 不符，已修正。Standard 与 Pro 两档原本就是对的。
+>
+> 动作控制在 `character_orientation=video` 时输出时长跟随参考视频（最长 30 秒）。宿主在提交前读取视频元数据，通过运行时计价字段 `__videoDurationSeconds`（优先）、`__totalVideoDurationSeconds`（次选）传入真实时长；SDK 仍兼容旧字段 `__firstVideoDurationSeconds`。这些字段只参与估价，不进入 PPIO 请求体。若视频元数据确实不可读，才退回当前 `duration` 的兜底估计。
+
+计价函数必须同时读取「档位（std/pro/4k）」和「`sound`」两个维度，缺一个就会算错。
+
+动作控制的档位由 `model_name` 字段决定（`kling-v3-0-std` / `kling-v3-0-pro`），与 t2v/i2v 的路由分档方式不同。
+
+## 3. 请求参数
+
+### 文生视频（std / pro / 4k 基本一致）
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `prompt` | string | ✅ | — | 0–2500 字符；Pro/4K 与 `multi_prompt` 互斥 |
+| `duration` | integer | | `5` | std 为枚举 `3..15`；pro/4k 为范围 `[3,15]` |
+| `cfg_scale` | number | | `0.5` | `[0, 1]` |
+| `aspect_ratio` | string | | `16:9` | `16:9` / `9:16` / `1:1` |
+| `sound` | boolean | | `false` | **影响单价档位** |
+| `negative_prompt` | string | | — | ≤ 2500 |
+| `multi_prompt` | string[] | | — | 仅 Pro t2v；多镜头，与 `prompt` 互斥 |
+
+### 图生视频（std / pro / 4k）
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `image` | string | ✅ | — | jpg/jpeg/png，≤10MB，宽高均 ≥300px，宽高比 1:2.5 ~ 2.5:1 |
+| `prompt` | string | ✅ | — | ≤ 2500 |
+| `duration` | integer | | `5` | 同 t2v |
+| `cfg_scale` | number | | `0.5` | `[0, 1]` |
+| `sound` | boolean | | `false` | **影响单价档位** |
+| `negative_prompt` | string | | — | ≤ 2500 |
+| `end_image` | string | | — | 尾帧，约束同 `image`，**与 `multi_prompt` 互斥** |
+| `multi_prompt` | — | | — | **类型按档位不同，见下** |
+
+**i2v 没有 `aspect_ratio` 字段**（比例由输入图决定）。
+
+#### `multi_prompt` 在 i2v 各档位类型不一致
+
+| 档位 | 类型 |
+|---|---|
+| std-i2v、4k-i2v | **object[]**：`{ prompt: string 必填, duration: integer 默认 5, 范围 [3,15] }` |
+| pro-i2v | **string[]** |
+
+同一个字段名在同一模型的不同档位下结构不同，builder 必须按档位分支处理。
+
+### 动作控制
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `image` | string | ✅ | — | ≤10MB，宽高 ≥300px |
+| `video` | string | ✅ | — | mp4/mov，≤10MB，3–30 秒 |
+| `model_name` | string | ✅ | `kling-v3-0-std` | `kling-v3-0-std` / `kling-v3-0-pro`，**决定单价** |
+| `character_orientation` | string | ✅ | — | `image`（输出固定 5 秒）/ `video`（时长同参考视频，最长 30 秒） |
+| `prompt` | string | | — | ≤ 2500 |
+| `negative_prompt` | string | | — | ≤ 2500 |
+| `keep_original_sound` | boolean | | `true` | |
+
+## 4. 上传要求
+
+动作控制的 `video` 字段是视频素材 → 按 [供应商/派欧云.md](../供应商/派欧云.md) 第 2 节的规则走 **`public-url` 模式**，需要公网 URL，本项目借用 KIE 上传服务。**用户未配置 KIE API Key 时该功能不可用。**
+
+i2v 的 `image` 与 `end_image` 字段名不以 `_url` 结尾，按默认 `data-uri` 模式内联，不依赖 KIE。但 `ppio-media.ts` 里对 `/async/kling-v3.0-4k-i2v` 和 `/async/kling-v3.0-motion-control` 的 `image` 字段有 `public-url` 白名单覆盖——接入 4K i2v 时需要注意这个例外。
+
+## 5. 适配要点
+
+- 三个档位（std/pro/4k）+ 两种输入（t2v/i2v）建议按项目规范合并为**一个产品入口**，用顶层参数切换档位，由是否上传图片自动路由 t2v/i2v；动作控制因为输入素材、参数集合和输出约束都明显不同，可以保留为独立 mode。
+- `sound` 必须暴露给用户并接入计价，不能当成隐藏默认值——它是 50% 的价格差。
+- `duration` 在 std 是枚举、在 pro/4k 是范围，UI 上统一成同一个控件时要注意合法值集合按档位变化。
+- 项目默认隐藏 `seed` 与负面提示词：本模型有 `negative_prompt`，按约定**不显示、不请求**。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Standard 文生视频 | https://ppio.com/docs/models/reference-kling-v3.0-std-t2v | 否 |
+| Standard 图生视频 | https://ppio.com/docs/models/reference-kling-v3.0-std-i2v | 否 |
+| Pro 文生视频 | https://ppio.com/docs/models/reference-kling-v3.0-pro-t2v | 否 |
+| Pro 图生视频 | https://ppio.com/docs/models/reference-kling-v3.0-pro-i2v | 否 |
+| 4K 文生视频 | https://ppio.com/docs/models/reference-kling-v3.0-4k-t2v | 否 |
+| 4K 图生视频 | https://ppio.com/docs/models/reference-kling-v3.0-4k-i2v | 否 |
+| 动作控制 | https://ppio.com/docs/models/reference-kling-v3.0-motion-control | 否 |
+| 定价页（视频 tab 搜 Kling 3.0） | https://ppio.com/pricing | 否 |

package/docs/model-adaptation/Kling-3.0-Omni/Kling-3.0-Omni_APIMart.md

@@ -0,0 +1,125 @@
+# Kling 3.0 Omni · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `kling-v3-omni` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 上游官方模型标识 | `kling-v3-omni`（与可灵官方能力地图一致：全能多模态输入、有声角色驱动、直出音画和分镜） |
+
+## 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}`
+
+## 2. 能力清单
+
+统一文生 / 图生接口 + **图片引用语法**、**参考视频（视频编辑 / 特征参考）**、有声视频、多镜头分镜、引用元素（主体一致性）。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | `kling-v3-omni` |
+| `prompt` | string | 必填 | — | 支持 **`<<<image_N>>>`** 语法引用 `image_urls` 中的图片（N 从 1 开始）。例：`"让<<<image_1>>>中的人物向镜头挥手"` |
+| `negative_prompt` | string | 可选 | — | 负面提示词，**最大 2500 字符**。**本项目规则：绝对不显示**，不下发 |
+| `mode` | string | 可选 | `std` | `std`（720P）/ `pro`（1080P）/ `4k`（4K 超清） |
+| `duration` | integer | 可选 | `5` | **3–15 秒**。必须是纯数字 |
+| `aspect_ratio` | string | 可选 | `16:9` | `16:9`、`9:16`、`1:1` |
+| `image_urls` | array | 可选 | — | 图片 URL 数组，用于 `<<<image_N>>>` 引用。URL 必须公开可访问、不能有防盗链。图生视频时 `aspect_ratio` 可能被图片实际比例覆盖 |
+| `image_with_roles` | array | 可选 | — | `{ url, role }`，`role` ∈ `first_frame` / `last_frame` / **`reference`**。**与 `image_urls` 二选一** |
+| `video_list` | array | 可选 | — | 参考视频列表，**最多 1 段**，见下 |
+| `multi_shot` | boolean | 可选 | `false` | 是否启用多镜头分镜 |
+| `shot_type` | string | 条件 | — | `customize` / `intelligence`。**`multi_shot=true` 时必填** |
+| `multi_prompt` | array | 条件 | — | `{ index, prompt, duration }`。**`multi_shot=true` 且 `shot_type=customize` 时必填** |
+| `element_list` | array | 可选 | — | 引用元素，**最多 3 个主体** |
+| `watermark` | boolean | 可选 | — | 是否添加水印 |
+| `audio` | boolean | 可选 | **`false`** | 是否生成有声视频。**与 `video_list` 互斥**——`video_list` 有值时该参数会被忽略 |
+| `nsfw_check` | boolean | 可选 | `false` | 提交前内容审核 |
+
+### `image_urls` 的图片引用语法（Omni 独有）
+
+| 语法 | 说明 |
+|---|---|
+| `<<<image_1>>>` | 引用 `image_urls` 数组中的第 1 张图片 |
+| `<<<image_2>>>` | 引用第 2 张图片 |
+
+**自动引用**：若已传入 `image_urls` 但提示词中没有任何 `<<<image_N>>>`，**系统会自动在提示词前添加 `<<<image_1>>>`**。
+
+### `video_list`
+
+| 字段 | 取值 | 说明 |
+|---|---|---|
+| `video_url` | URL | **不能为空**，且需可访问 |
+| `refer_type` | `base`（默认）/ `feature` | `base` = 待编辑视频；`feature` = 特征参考视频 |
+| `keep_original_sound` | `no`（默认）/ `yes` | 是否保留原声 |
+
+约束：
+- `refer_type=base` 时：**不能定义视频首尾帧**；参考视频需 **3–10 秒**；**生成视频时长以上传视频为准**
+- `refer_type=feature` 且 `video_url` 非空时：`image_urls` **只可上传首帧图片**
+- 视频要求：仅支持 **MP4 / MOV**；时长不少于 3 秒；分辨率 **720px–2160px**；帧率 **24–60 fps（输出为 24 fps）**；大小 **≤ 200 MB**
+
+### `multi_prompt` 约束
+
+最少 1 个、最多 **6 个**分镜；每个分镜 `duration` 为整数且 ≥ 1；**所有分镜 `duration` 之和必须等于顶层 `duration`**；`index` 从 1 连续递增。
+
+### `element_list`
+
+现场创建主体时 `name`、`description`、`element_input_urls` 必填；`element_input_urls` 每个主体**至少 2 张、最多 4 张**（第 1 张正面图 + 其余参考图）；prompt 中用 **`@name`** 引用。
+
+### 参数互斥与边界（汇总）
+
+- `image_urls` 与 `image_with_roles` **二选一**
+- `mode=4k` 在 `kling-v3-omni` 可用
+- **仅尾帧输入（只有 `last_frame`）会报错，必须配首帧**
+- **首/尾帧与视频编辑互斥**：`video_list.refer_type=base`（或缺省）时不允许首尾帧
+- 有 `video_list` 时 `audio` 被忽略
+- `video_list` 最多 1 段
+- `multi_prompt` 最多 6 个分镜，`index` 从 1 连续递增
+
+## 4. 响应结构
+
+提交返回 `{ code, data: [{ status: "submitted", task_id }] }`；轮询 `GET /v1/tasks/{task_id}`，成功后读 `result.videos[]`。
+
+## 5. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → 视频标签页 `KLING-V3-OMNI`（2026-08-22，**8 个档位**，1 Credit ≈ $0.1）。
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认（std 无声） | 0.672 Credits/秒 ≈ **$0.0672/秒** | $0.084 | 20% |
+| `sound`（std 有声） | 0.896 Credits/秒 ≈ **$0.0896/秒** | $0.112 | 20% |
+| `video`（std + 参考视频） | 1.008 Credits/秒 ≈ **$0.1008/秒** | $0.126 | 20% |
+| `pro`（1080P 无声） | 0.896 Credits/秒 ≈ **$0.0896/秒** | $0.112 | 20% |
+| `pro-sound` | 1.12 Credits/秒 ≈ **$0.112/秒** | $0.14 | 20% |
+| `pro-video`（1080P + 参考视频） | 1.344 Credits/秒 ≈ **$0.1344/秒** | $0.168 | 20% |
+| `4k`（无声） | 4.2856 Credits/秒 ≈ **$0.42856/秒** | $0.5357 | 20% |
+| `4k-sound` | 4.2856 Credits/秒 ≈ **$0.42856/秒** | $0.5357 | 20% |
+
+> Omni 比 `kling-v3` 多了 `video` / `pro-video` 两个「带参考视频」的档位。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口**有 `negative_prompt`**，必须主动不注册、不下发。
+- **`<<<image_N>>>` 图片引用语法是 Omni 独有**：不写引用时系统会**静默**在 prompt 前加 `<<<image_1>>>`，产品若不想要这种行为必须显式管理引用。
+- `audio` 默认 `false`；**有 `video_list` 时 `audio` 被忽略**（不是报错，是静默忽略）。
+- **`refer_type=base` 时生成时长由上传视频决定**，用户设置的 `duration` 不生效——UI 要禁用时长选择。
+- 首尾帧与视频编辑互斥，且只传尾帧会报错。
+- 参考视频只允许 1 段、3–10 秒（`base` 模式）。
+- 多镜头分镜与引用元素是两套独立子能力，与 `kling-v3` 一致。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Kling v3 Omni 视频生成 | https://docs.apimart.ai/cn/api-reference/videos/kling-v3-omni/generation | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（视频标签页搜 KLING-V3-OMNI） | https://apimart.ai/zh/pricing | 否 |
+| 可灵官方视频能力地图（仅参考） | https://www.klingai.com/document-api/guides/capability-map/video | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

package/docs/model-adaptation/Kling-3.0-Omni/Kling-3.0-Omni_Fal.md

@@ -0,0 +1,107 @@
+# Kling 3.0 Omni · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `fal-ai/kling-video/o3/{pro,standard}/{text-to-video,image-to-video,reference-to-video}` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> ⚠️ **命名对应关系需注意**：Fal 把这一代叫 **「Kling O3」**，而可灵官方与 APIMart / KIE 叫 **Kling 3.0 Omni**（官方标识 `kling-v3-omni`）。SDK catalog 的 `fal/kling-3.0-omni.model.ts` 已按 `fal-ai/kling-video/o3/*` 映射到 Kling 3.0 Omni。Fal 文档并未明写这层对应关系，**若后续行为不符需重新核对**。
+
+## 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. 能力清单
+
+| 档位 | 文生视频 | 图生视频 | 参考生视频 |
+|---|---|---|---|
+| Pro | `fal-ai/kling-video/o3/pro/text-to-video` | `fal-ai/kling-video/o3/pro/image-to-video` | `fal-ai/kling-video/o3/pro/reference-to-video` |
+| Standard | `fal-ai/kling-video/o3/standard/text-to-video` | `fal-ai/kling-video/o3/standard/image-to-video` | `fal-ai/kling-video/o3/standard/reference-to-video` |
+
+## 3. 请求参数
+
+### 3.1 三类端点共有
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 可选 | — | **`prompt` 与 `multi_prompt` 必须二选一，不能同时给** |
+| `multi_prompt` | array | 可选 | — | 多镜头分镜列表 |
+| `duration` | string | 可选 | `"5"` | **字符串枚举** `"3"` ~ `"15"` |
+| `generate_audio` | boolean | 可选 | **`false`** | 原生音频（**注意与非 Omni 的 `kling-video/v3` 默认 `true` 相反**） |
+| `shot_type` | string | 可选 | `customize` | `customize` / `intelligent` |
+
+### 3.2 仅 `text-to-video` 与 `reference-to-video`
+
+| 字段 | 默认 | 取值与说明 |
+|---|---|---|
+| `aspect_ratio` | `16:9` | `16:9`、`9:16`、`1:1`；图生视频端点不接受该字段，输出比例跟随输入图 |
+
+### 3.3 仅 `image-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_url` | string | **必填** | 首帧图 URL |
+| `end_image_url` | string | 可选 | 尾帧图 URL |
+
+模型定位：给定首帧与尾帧，按文本描述的风格与场景生成两帧之间的过渡动画。
+
+### 3.4 仅 `reference-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `start_image_url` | string | 可选 | 作为视频首帧的图片 |
+| `end_image_url` | string | 可选 | 作为视频尾帧的图片 |
+| `image_urls` | string[] | 可选 | 风格 / 外观参考图，prompt 中用 **`@Image1`、`@Image2`** 引用。**使用视频时，elements + 参考图合计最多 4 个** |
+| `elements` | array | 可选 | 要包含的元素（角色 / 物体），prompt 中用 **`@Element1`、`@Element2`** 引用 |
+
+## 4. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" } }
+```
+
+## 5. 价格
+
+来源：各端点 `llms.txt`（2026-08-30 重新读取）。三类端点（文生 / 图生 / 参考生）在同一档位下同价。
+
+| 档位 | 关音频 | 开音频 |
+|---|---|---|
+| Pro | **$0.112 / 秒** | **$0.14 / 秒** |
+| Standard | **$0.084 / 秒** | **$0.112 / 秒** |
+
+例：Pro 5 秒开音频 = $0.70；Standard 5 秒开音频 = $0.56。
+
+**本次计价确认**：Kling O3 开音频后的正确秒价是 Pro `$0.14`、Standard `$0.112`。非 Omni Kling 3.0 的 Pro `$0.168`、Standard `$0.126` 属于另一组端点，不能复用到 O3。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 的 o3 端点这两个字段都没有。
+- **`generate_audio` 默认 `false`**，与同平台的 `kling-video/v3`（默认 `true`）相反，两个模型不能共用默认值。
+- `duration` 是**字符串枚举**。
+- 档位与输入形态都通过 **endpoint 路径**选择，共 6 个端点，适配层要做路由。
+- 比例参数只在文生视频与参考生视频显示；图生视频隐藏且不发送。
+- 路由与请求必须共用同一套图片来源解析，兼容生成提交的 `uploadedFilePaths`、画布的 `images` 与对话面板的 `uploadedImages`，并忽略空值。
+- **Fal 上没有 4K 档**（APIMart / KIE 有），也没有 `video_list` 视频编辑 / transformation 能力。
+- 素材引用写法是 `@Image1` / `@Element1`，与 APIMart 的 `<<<image_N>>>`、KIE 的 `@自定义名称` 都不同——提示词模板必须按供应商分开。
+- 「Kling O3 = Kling 3.0 Omni」这层命名映射未见 Fal 官方文档明确背书，接入或排障时要留意。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Pro 文生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/o3/pro/text-to-video/llms.txt | 否 |
+| Pro 图生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/o3/pro/image-to-video/llms.txt | 否 |
+| Pro 参考生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/o3/pro/reference-to-video/llms.txt | 否 |
+| Standard 文生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/o3/standard/text-to-video/llms.txt | 否 |
+| Standard 图生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/o3/standard/image-to-video/llms.txt | 否 |
+| Standard 参考生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/o3/standard/reference-to-video/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| 可灵官方视频能力地图（确认 `kling-v3-omni` 命名） | https://www.klingai.com/document-api/guides/capability-map/video | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |

package/docs/model-adaptation/Kling-3.0-Omni/Kling-3.0-Omni_KIE.md

@@ -0,0 +1,143 @@
+# Kling 3.0 Omni · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `kling-3.0-omni/text-to-video`、`kling-3.0-omni/image-to-video`、`kling-3.0-omni/reference-to-video`、`kling-3.0-omni/transformation` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录（**定价页未单列 Omni 条目，见第 5 节**） |
+
+> KIE 上 Kling 3.0 Omni 有 **4 个端点**，其中 `transformation`（视频转换 / 编辑）是上一版适配遗漏的能力。
+
+## 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 |
+|---|---|
+| 文生视频 | `kling-3.0-omni/text-to-video` |
+| 图生视频（单张首帧） | `kling-3.0-omni/image-to-video` |
+| 参考生视频（参考图 / 参考视频 / 主体） | `kling-3.0-omni/reference-to-video` |
+| **视频转换 / 编辑** | `kling-3.0-omni/transformation` |
+
+## 3. 请求参数
+
+### 3.1 通用字段（四个端点共有或大部分共有）
+
+| 字段 | 类型 | 默认 | 取值与说明 |
+|---|---|---|---|
+| `input.prompt` | string | — | 去首尾空白后不能为空，**最长 3072 字符** |
+| `input.duration` | integer | `5` | 枚举 3–15 秒 |
+| `input.resolution` | string | `720p` | `720p` / `1080p` / **`4k`** |
+| `input.aspect_ratio` | string | 视端点而定 | `16:9`、`9:16`、`1:1`、`auto`（各端点可选集合不同，见下） |
+| `input.audio` | boolean | `false` | 是否开启音频。**建议显式传入** |
+| `input.customize_multi_shots` | boolean | 文生 `true` | 是否开启**自定义**多镜头。**建议显式指定** |
+| `input.prefer_multi_shots` | boolean | — | 是否开启**智能分镜**。**与 `customize_multi_shots` 互斥**：两者可以同时为 `false`，但**不能同时为 `true`** |
+| `input.multi_prompt` | array | `[]` | 自定义分镜列表，**最多 6 个**。`customize_multi_shots=true` 时必填且不能为空；为 `false` 时**必须为空数组或省略** |
+| `input.elements` | array | `[]` | 一次性主体素材列表，见下 |
+
+`multi_prompt` 元素：`prompt`（1–512 字符，必填）、`duration`（**1–15 秒**，必填）。
+
+### 3.2 `elements`（主体素材）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `name` | string | 必填 | 主体名称，**同一请求内唯一**，prompt 中用 `@名称` 引用 |
+| `description` | string | 必填 | 主体素材的文本描述 |
+| `element_input_urls` | array | 必填 | **多图主体传 2–4 张图片；视频角色主体恰好传 1 个视频；图片和视频不能混传**。支持 HTTP / HTTPS / OSS |
+| `element_input_audio_urls` | array | 可选 | 主体音频素材。可读到时长时**必须为 5–30 秒** |
+| `start_time` | integer | 可选（默认 `0`） | 视频角色主体截取开始时间（毫秒），仅传视频时生效 |
+| `end_time` | integer | 可选（默认 `8000`） | 截取结束时间（毫秒），须大于 `start_time`，**截取时长必须为 3000–8000 ms** |
+
+**主体数量限制（文生 / 参考端点）**：仅多图主体时最多 **7 个**主体；仅视频角色主体时不超过 **3 个**；两者同时存在时视频角色主体 ≤ 3、多图主体 ≤ 4。
+**图生视频端点**的 `elements` 上限是 **3 个**。
+
+### 3.3 `kling-3.0-omni/text-to-video`
+
+`aspect_ratio` 可选 `16:9`（默认）、`9:16`、`1:1`。`customize_multi_shots` **默认 `true`**。
+
+### 3.4 `kling-3.0-omni/image-to-video`（`input` 为 `oneOf`，此处为「单张首帧」形态）
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `prompt` | **必填** | ≤ 3072 字符 |
+| `image_urls` | **必填** | 首帧图片，**必须且只能传 1 张**。HTTP / HTTPS / OSS；JPG / JPEG / PNG；**≤ 50 MB**；宽高均 ≥ 300 px；宽高比 0.4–2.5 |
+| `aspect_ratio` | 可选，默认 **`auto`** | `16:9` / `9:16` / `1:1` / `auto`。**只有开启 `customize_multi_shots` 时才可以选 16:9 / 9:16 / 1:1，其余情况为 `auto`** |
+
+### 3.5 `kling-3.0-omni/reference-to-video`（`input` 为 `oneOf`）
+
+**形态 A「无视频输入」**（必填 `prompt` + `image_urls`）
+
+| 字段 | 说明 |
+|---|---|
+| `image_urls` | 参考图片数组，**最多 7 张**。图片数量上限与主体数量/类型相关：无参考视频 + 仅多图主体时，**参考图片与多图主体数量之和 ≤ 7**；无参考视频 + 同时有视频角色主体和多图主体时，**参考图片与多图主体数量之和 ≤ 4**。JPG / JPEG / PNG；≤ 50 MB；宽高 ≥ 300 px；宽高比 0.4–2.5 |
+| `aspect_ratio` | `16:9`（默认）/ `9:16` / `1:1` |
+| `audio` | 无视频输入时支持 `true` / `false` |
+
+**形态 B「仅视频输入」**（必填 `prompt`、`video_urls`、`aspect_ratio`、`audio`）
+
+| 字段 | 说明 |
+|---|---|
+| `video_urls` | **必须且只能传 1 个视频**。MP4 / MOV；**≤ 200 MB**；时长 **3–15.5 秒**；宽高 **700–4553 px**；总像素 **≤ 8,294,400**；宽高比 **0.4–2**；帧率 **24–60 fps** |
+
+### 3.6 `kling-3.0-omni/transformation`（视频转换 / 编辑）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `prompt` | string | 可选 | — | ≤ 3072 字符 |
+| `video_urls` | array | 可选 | — | **必须且只能 1 个视频**。规格同上（MP4/MOV、≤200 MB、3–15.5 s、700–4553 px、总像素 ≤ 8,294,400、宽高比 0.4–2、24–60 fps） |
+| `image_urls` | array | 可选 | — | **最多 4 张**。上限与主体数量/类型有关：仅有多图主体时**参考图片与多图主体数量之和 ≤ 4**；**不同时支持视频角色主体与多图主体或参考图片**。JPG / JPEG / PNG；≤ 50 MB；宽高 ≥ 300 px；宽高比 0.4–2.5 |
+| `duration` | string | 可选 | — | **视频加图片时可保留该字段配置**（纯视频输入时时长跟随源视频） |
+| `resolution` | string | 可选 | `720p` | `720p` / `1080p` / `4k` |
+| `aspect_ratio` | string | 可选 | `16:9` | **仅视频输入时只能为 `auto`；视频加图片时支持 `16:9` / `9:16` / `1:1`，不支持 `auto`** |
+| `audio` | boolean | 可选 | — | 是否开启音频 |
+| `elements` | array | 可选 | `[]` | 同上 |
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://....mp4"] }`。
+
+## 5. 价格
+
+⚠️ **KIE 定价页（2026-08-22 读取，搜索 `kling` / `omni`）未单独列出 `kling-3.0-omni` 的价格条目**，只有 `Kling 3.0`、`kling 3.0 turbo`、`kling 3.0 motion control` 三组。
+
+接入前需要向 KIE 确认 Omni 的计费口径，或先跑一次任务从 `creditsConsumed` 反推。可作为参考的同代价格（`Kling 3.0`，1 Credit = $0.005）：
+
+| 规格 | 积分 | 我们的价格 |
+|---|---|---|
+| 720P 无声 / 有声 | 14 / 20 每秒 | $0.07 / $0.1 每秒 |
+| 1080P 无声 / 有声 | 18 / 27 每秒 | $0.09 / $0.135 每秒 |
+| 4K 无声 / 有声 | 67 / 67 每秒 | $0.335 / $0.335 每秒 |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本组接口都没有这两个字段。
+- **4 个端点的 `aspect_ratio` 规则各不相同**，尤其 `image-to-video`「只有开启自定义多镜头才能选具体比例」和 `transformation`「纯视频输入只能 `auto`、视频+图片不支持 `auto`」——UI 必须按端点与输入组合联动。
+- `customize_multi_shots` 与 `prefer_multi_shots` **不能同时为 `true`**。
+- `customize_multi_shots=false` 时 `multi_prompt` **必须是空数组或不传**，传了会报错。
+- `elements` 的主体数量上限是**动态的**（取决于是否有参考视频、主体类型），需要在前端做组合校验。
+- 视频角色主体的截取窗口必须是 3000–8000 ms。
+- **Omni 在 KIE 定价页没有独立条目**，成本核算需先实测。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Kling 3.0 Omni 文生视频 | https://docs.kie.ai/cn/market/kling/v3-omni-text-to-video | 否 |
+| Kling 3.0 Omni 图生视频 | https://docs.kie.ai/cn/market/kling/v3-omni-image-to-video | 否 |
+| Kling 3.0 Omni Reference-To-Video | https://docs.kie.ai/cn/market/kling/v3-omni-reference-to-video | 否 |
+| Kling 3.0 Omni Transformation | https://docs.kie.ai/cn/market/kling/v3-omni-transformation | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `kling`；**Omni 无独立条目**） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |