@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/Ideogram-/345/233/276/347/211/207/346/224/276/345/244/247/Ideogram-/345/233/276/347/211/207/346/224/276/345/244/247_Fal.md

@@ -0,0 +1,41 @@
+# Ideogram 图片放大（Fal）
+
+## 契约
+
+| 项目 | 内容 |
+|---|---|
+| endpoint ID | `fal-ai/ideogram/upscale` |
+| 输入 | `image_url`，应用严格要求 1 张图片 |
+| 输出 | `images: File[]`，最高约 2× |
+| 应用参数 | resemblance 1～100、detail 1～100，默认均为 50 |
+| 隐藏字段 | prompt、expand_prompt、seed、sync_mode |
+| 价格 | `$0.06/张` |
+| 资料核查 | 2026-08-29；公开，无需登录 |
+
+## 请求示例
+
+```json
+{
+  "image_url": "https://example.com/source.jpg",
+  "resemblance": 50,
+  "detail": 50
+}
+```
+
+## 队列与适配
+
+使用 `Authorization: Key <FAL_KEY>` 调用 `https://queue.fal.run`，状态为 `IN_QUEUE`、
+`IN_PROGRESS`、`COMPLETED`，结果沿用 Fal 通用递归 URL 提取。canonical ID 为 `ideogram-upscale`，
+应用模型 ID 为 `fal-ai-ideogram-upscale`。
+
+画布按固定 2× 预估尺寸；默认输出路径不承诺保留 alpha，透明源图会在上传前提示改用专用模型。当前不开放
+提示词，以保持“高清放大”工具的单图、无提示词交互。已完成端点、范围钳制、固定价与预检离线测试；
+未执行真实付费生成。
+
+## 一手资料
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| API 文档 | https://fal.ai/models/fal-ai/ideogram/upscale/api | 否 |
+| OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ideogram/upscale | 否 |
+| API Key | https://fal.ai/dashboard/keys | 是 |

package/docs/model-adaptation/Image-Apps-v2-/345/225/206/345/223/201/346/221/204/345/275/261/Image-Apps-v2-/345/225/206/345/223/201/346/221/204/345/275/261_Fal.md

@@ -0,0 +1,72 @@
+# Image Apps v2 商品摄影（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Product Photography |
+| API endpoint ID | `fal-ai/image-apps-v2/product-photography` |
+| 模态 | 单张商品图 → 单张影棚商品图 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/product-photography` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
+| 价格 | `$0.04 / image` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+## 1. 能力与产品边界
+
+该端点会为商品生成写实的影棚式背景和光照。官方 API 只接收商品图和输出比例，没有提示词、背景风格、光照风格、品牌色或生成数量字段。产品首版只能给出“自动商品摄影”能力，不应补造这些控制项。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/image-apps-v2/product-photography`
+- 队列提交：`POST https://queue.fal.run/fal-ai/image-apps-v2/product-photography`
+- 状态：`GET https://queue.fal.run/fal-ai/image-apps-v2/product-photography/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/image-apps-v2/product-photography/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/image-apps-v2/product-photography/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；`images` 必填
+
+通用状态为 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` 和 `request_id` 必填。`COMPLETED` 是状态终态，客户端仍需取结果并确认存在非空 `images[].url`。没有模型专属错误码或新事件，其余使用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `product_image_url` | string | 是 | 官方未公布文件限制 | 恰好 1 张已有素材；这是特殊媒体字段，必须在 `runtimeConstraints.mediaFields` 声明为图片并由 Fal CDN 上传 |
+| `aspect_ratio` | `{ratio: enum}` | 否 | `ratio` 子字段默认 `1:1`；枚举 `1:1` / `16:9` / `9:16` / `4:3` / `3:4` | 复用标准智能比例，按首图就近匹配，最终必须发送 `{ratio: '...'}` 对象 |
+
+`aspect_ratio` 描述为“4K 输出比例”，OpenAPI 未提供精确宽高。`smart` 是本地 UI 值，不能原样发给 Fal。
+
+## 4. 请求与响应示例
+
+```json
+{
+  "product_image_url": "https://v3.fal.media/files/.../product.png",
+  "aspect_ratio": { "ratio": "1:1" }
+}
+```
+
+```json
+{
+  "images": [
+    { "url": "https://v3b.fal.media/files/.../studio-product.png" }
+  ]
+}
+```
+
+## 5. 计价与未知项
+
+- 实时 `llms.txt` 标价 `$0.04 / image`，静态估价为 `$0.04 / 次`。
+- 官方未公布输入格式/尺寸/文件大小上限、输出的精确 4K 宽高、延迟 SLA 或背景生成的可控边界。
+- 需付费验证透明背景商品、白底商品、人像穿戴商品、文字/商标保持和不同比例的主体完整性。
+- 不定义、不发送 `seed`、负面提示词、`output_format` 或文档未声明的字段。
+
+## 6. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/image-apps-v2/product-photography | 否 | 2026-08-29 |
+| 实时字段、示例与价格 | https://fal.ai/models/fal-ai/image-apps-v2/product-photography/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（对象比例、必填与响应） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/image-apps-v2/product-photography | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |
+| Fal 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） | 2026-08-29 |

package/docs/model-adaptation/Image-Apps-v2-/346/211/251/345/233/276/Image-Apps-v2-/346/211/251/345/233/276_Fal.md

@@ -0,0 +1,93 @@
+# Image Apps v2 扩图（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Image Outpaint |
+| API endpoint ID | `fal-ai/image-apps-v2/outpaint` |
+| 模态 | 单图输入 → 单张扩图结果 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/outpaint` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
+| 价格 | `$0.035 / megapixel` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+## 1. 能力与语义
+
+该端点支持两种可以叠加的扩图控制：
+
+- `expand_left/right/top/bottom`：在四边增加 `0..700` 像素的黑色待生成区域。
+- `zoom_out_percentage`：把原图缩小 `0..90%`，用黑色边缘填满原始画布，再生成新区域。
+
+官方将 `zoom_out_percentage` 称为可选能力，但 schema 默认值是 `20`。首版应把它作为可见数值并显式发送，避免 UI 显示值与服务端实际缩放不一致。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/image-apps-v2/outpaint`
+- 队列提交：`POST https://queue.fal.run/fal-ai/image-apps-v2/outpaint`
+- 状态：`GET https://queue.fal.run/fal-ai/image-apps-v2/outpaint/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/image-apps-v2/outpaint/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/image-apps-v2/outpaint/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；`images` 和 `seed` 在 OpenAPI 中必填
+
+队列仅使用 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` / `request_id` 必填。`COMPLETED` 后再取结果，且只有非空 `images[].url` 才算有效结果。模型没有新增状态或错误码，断线、取消和资源释放沿用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_url` | string | 是 | 官方未公布格式与尺寸限制 | 恰好 1 张已有素材，经 Fal CDN 上传 |
+| `expand_left` | integer | 否 | `0`；`0..700` | 显示并发送 |
+| `expand_right` | integer | 否 | `0`；`0..700` | 显示并发送 |
+| `expand_top` | integer | 否 | `0`；`0..700` | 显示并发送 |
+| `expand_bottom` | integer | 否 | `0`；`0..700` | 显示并发送 |
+| `zoom_out_percentage` | number | 否 | `20`；`0..90` | 显示并显式发送 |
+| `prompt` | string | 否 | `""`；最长 500 字符 | 复用工具的提示词输入；空值不发送 |
+| `num_images` | integer | 否 | `1`；`1..4` | 首版固定 1，不展示、不发送 |
+| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不发送 |
+| `seed` | integer/null | 否 | 随机 | 不展示、不发送 |
+| `sync_mode` | boolean | 否 | `false` | 不展示、不发送 |
+| `output_format` | enum | 否 | `png`；`png` / `jpeg` / `jpg` / `webp` | 按项目约定不展示、不发送 |
+
+产品在提交前应拒绝“四边均为 0 且缩放为 0”的明显无操作组合，避免付费生成近似原图。这是产品校验，不是官方 API 硬限制。
+
+## 4. 请求与响应示例
+
+```json
+{
+  "image_url": "https://v3.fal.media/files/.../source.png",
+  "expand_left": 200,
+  "expand_right": 200,
+  "expand_top": 0,
+  "expand_bottom": 0,
+  "zoom_out_percentage": 20,
+  "prompt": "continue the sunset landscape naturally"
+}
+```
+
+```json
+{
+  "images": [
+    { "url": "https://v3b.fal.media/files/.../outpainted.png" }
+  ],
+  "seed": 123456
+}
+```
+
+## 5. 计价与未知项
+
+- 实时 `llms.txt` 标价 `$0.035 / megapixel`。文本未明确这是输入、输出还是处理像素；由于四边扩展会改变面积，静态首屏只应显示单位价或明确标注“估算”。
+- 最终成本需使用 Fal pricing API / billing event 的实际 billing units 对账。
+- 官方未给输入尺寸/格式上限、扩展后的最大总尺寸、延迟 SLA 和无操作组合的服务端行为。
+- 付费验证要覆盖单边、非对称多边、纯缩放以及扩展+缩放叠加四类请求。
+
+## 6. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/image-apps-v2/outpaint | 否 | 2026-08-29 |
+| 实时字段、范围、示例与价格 | https://fal.ai/models/fal-ai/image-apps-v2/outpaint/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（完整范围、必填与响应） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/image-apps-v2/outpaint | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |
+| Fal 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） | 2026-08-29 |

package/docs/model-adaptation/Image-Apps-v2-/347/205/247/347/211/207/344/277/256/345/244/215/Image-Apps-v2-/347/205/247/347/211/207/344/277/256/345/244/215_Fal.md

@@ -0,0 +1,86 @@
+# Image Apps v2 照片修复（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Photo Restoration |
+| API endpoint ID | `fal-ai/image-apps-v2/photo-restoration` |
+| 模态 | 单张旧照片 → 单张修复图片 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/photo-restoration` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
+| 价格 | `$0.04 / image` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+## 1. 能力与边界
+
+官方提供三个可独立开关的修复能力：提升清晰度、修复颜色、消除划痕。端点不接收提示词或修复强度，也没有人脸保真程度、上色风格等控件。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/image-apps-v2/photo-restoration`
+- 队列提交：`POST https://queue.fal.run/fal-ai/image-apps-v2/photo-restoration`
+- 状态：`GET https://queue.fal.run/fal-ai/image-apps-v2/photo-restoration/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/image-apps-v2/photo-restoration/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/image-apps-v2/photo-restoration/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；`images` 必填
+
+通用队列状态为 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` / `request_id` 必填。`COMPLETED` 后必须另取结果并校验 `images[].url`；没有模型专属状态或错误码，其余复用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_url` | string | 是 | 官方未公布文件限制 | 恰好 1 张已有素材，经 Fal CDN 上传 |
+| `enhance_resolution` | boolean | 否 | `true` | 显示并发送 |
+| `fix_colors` | boolean | 否 | `true` | 显示并发送 |
+| `remove_scratches` | boolean | 否 | `true` | 显示并发送 |
+| `aspect_ratio` | `{ratio: enum}` | 否 | 见下方冲突说明；枚举 `1:1` / `16:9` / `9:16` / `4:3` / `3:4` | 复用标准智能比例，按首图就近匹配，显式发送 `{ratio: '...'}` 对象 |
+
+### 比例默认值冲突
+
+- `aspect_ratio` 字段描述写“default: 4:3 for classic photos”。
+- 同一份 OpenAPI 的 `AspectRatio.ratio` schema 默认值却是 `1:1`。
+
+两处官方资料自相矛盾，不使用供应商隐式默认。SDK 应始终把本地 `smart` 按输入图比例转成具体枚举，再发送对象。
+
+三个修复开关全为 `false` 时，官方没有说明服务端行为。产品应在提交前要求至少一项为 `true`，避免支付一次无操作请求；这是产品保守校验，不是官方 API 硬限制。
+
+## 4. 请求与响应示例
+
+```json
+{
+  "image_url": "https://v3.fal.media/files/.../old-photo.png",
+  "enhance_resolution": true,
+  "fix_colors": true,
+  "remove_scratches": true,
+  "aspect_ratio": { "ratio": "4:3" }
+}
+```
+
+```json
+{
+  "images": [
+    { "url": "https://v3b.fal.media/files/.../restored.png" }
+  ]
+}
+```
+
+## 5. 计价与未知项
+
+- 实时 `llms.txt` 标价 `$0.04 / image`，三个开关不改变单价。
+- 静态估价为 `$0.04 / 次`；最终以账户价格和 billing event 为准。
+- 官方未给输入格式/尺寸/文件大小上限、精确 4K 输出宽高、延迟 SLA 和人脸/文字保真承诺。
+- 付费验收要分别测试黑白上色、褪色修复、划痕消除、低清放大以及三项叠加。
+- 该 API 没有 `seed`、负面提示词或 `output_format` 字段，不得发送。
+
+## 6. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/image-apps-v2/photo-restoration | 否 | 2026-08-29 |
+| 实时字段、默认、示例与价格 | https://fal.ai/models/fal-ai/image-apps-v2/photo-restoration/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（对象比例、冲突默认值、必填与响应） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/image-apps-v2/photo-restoration | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |
+| Fal 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） | 2026-08-29 |

package/docs/model-adaptation/Image-Apps-v2-/351/207/215/346/211/223/345/205/211/Image-Apps-v2-/351/207/215/346/211/223/345/205/211_Fal.md

@@ -0,0 +1,84 @@
+# Image Apps v2 重打光（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Relighting |
+| API endpoint ID | `fal-ai/image-apps-v2/relighting` |
+| 模态 | 单图输入 → 单张重打光图片 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/relighting` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
+| 价格 | `$0.04 / image` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+## 1. 能力与产品边界
+
+该端点使用固定预设为单张图片重新设计光照，没有提示词、光源坐标、光强、色温或遮罩字段。产品不应将预设宣称为物理精确打光，也不应补造不会进入请求的提示词输入。
+
+18 个官方光照预设是：
+
+`natural` / `studio` / `golden_hour` / `blue_hour` / `dramatic` / `soft` / `hard` / `backlight` / `side_light` / `front_light` / `rim_light` / `sunset` / `sunrise` / `neon` / `candlelight` / `moonlight` / `spotlight` / `ambient`。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/image-apps-v2/relighting`
+- 队列提交：`POST https://queue.fal.run/fal-ai/image-apps-v2/relighting`
+- 状态：`GET https://queue.fal.run/fal-ai/image-apps-v2/relighting/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/image-apps-v2/relighting/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/image-apps-v2/relighting/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；`images` 必填，数组元素只有 `url` 必填
+
+| 状态 | 字段与语义 | 客户端处理 |
+|---|---|---|
+| `IN_QUEUE` | `status` / `request_id` 必填；`queue_position` 可选 | 继续轮询，不产生媒体结果 |
+| `IN_PROGRESS` | `status` / `request_id` 必填；`logs` / `metrics` 可选 | 继续轮询，可更新进度 |
+| `COMPLETED` | 状态终态；官方状态 schema 不代表业务必然成功 | 再取结果，校验 `images[].url`；空数组或缺 URL 按契约失败处理 |
+
+模型没有新增队列状态、回调事件或错误码。取消后是否还会看到短暂状态迁移、断线后的保留期和乱序规则，模型 OpenAPI 未说明；实现继续复用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_url` | string | 是 | 官方未给文件大小与格式上限 | 恰好 1 张已有素材，由 Fal CDN 上传后填入 |
+| `lighting_style` | enum | 否 | `natural`；共18个预设 | 显示并发送 |
+| `aspect_ratio` | `{ratio: enum}` | 否 | `ratio` 子字段默认 `1:1`；支持 `1:1` / `16:9` / `9:16` / `4:3` / `3:4` | 复用标准智能比例，按首图就近匹配，发送对象而非字符串 |
+
+`aspect_ratio` 的描述是“4K 输出比例”。OpenAPI 没有给出各比例的精确像素尺寸，不应在 SDK 中自行硬编一组未经证实的 4K 宽高。
+
+## 4. 请求与响应示例
+
+```json
+{
+  "image_url": "https://v3.fal.media/files/.../source.png",
+  "lighting_style": "golden_hour",
+  "aspect_ratio": { "ratio": "4:3" }
+}
+```
+
+```json
+{
+  "images": [
+    { "url": "https://v3b.fal.media/files/.../relit.png" }
+  ]
+}
+```
+
+## 5. 计价、适配要点与未知项
+
+- 实时 `llms.txt` 标价 `$0.04 / image`，不随已选光照预设或比例变化。
+- 静态预估为 `$0.04 / 次`；最终以账户价格 API 和 billing event 为准。
+- 不定义、不发送 `seed`、负面提示词、`output_format` 或任何文档未声明的字段。
+- 官方未给输入分辨率、格式、大小、延迟 SLA 与结果保留期；接入前需用真实请求验证。
+
+## 6. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/image-apps-v2/relighting | 否 | 2026-08-29 |
+| 实时字段、枚举、示例与价格 | https://fal.ai/models/fal-ai/image-apps-v2/relighting/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（对象比例、必填与响应结构） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/image-apps-v2/relighting | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |
+| Fal 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） | 2026-08-29 |

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

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

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

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