@henjicc/ai-sdk 0.8.0 → 0.10.0

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

@@ -1,112 +1,112 @@
-# Kling 3.0 · APIMart
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 视频 |
-| 供应商 | APIMart（聚合平台） |
-| 平台模型 ID | `kling-v3` |
-| 接口形态 | **异步任务** |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-| 上游官方模型标识 | `kling-v3`（与可灵官方能力地图一致） |
-
-## 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` |
-| `prompt` | string | 必填 | — | 正向提示词。**建议使用英文提示词**。`multi_shot=true` 时顶层 `prompt` 可省略 |
-| `negative_prompt` | string | 可选 | — | 负面提示词。**本项目规则：绝对不显示**，不下发 |
-| `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 | 可选 | — | **最多 2 张**：传 1 张 = 首帧；传 2 张 = 自动分配为首帧 + 尾帧。URL 必须公开可访问、**不能有防盗链** |
-| `watermark` | boolean | 可选 | — | 是否添加水印 |
-| `audio` | boolean | 可选 | **`false`** | 是否生成有声视频 |
-| `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 个主体** |
-| `nsfw_check` | boolean | 可选 | `false` | 提交前内容审核 |
-
-### 多镜头分镜（`multi_prompt`）约束
-
-- 最多 **6 个**分镜，最少 1 个
-- 每个分镜相关内容的最大长度 **≤ 512**
-- 每个分镜的时长 **不大于当前任务总时长，且不小于 1**
-- **所有分镜时长之和必须等于当前任务总时长**
-- `index` 从 1 连续递增
-
-### 引用元素（`element_list`）
-
-现场创建主体时 `name`、`description`、`element_input_urls` 均必填。
-`element_input_urls`：每个主体**至少 2 张、最多 4 张**（第 1 张正面图 + 其余参考图）。
-在 `prompt` 中通过 **`@name`** 引用，例如 `"@element_dog 和 @element_cat 在草地上追逐玩耍"`。
-
-### 参数互斥与边界
-
-- `mode=4k` 在 `kling-v3` 可用
-- `image_urls` 最多 2 张
-- **仅尾帧输入（只有 `last_frame`）会报错，必须配首帧**
-- `multi_shot=true` 时顶层 `prompt` 可省略
-- `multi_prompt` 最多 6 个分镜，`index` 从 1 连续递增
-
-### 功能支持矩阵（文档给出）
-
-| 类型 | 功能 | std 5s | std 10s | std 15s | pro 5s | pro 10s |
-|---|---|---|---|---|---|---|
-| 文生视频 | 视频生成 | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 图生视频 | 视频生成 | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 图生视频 | 首帧 | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 图生视频 | 尾帧 | ✅ | ✅ | ✅ | ✅ | ✅ |
-
-系统会根据 `image_urls` 自动判断文生 / 图生模式。
-
-## 4. 响应结构
-
-提交返回 `{ code, data: [{ status: "submitted", task_id }] }`；轮询 `GET /v1/tasks/{task_id}`，成功后读 `result.videos[]`。
-
-## 5. 价格
-
-来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → 视频标签页 `KLING-V3`（2026-08-22，6 个档位，1 Credit ≈ $0.1）。
-
-| 规格 | 我们的价格 | 官方价 | 节省 |
-|---|---|---|---|
-| 默认（std 无声） | 0.672 Credits/秒 ≈ **$0.0672/秒** | $0.084 | 20% |
-| `sound`（std 有声） | 1.008 Credits/秒 ≈ **$0.1008/秒** | $0.126 | 20% |
-| `pro`（1080P 无声） | 0.896 Credits/秒 ≈ **$0.0896/秒** | $0.112 | 20% |
-| `pro-sound`（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% |
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口**有 `negative_prompt`**，必须主动不注册、不下发（无 `seed` 字段）。
-- `audio` **默认 `false`**（与 Seedance 的 `generate_audio: true` 相反），且有声比无声贵 33%~50%。
-- `duration` 必须以数字类型下发。
-- 图生视频时 `aspect_ratio` 可能被图片比例覆盖——UI 上应提示或禁用。
-- **多镜头分镜是一整套子能力**：`multi_shot` + `shot_type` + `multi_prompt`，且分镜时长之和必须等于总时长，需要专门的编辑交互。
-- **引用元素（主体一致性）是另一套子能力**：每个主体 2–4 张图，prompt 中用 `@name` 引用，最多 3 个主体。
-- 只传尾帧会报错，必须配首帧。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Kling v3 视频生成 | https://docs.apimart.ai/cn/api-reference/videos/kling-v3/generation | 否 |
-| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
-| 定价中心（视频标签页搜 KLING-V3） | https://apimart.ai/zh/pricing | 否 |
-| 可灵官方视频能力地图（仅参考，不适配官方接口） | https://www.klingai.com/document-api/guides/capability-map/video | 否 |
-| API Key 管理 | https://apimart.ai/keys | **是** |
+# Kling 3.0 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `kling-v3` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 上游官方模型标识 | `kling-v3`（与可灵官方能力地图一致） |
+
+## 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` |
+| `prompt` | string | 必填 | — | 正向提示词。**建议使用英文提示词**。`multi_shot=true` 时顶层 `prompt` 可省略 |
+| `negative_prompt` | string | 可选 | — | 负面提示词。**本项目规则：绝对不显示**，不下发 |
+| `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 | 可选 | — | **最多 2 张**：传 1 张 = 首帧；传 2 张 = 自动分配为首帧 + 尾帧。URL 必须公开可访问、**不能有防盗链** |
+| `watermark` | boolean | 可选 | — | 是否添加水印 |
+| `audio` | boolean | 可选 | **`false`** | 是否生成有声视频 |
+| `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 个主体** |
+| `nsfw_check` | boolean | 可选 | `false` | 提交前内容审核 |
+
+### 多镜头分镜（`multi_prompt`）约束
+
+- 最多 **6 个**分镜，最少 1 个
+- 每个分镜相关内容的最大长度 **≤ 512**
+- 每个分镜的时长 **不大于当前任务总时长，且不小于 1**
+- **所有分镜时长之和必须等于当前任务总时长**
+- `index` 从 1 连续递增
+
+### 引用元素（`element_list`）
+
+现场创建主体时 `name`、`description`、`element_input_urls` 均必填。
+`element_input_urls`：每个主体**至少 2 张、最多 4 张**（第 1 张正面图 + 其余参考图）。
+在 `prompt` 中通过 **`@name`** 引用，例如 `"@element_dog 和 @element_cat 在草地上追逐玩耍"`。
+
+### 参数互斥与边界
+
+- `mode=4k` 在 `kling-v3` 可用
+- `image_urls` 最多 2 张
+- **仅尾帧输入（只有 `last_frame`）会报错，必须配首帧**
+- `multi_shot=true` 时顶层 `prompt` 可省略
+- `multi_prompt` 最多 6 个分镜，`index` 从 1 连续递增
+
+### 功能支持矩阵（文档给出）
+
+| 类型 | 功能 | std 5s | std 10s | std 15s | pro 5s | pro 10s |
+|---|---|---|---|---|---|---|
+| 文生视频 | 视频生成 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 图生视频 | 视频生成 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 图生视频 | 首帧 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 图生视频 | 尾帧 | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+系统会根据 `image_urls` 自动判断文生 / 图生模式。
+
+## 4. 响应结构
+
+提交返回 `{ code, data: [{ status: "submitted", task_id }] }`；轮询 `GET /v1/tasks/{task_id}`，成功后读 `result.videos[]`。
+
+## 5. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → 视频标签页 `KLING-V3`（2026-08-22，6 个档位，1 Credit ≈ $0.1）。
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认（std 无声） | 0.672 Credits/秒 ≈ **$0.0672/秒** | $0.084 | 20% |
+| `sound`（std 有声） | 1.008 Credits/秒 ≈ **$0.1008/秒** | $0.126 | 20% |
+| `pro`（1080P 无声） | 0.896 Credits/秒 ≈ **$0.0896/秒** | $0.112 | 20% |
+| `pro-sound`（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% |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口**有 `negative_prompt`**，必须主动不注册、不下发（无 `seed` 字段）。
+- `audio` **默认 `false`**（与 Seedance 的 `generate_audio: true` 相反），且有声比无声贵 33%~50%。
+- `duration` 必须以数字类型下发。
+- 图生视频时 `aspect_ratio` 可能被图片比例覆盖——UI 上应提示或禁用。
+- **多镜头分镜是一整套子能力**：`multi_shot` + `shot_type` + `multi_prompt`，且分镜时长之和必须等于总时长，需要专门的编辑交互。
+- **引用元素（主体一致性）是另一套子能力**：每个主体 2–4 张图，prompt 中用 `@name` 引用，最多 3 个主体。
+- 只传尾帧会报错，必须配首帧。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Kling v3 视频生成 | https://docs.apimart.ai/cn/api-reference/videos/kling-v3/generation | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（视频标签页搜 KLING-V3） | 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/Kling-3.0_Fal.md

@@ -1,89 +1,91 @@
-# Kling 3.0 · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 视频 |
-| 供应商 | fal.ai（聚合平台） |
-| 平台模型 ID | `fal-ai/kling-video/v3/{pro,standard}/{text-to-video,image-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. 能力清单（Fal 用「档位 × 输入形态」拆端点）
-
-| 档位 | 文生视频 | 图生视频 |
-|---|---|---|
-| Pro（1080P） | `fal-ai/kling-video/v3/pro/text-to-video` | `fal-ai/kling-video/v3/pro/image-to-video` |
-| Standard（720P） | `fal-ai/kling-video/v3/standard/text-to-video` | `fal-ai/kling-video/v3/standard/image-to-video` |
-
-> Fal 上 Kling v3 **没有 4K 档**（APIMart 与 KIE 有）。
-
-## 3. 请求参数
-
-### 3.1 `text-to-video`
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `prompt` | string | 可选 | — | **`prompt` 与 `multi_prompt` 必须二选一，不能同时给** |
-| `multi_prompt` | array | 可选 | — | 多镜头分镜列表。给了就覆盖单 prompt，把视频切成多个镜头 |
-| `duration` | string | 可选 | `"5"` | **字符串枚举** `"3"` ~ `"15"` |
-| `generate_audio` | boolean | 可选 | **`true`** | 原生音频。**支持中英文语音输出，其他语言自动翻译成英文**；英文语音用小写字母，缩写或专有名词用大写 |
-| `shot_type` | string | 可选 | `customize` | `customize` / `intelligent`（由模型自动决定分镜结构） |
-| `aspect_ratio` | string | 可选 | `16:9` | `16:9`、`9:16`、`1:1` |
-| `negative_prompt` | string | 可选 | **`"blur, distort, and low quality"`** | 负面提示词。**本项目规则：绝对不显示**，不下发——但注意 Fal **有非空默认值**，不下发时平台仍会用这个默认值 |
-| `cfg_scale` | float | 可选 | `0.5` | 0–1，控制贴合提示词的程度 |
-
-### 3.2 `image-to-video`
-
-在上表基础上（**无 `aspect_ratio`**）：
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `start_image_url` | string | **必填** | 首帧图 URL |
-| `end_image_url` | string | 可选 | 尾帧图 URL |
-| `elements` | array | 可选 | 要出现在视频中的元素（角色 / 物体）。每个元素可以是**一组图片（正面图 + 参考图）或一个视频**。prompt 中用 **`@Element1`、`@Element2`** 引用 |
-
-## 4. 响应结构
-
-```json
-{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" } }
-```
-
-## 5. 价格
-
-来源：各端点 `llms.txt`（2026-08-22 读取）。
-
-| 档位 | 关音频 | 开音频 | 开音频 + voice control |
-|---|---|---|---|
-| Pro | **$0.112 / 秒** | **$0.168 / 秒** | **$0.196 / 秒** |
-| Standard | **$0.084 / 秒** | **$0.126 / 秒** | **$0.154 / 秒** |
-
-例：Pro 5 秒、开音频 + voice control = $0.98。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**有 `negative_prompt` 且默认值非空**（`"blur, distort, and low quality"`）——不下发时它仍在生效，与「不使用负面提示词」不是一回事，需要在文档/产品上明确。
-- `generate_audio` **默认 `true`**（APIMart / KIE 默认关），且有声比无声贵 50%。
-- `duration` 是**字符串枚举**。
-- **`prompt` 与 `multi_prompt` 互斥**，不能同时给。
-- 档位通过 **endpoint 路径**选择（pro / standard），不是参数——适配层要做端点路由，且**没有 4K**。
-- `image-to-video` 端点没有 `aspect_ratio`，比例由首帧图决定。
-- `elements` 的引用写法是 `@Element1`（KIE / APIMart 是 `@自定义名称`），提示词模板不通用。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Pro 文生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/pro/text-to-video/llms.txt | 否 |
-| Pro 图生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/pro/image-to-video/llms.txt | 否 |
-| Standard 文生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/standard/text-to-video/llms.txt | 否 |
-| Standard 图生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/standard/image-to-video/llms.txt | 否 |
-| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
-| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+# Kling 3.0 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `fal-ai/kling-video/v3/{pro,standard}/{text-to-video,image-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. 能力清单（Fal 用「档位 × 输入形态」拆端点）
+
+| 档位 | 文生视频 | 图生视频 |
+|---|---|---|
+| Pro（1080P） | `fal-ai/kling-video/v3/pro/text-to-video` | `fal-ai/kling-video/v3/pro/image-to-video` |
+| Standard（720P） | `fal-ai/kling-video/v3/standard/text-to-video` | `fal-ai/kling-video/v3/standard/image-to-video` |
+
+> Fal 上 Kling v3 **没有 4K 档**（APIMart 与 KIE 有）。
+
+## 3. 请求参数
+
+### 3.1 `text-to-video`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 可选 | — | **`prompt` 与 `multi_prompt` 必须二选一，不能同时给** |
+| `multi_prompt` | array | 可选 | — | 多镜头分镜列表。给了就覆盖单 prompt，把视频切成多个镜头 |
+| `duration` | string | 可选 | `"5"` | **字符串枚举** `"3"` ~ `"15"` |
+| `generate_audio` | boolean | 可选 | **`true`** | 原生音频。**支持中英文语音输出，其他语言自动翻译成英文**；英文语音用小写字母，缩写或专有名词用大写 |
+| `shot_type` | string | 可选 | `customize` | `customize` / `intelligent`（由模型自动决定分镜结构） |
+| `aspect_ratio` | string | 可选 | `16:9` | `16:9`、`9:16`、`1:1` |
+| `negative_prompt` | string | 可选 | **`"blur, distort, and low quality"`** | 负面提示词。**本项目规则：绝对不显示**，不下发——但注意 Fal **有非空默认值**，不下发时平台仍会用这个默认值 |
+| `cfg_scale` | float | 可选 | `0.5` | 0–1，控制贴合提示词的程度 |
+
+### 3.2 `image-to-video`
+
+在上表基础上（**无 `aspect_ratio`**）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `start_image_url` | string | **必填** | 首帧图 URL |
+| `end_image_url` | string | 可选 | 尾帧图 URL |
+| `elements` | array | 可选 | 要出现在视频中的元素（角色 / 物体）。每个元素可以是**一组图片（正面图 + 参考图）或一个视频**。prompt 中用 **`@Element1`、`@Element2`** 引用 |
+
+## 4. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" } }
+```
+
+## 5. 价格
+
+来源：各端点 `llms.txt`（2026-08-22 读取）。
+
+| 档位 | 关音频 | 开音频 | 开音频 + voice control |
+|---|---|---|---|
+| Pro | **$0.112 / 秒** | **$0.168 / 秒** | **$0.196 / 秒** |
+| Standard | **$0.084 / 秒** | **$0.126 / 秒** | **$0.154 / 秒** |
+
+例：Pro 5 秒、开音频 + voice control = $0.98。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**有 `negative_prompt` 且默认值非空**（`"blur, distort, and low quality"`）——不下发时它仍在生效，与「不使用负面提示词」不是一回事，需要在文档/产品上明确。
+- `generate_audio` **默认 `true`**（APIMart / KIE 默认关），且有声比无声贵 50%。
+- `duration` 是**字符串枚举**。
+- **`prompt` 与 `multi_prompt` 互斥**，不能同时给。
+- 档位通过 **endpoint 路径**选择（pro / standard），不是参数——适配层要做端点路由，且**没有 4K**。
+- `image-to-video` 端点没有 `aspect_ratio`，比例由首帧图决定。
+- `elements` 的引用写法是 `@Element1`（KIE / APIMart 是 `@自定义名称`），提示词模板不通用。
+
+- 界面与请求一致（2026-11-08“所选即所发”离线检查）：带首帧时图生视频端点没有比例字段，比例参数在带图时隐藏。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Pro 文生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/pro/text-to-video/llms.txt | 否 |
+| Pro 图生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/pro/image-to-video/llms.txt | 否 |
+| Standard 文生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/standard/text-to-video/llms.txt | 否 |
+| Standard 图生视频 schema + 价格 | https://fal.ai/models/fal-ai/kling-video/v3/standard/image-to-video/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |

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

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