@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/model-adaptation/FLUX-2-/345/244/232/350/247/222/345/272/246/FLUX-2-/345/244/232/350/247/222/345/272/246_Fal.md

@@ -1,107 +1,107 @@
-# FLUX 2 多角度（Fal）适配资料
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-29 |
-| 平台 | Fal |
-| 展示名 | Flux 2 Lora Gallery / Multiple Angles |
-| API endpoint ID | `fal-ai/flux-2-lora-gallery/multiple-angles` |
-| 模态 | 图片数组输入 → 指定镜头角度的图片 |
-| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/flux-2-multiple-angles` |
-| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-multi-angle-tools` |
-| 价格 | `$0.021 / processed megapixel` |
-| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
-
-> 模型用度数表达水平和垂直控制，但没有输出相机内参、外参或误差。产品可称“镜头角度”或“模型控制角”，不能称测量级姿态。
-
-## 1. 角度语义
-
-| 字段 | 官方语义 |
-|---|---|
-| `horizontal_angle` | `0°` 正面，`90°` 右侧，`180°` 背面，`270°` 左侧，`360°` 回到正面 |
-| `vertical_angle` | `0°` 平视，`30°` 高机位，`60°` 高角度俯拍 |
-| `zoom` | `0` 远景，`5` 中景，`10` 近景 |
-
-该端点没有请求 `prompt`：官方说明提示词由滑块数值自动组装。正式 UI 不应展示一个不会进入请求的提示词框。
-
-## 2. 接口与队列契约
-
-- 鉴权：`Authorization: Key <FAL_KEY>`
-- 直连：`POST https://fal.run/fal-ai/flux-2-lora-gallery/multiple-angles`
-- 队列提交：`POST https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles`
-- 状态：`GET https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}/status`
-- 结果：`GET https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}`
-- 取消：`PUT https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}/cancel`
-- 结果路径：`images[].url`；OpenAPI 还把 `seed` 和服务端组装的 `prompt` 标为必填
-
-通用状态为 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` / `request_id` 必填。`COMPLETED` 后再获取结果并严格校验 `images[].url`；模型没有新增状态或错误码，其余复用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
-
-## 3. 请求字段
-
-| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
-|---|---|---|---|---|
-| `image_urls` | `string[]` | 是 | **官方未给 `minItems` / `maxItems`** | 首版保守限制恰好 1 张；这是产品约束，不冒充官方限制；由 Fal CDN 上传 |
-| `horizontal_angle` | number | 否 | `0`；`0..360` | 显示并发送 |
-| `vertical_angle` | number | 否 | `0`；`0..60` | 显示并发送 |
-| `zoom` | number | 否 | `5`；`0..10` | 显示并发送 |
-| `image_size` | 对象 / enum / null | 否 | 枚举见下 | 首版按输入比例选约 1MP 标准档，显式发送，限制波动与费用 |
-| `guidance_scale` | number | 否 | `2.5`；`0..20` | 不展示、不发送 |
-| `num_inference_steps` | integer | 否 | `40`；`4..50` | 不展示、不发送 |
-| `acceleration` | enum | 否 | `regular`；`none` / `regular` | 不展示、不发送 |
-| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不发送 |
-| `num_images` | integer | 否 | `1`；`1..4` | 首版一个目标角度对应一张，固定 1，不展示、不发送 |
-| `lora_scale` | number | 否 | `1`；`0..2` | 不展示、不发送 |
-| `seed` | integer/null | 否 | 随机 | 不展示、不发送 |
-| `sync_mode` | boolean | 否 | `false` | 不展示、不发送 |
-| `output_format` | enum | 否 | `png`；`png` / `jpeg` / `webp` | 按项目约定不展示、不发送 |
-
-`image_size` 可以是 `{width, height}`（宽高为正整数，单边最大 `14142`，子字段默认 `512`），或以下枚举：
-
-`square_hd` / `square` / `portrait_4_3` / `portrait_16_9` / `landscape_4_3` / `landscape_16_9`。
-
-## 4. 请求与响应示例
-
-```json
-{
-  "image_urls": ["https://v3.fal.media/files/.../object.png"],
-  "horizontal_angle": 90,
-  "vertical_angle": 30,
-  "zoom": 5,
-  "image_size": "square_hd"
-}
-```
-
-```json
-{
-  "images": [
-    { "url": "https://v3b.fal.media/files/.../angle.png" }
-  ],
-  "prompt": "<server-generated prompt>"
-}
-```
-
-OpenAPI 把 `seed` 标为必填，但同一份官方 `llms.txt` 的字面响应示例缺少 `seed`。解析器只应把非空 `images[].url` 当作成功必要条件，`seed` / `prompt` 按可选元数据处理。
-
-## 5. 多角度组与计价
-
-- 每个目标角度使用一次独立 Fal 请求，选择顺序在请求前固定，不从结果文件名推断。
-- 实时 `llms.txt` 标价 `$0.021 / processed megapixel`。首版固定约 1MP 时，单角度静态预算约 `$0.021`；4 角度约 `$0.084`。
-- “processed megapixel”的精确取整和输入/输出基准未在 `llms.txt` 展开，最终以 pricing API / billing event 为准。
-- 多次独立生成不保证身份、文字、不可见结构或背景一致；批次失败和按失败项重试策略应与现有多角度工具保持一致。
-
-## 6. 待真实验证
-
-- 人物、商品、建筑在 `0/90/180/270/360°` 的方位遵从和回环误差。
-- `vertical_angle` 只有正值，是否无法表达仰拍。
-- `zoom` 是改变景别还是同时改变主体几何。
-- 官方未给输入数量、文件限制、延迟 SLA 和一致性承诺。
-
-## 7. 原始链接索引
-
-| 内容 | 链接 | 是否需登录 | 核查日期 |
-|---|---|---|---|
-| 模型页与当前价格 | https://fal.ai/models/fal-ai/flux-2-lora-gallery/multiple-angles | 否 | 2026-08-29 |
-| 实时字段、范围、示例与价格 | https://fal.ai/models/fal-ai/flux-2-lora-gallery/multiple-angles/llms.txt | 否 | 2026-08-29 |
-| OpenAPI（完整尺寸枚举、范围、必填与响应） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/flux-2-lora-gallery/multiple-angles | 否 | 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 |
+# FLUX 2 多角度（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Flux 2 Lora Gallery / Multiple Angles |
+| API endpoint ID | `fal-ai/flux-2-lora-gallery/multiple-angles` |
+| 模态 | 图片数组输入 → 指定镜头角度的图片 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/flux-2-multiple-angles` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-multi-angle-tools` |
+| 价格 | `$0.021 / processed megapixel` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+> 模型用度数表达水平和垂直控制，但没有输出相机内参、外参或误差。产品可称“镜头角度”或“模型控制角”，不能称测量级姿态。
+
+## 1. 角度语义
+
+| 字段 | 官方语义 |
+|---|---|
+| `horizontal_angle` | `0°` 正面，`90°` 右侧，`180°` 背面，`270°` 左侧，`360°` 回到正面 |
+| `vertical_angle` | `0°` 平视，`30°` 高机位，`60°` 高角度俯拍 |
+| `zoom` | `0` 远景，`5` 中景，`10` 近景 |
+
+该端点没有请求 `prompt`：官方说明提示词由滑块数值自动组装。正式 UI 不应展示一个不会进入请求的提示词框。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/flux-2-lora-gallery/multiple-angles`
+- 队列提交：`POST https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles`
+- 状态：`GET https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；OpenAPI 还把 `seed` 和服务端组装的 `prompt` 标为必填
+
+通用状态为 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` / `request_id` 必填。`COMPLETED` 后再获取结果并严格校验 `images[].url`；模型没有新增状态或错误码，其余复用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_urls` | `string[]` | 是 | **官方未给 `minItems` / `maxItems`** | 首版保守限制恰好 1 张；这是产品约束，不冒充官方限制；由 Fal CDN 上传 |
+| `horizontal_angle` | number | 否 | `0`；`0..360` | 显示并发送 |
+| `vertical_angle` | number | 否 | `0`；`0..60` | 显示并发送 |
+| `zoom` | number | 否 | `5`；`0..10` | 显示并发送 |
+| `image_size` | 对象 / enum / null | 否 | 枚举见下 | 首版按输入比例选约 1MP 标准档，显式发送，限制波动与费用 |
+| `guidance_scale` | number | 否 | `2.5`；`0..20` | 不展示、不发送 |
+| `num_inference_steps` | integer | 否 | `40`；`4..50` | 不展示、不发送 |
+| `acceleration` | enum | 否 | `regular`；`none` / `regular` | 不展示、不发送 |
+| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不发送 |
+| `num_images` | integer | 否 | `1`；`1..4` | 首版一个目标角度对应一张，固定 1，不展示、不发送 |
+| `lora_scale` | number | 否 | `1`；`0..2` | 不展示、不发送 |
+| `seed` | integer/null | 否 | 随机 | 不展示、不发送 |
+| `sync_mode` | boolean | 否 | `false` | 不展示、不发送 |
+| `output_format` | enum | 否 | `png`；`png` / `jpeg` / `webp` | 按项目约定不展示、不发送 |
+
+`image_size` 可以是 `{width, height}`（宽高为正整数，单边最大 `14142`，子字段默认 `512`），或以下枚举：
+
+`square_hd` / `square` / `portrait_4_3` / `portrait_16_9` / `landscape_4_3` / `landscape_16_9`。
+
+## 4. 请求与响应示例
+
+```json
+{
+  "image_urls": ["https://v3.fal.media/files/.../object.png"],
+  "horizontal_angle": 90,
+  "vertical_angle": 30,
+  "zoom": 5,
+  "image_size": "square_hd"
+}
+```
+
+```json
+{
+  "images": [
+    { "url": "https://v3b.fal.media/files/.../angle.png" }
+  ],
+  "prompt": "<server-generated prompt>"
+}
+```
+
+OpenAPI 把 `seed` 标为必填，但同一份官方 `llms.txt` 的字面响应示例缺少 `seed`。解析器只应把非空 `images[].url` 当作成功必要条件，`seed` / `prompt` 按可选元数据处理。
+
+## 5. 多角度组与计价
+
+- 每个目标角度使用一次独立 Fal 请求，选择顺序在请求前固定，不从结果文件名推断。
+- 实时 `llms.txt` 标价 `$0.021 / processed megapixel`。首版固定约 1MP 时，单角度静态预算约 `$0.021`；4 角度约 `$0.084`。
+- “processed megapixel”的精确取整和输入/输出基准未在 `llms.txt` 展开，最终以 pricing API / billing event 为准。
+- 多次独立生成不保证身份、文字、不可见结构或背景一致；批次失败和按失败项重试策略应与现有多角度工具保持一致。
+
+## 6. 待真实验证
+
+- 人物、商品、建筑在 `0/90/180/270/360°` 的方位遵从和回环误差。
+- `vertical_angle` 只有正值，是否无法表达仰拍。
+- `zoom` 是改变景别还是同时改变主体几何。
+- 官方未给输入数量、文件限制、延迟 SLA 和一致性承诺。
+
+## 7. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/flux-2-lora-gallery/multiple-angles | 否 | 2026-08-29 |
+| 实时字段、范围、示例与价格 | https://fal.ai/models/fal-ai/flux-2-lora-gallery/multiple-angles/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（完整尺寸枚举、范围、必填与响应） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/flux-2-lora-gallery/multiple-angles | 否 | 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/FLUX-3/FLUX-3_APIMart.md

@@ -0,0 +1,65 @@
+# FLUX 3 Image · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 项目模型 ID | `apimart-flux-3-image`（通用标识 `flux-3`，与 Fal 一致） |
+| 平台模型 ID | `flux-3-image`、`flux-3-image-klein` |
+| 接口形态 | 异步任务 |
+| 文档 / 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- 提交：`POST /v1/images/generations` → `data[0].task_id`
+- 查询：`GET /v1/tasks/{task_id}`，完成后读 `data.result.images[0].url[0]`，保留 72 小时
+
+## 2. 能力
+
+文生图、单图编辑、最多 10 张参考图的多图参考；提示词内可用标签 + bbox JSON（0–1000 归一化坐标）描述布局与局部编辑，不是独立参数，也没有蒙版。每次只出 1 张。Klein 是更小更快的开放权重版本。
+
+## 3. 请求参数
+
+| 字段 | `flux-3-image` | `flux-3-image-klein` |
+|---|---|---|
+| `model` | 必填 | 必填 |
+| `prompt` | 必填；不支持负面提示词 | 同左 |
+| `image_urls` | ≤ 10，公网 URL 或 Base64 | 同左 |
+| `aspect_ratio`（或 `size`） | `21:9` `2:1` `16:9` `3:2` `7:5` `4:3` `5:4` `1:1` `4:5` `3:4` `5:7` `2:3` `9:16` `1:2` `9:21` / `auto`；不接受像素值 | 同左 |
+| `resolution` | `768sq` / `1k` / `1.5k` / `2k` / `4k`，默认 `1k`，决定计费档 | 同左 |
+| `safety_tolerance` | 0–4，默认 2 | 同左 |
+| `grounding` | boolean，默认 true（生成前检索） | 不支持（传入 400） |
+| `seed` | 不支持 | 0–4294967295 |
+| `steps` | 不支持 | 1–16，默认 16，不影响价格 |
+| `output_format` | 不支持 | `jpeg` / `png` |
+| `n` | 只能 1 | 只能 1 |
+| 报 400 | `width` `height` 像素尺寸 `guidance` `negative_prompt` `prompt_upsampling` `mask_url` | |
+
+## 4. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) 图像区 `flux-3-image`、`flux-3-image-klein`（2026-11-07 读取，各 6 个价格档位，黄金价 = 当前价）；[FLUX 3 Image 模型页](https://apimart.ai/zh/model/flux-3-image)说明“价格由分辨率决定，参考图不另收费”。
+
+| 档位 | flux-3-image | flux-3-image-klein |
+|---|---|---|
+| 768SQ | $0.0328 | $0.0064 |
+| 1K（默认） | $0.0384 | $0.0072 |
+| 1.5K | $0.056 | $0.0088 |
+| 2K | $0.08 | $0.0112 |
+| 4K | $0.4856 | $0.0288 |
+
+## 5. 项目适配
+
+- 一个产品模型，`role: 'mode'` 版本（标准 / Klein），两个版本共用比例与分辨率参数。
+- 比例默认“智能”：按首图比例取最近支持比例，无图回退 `1:1`；始终发具体比例，不发 `auto`。
+- 不显示、不请求：`safety_tolerance`、`grounding`（用平台默认开启）、Klein 的 `seed` / `steps` / `output_format`。
+- 布局 / 局部编辑通过提示词语法表达，不提供额外参数。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| FLUX 3 Image API 文档 | https://docs.apimart.ai/cn/api-reference/images/flux-3-image/generation | 否 |
+| FLUX 3 Image Klein API 文档 | https://docs.apimart.ai/cn/api-reference/images/flux-3-image-klein/generation | 否 |
+| 模型页 | https://apimart.ai/zh/model/flux-3-image | 否 |
+| 定价中心（分档价格） | https://apimart.ai/zh/pricing | 否 |

package/docs/model-adaptation/FLUX-3/FLUX-3_Fal.md

@@ -0,0 +1,48 @@
+# FLUX 3 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 图片 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `blackforestlabs/flux-3/text-to-image`、`blackforestlabs/flux-3/edit-image` |
+| 痕迹AI 模型 ID | `fal-ai-flux-3`（canonical `flux-3`） |
+| 接口形态 | Fal 队列异步 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 请求参数（OpenAPI，2026-11-07 读取）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `prompt` | string | 是 | — | |
+| `resolution` | string | 否 | `1k` | `768sq` / `1k` / `1.5k` / `2k` / `4k`（模型页说明文字还列了 `512sq`，OpenAPI 枚举没有，以 OpenAPI 为准）；4k 可能要几分钟 |
+| `aspect_ratio` | string | 否 | `auto` | `auto` / `21:9` / `2:1` / `16:9` / `3:2` / `7:5` / `4:3` / `5:4` / `1:1` / `4:5` / `3:4` / `5:7` / `2:3` / `9:16` / `1:2`；编辑时 `auto` 跟随第一张参考图 |
+| `enable_prompt_expansion` | boolean | 否 | `false` | 扩写提示词并保留意图与参考角色 |
+| `image_urls` | array | 编辑必填 | — | 1–10 张，每边 ≥256px，超过 4MP 自动缩小；第一张决定 `auto` 比例 |
+| `safety_tolerance` | integer | 否 | `2` | 0–4；不展示、不下发 |
+| `output_format` | string | 否 | `jpeg` | 按产品约定不展示、不下发 |
+| `version` / `sync_mode` | | 否 | | 不展示、不下发 |
+
+响应：`{ "images": [{ "url", ... }] }`。
+
+## 2. 价格（模型页 pricingInfoOverride / publicEndpointBilling，2026-11-07 读取）
+
+- 计费单位为百万像素：**$0.048/MP**；模型页写明“一档一价”，并只给出 1K（1MP）= $0.048 一个示例。
+- 其余档位页面未列具体价格。痕迹AI 按档位边长的正方形像素数估算（768 ≈ 0.59MP、1.5K = 2.25MP、2K = 4MP、4K = 16MP），并标为估算价。
+
+## 3. 适配要点
+
+- 有图自动走 `edit-image`，无图走 `text-to-image`。
+- 智能比例：编辑时下发 `auto`（平台按第一张参考图），纯文生图回退 `1:1`。
+- FLUX 3 Klein（`blackforestlabs/flux-3/klein/*`，按尺寸逐档定价）不在本次范围。
+- FLUX 3 / FLUX 3 Max 视频端点已作为独立视频模型 `fal-flux-3-video` 接入，见 [FLUX-3-Video_Fal.md](../FLUX-3-Video/FLUX-3-Video_Fal.md)。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生图 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=blackforestlabs/flux-3/text-to-image | 否 |
+| 编辑 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=blackforestlabs/flux-3/edit-image | 否 |
+| 模型页与价格 | https://fal.ai/models/blackforestlabs/flux-3/text-to-image | 否 |
+| 编辑价格 | https://fal.ai/models/blackforestlabs/flux-3/edit-image | 否 |

package/docs/model-adaptation/FLUX-3-Klein/FLUX-3-Klein_KIE.md

@@ -0,0 +1,38 @@
+# FLUX 3 Klein · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 项目模型 | `kie-flux-3-klein`，通用标识 `flux-3-klein` |
+| model ID | `flux-3/klein-text-to-image`、`flux-3/klein-edit-image` |
+| 文档与价格 | 公开，无需登录 |
+| 定价（每张，文生图与编辑同价） | 1K $0.008、2K $0.0125、4K $0.0325 |
+
+KIE 当前只上架 FLUX 3 的 Klein 档；没有其他 FLUX 3 档位的文档或价格。
+
+## 请求契约
+
+`POST https://api.kie.ai/api/v1/jobs/createTask`，`{model,input}`；无图走文生图，有图自动走编辑。
+
+| input 字段 | 值与约束 | 项目处理 |
+|---|---|---|
+| prompt | 必填，≤5000 | 统一提示词 |
+| image_urls | 编辑必填，1–10 张，jpeg/png/webp，≤30MB | 上传素材 |
+| aspect_ratio | 文生图：1:1（默认）、4:3、3:4、3:2、2:3、16:9、9:16、21:9、9:21；编辑另有 auto（跟随首图） | 智能比例：编辑发 auto，文生图本地转具体值（无图 1:1） |
+| resolution | 1K（默认）、2K、4K | 展示 |
+| width / height | 256–4096 自定义尺寸，传入后忽略比例与分辨率 | 不显示、不请求 |
+| num_images | 1–4，默认 1 | 生成数量 |
+| enhance_prompt | 默认 true，生成前改写提示词 | 开关，默认开 |
+| output_format / seed / nsfw_checker | 可选 | 按产品约定不显示、不请求 |
+
+## 事件与失败契约
+
+沿用 [KIE 供应商文档](../供应商/KIE.md) 第 2 节 Market 统一任务契约。官方请求 schema 见 `tests/fixtures/model-requests-2026-11/kie-flux-3-klein-*.json`；未做付费真网验收。
+
+## 原始链接索引
+
+均公开，无需登录：
+- [Klein Text to Image](https://docs.kie.ai/market/flux3/klein-text-to-image.md)
+- [Klein Edit Image](https://docs.kie.ai/market/flux3/klein-edit-image.md)
+- [模型页](https://kie.ai/flux-3)
+- [实时价格页](https://kie.ai/pricing)（2026-11-07 核对 6 行 Flux 3 Klein 价格）

package/docs/model-adaptation/FLUX-3-Video/FLUX-3-Video_APIMart.md

@@ -0,0 +1,84 @@
+# FLUX 3 Video · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 项目模型 ID | `apimart-flux-3-video`（通用标识 `flux-3-video`，与 Fal 一致） |
+| 平台模型 ID | `flux-3-video` |
+| 接口形态 | 异步任务 |
+| 文档 / 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- 提交：`POST https://api.apimart.ai/v1/videos/generations`，`Authorization: Bearer <key>`。
+- 提交响应（官方示例）：`{"code":200,"data":[{"status":"submitted","task_id":"task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"}]}`。
+- 查询：`GET /v1/tasks/{task_id}`，官方建议每 5–10 秒一次、客户端超时 15 分钟（20 秒 fhd 更慢；实测 t2v+hd+5 秒约 60 秒出片）；成功后取 `result.videos[0].url`，`cost` 为最终扣费。失败全额退款，内容审核拒绝进入 `failed`。
+- 错误：400 参数无效、401、402、422 参数互斥或取值非法、429。
+
+## 2. 生成模式
+
+统一入口，按传参自动判定，也可用 `mode` 显式指定（显式优先级最高）：
+
+| 模式 | 触发 | 说明 |
+|---|---|---|
+| `t2v` | 只传 `prompt` | 文生视频 |
+| `i2v` | 传 `image_urls` | 1 张=起始帧；2 张=起止帧；3–10 张=首尾起止、中间均匀分布；顺序即语义，不排序去重 |
+| `v2v` | 传 `video_url` / `video_urls`（取第一个） | 视频续写，单价更高；同时有图和视频时按续写处理；实际时长可能短于请求，按实际退差额 |
+| `draft_enhance` | `draft:true` / `draft_from_task_id` | 草稿（约 1/3 价、仅 hd）→ 草稿转正片（仅可改 `resolution`，全价，与 `draft` 互斥） |
+
+草稿转正片（官方原文要点）：`draft_from_task_id` 指向**自己的**一条已成功的草稿任务 ID，使用草稿保存的原始参数（模式 / 提示词 / 种子 / 素材）全质量渲染；仅可改 `resolution`，提示词、时长、图片、视频一律不能改，传 `prompt` 会被拒绝；与 `draft:true` 互斥。官方示例：`{"model":"flux-3-video","draft_from_task_id":"task_01K_DRAFT...","resolution":"fhd"}`。按正片全价计费，草稿费用不抵扣；视频续写草稿转正片按续写正片单价。
+
+`mode` 还接受官方拼写 `text-to-video` / `image-continuation` / `video-continuation`。
+
+## 3. 请求参数
+
+| 字段 | 类型 / 取值 | 说明 |
+|---|---|---|
+| `model` | 固定 `flux-3-video` | |
+| `prompt` | 必填 | 草稿转正片时不能传 |
+| `duration` | 整数 5–20，默认 5 | 不支持 `auto`；不传/非整数按 5 秒；21 被拒 |
+| `resolution` | `hd`(默认，也接受 `720p`) / `fhd`（也接受 `1080p`） | 实测 hd 16:9 约 1280×704，fhd 约 1920×1088；草稿只能 hd |
+| `aspect_ratio` | `21:9` `2:1` `16:9` `4:3` `1:1` `3:4` `9:16` / `auto`(默认) | |
+| `image_urls` | string[]，1–10 | 公网 URL 或 base64 |
+| `video_url` / `video_urls` | mp4，公网 URL 或 base64 | 官方未写时长/大小上限 |
+| `audio` | boolean，默认 true | 关闭出无声视频，不降价 |
+| `draft` / `draft_from_task_id` | boolean / string | 见上；`draft:true` + `fhd` 报错（草稿只能 hd） |
+| `safety_tolerance` | 0–4，默认 2 | |
+| `nsfw_check` | boolean，默认 false | provider 强制 false |
+| `mode` | 见上 | |
+
+## 4. 价格
+
+来源：模型页价格表（2026-11-07 读取，“黄金价 = 当前价格”，较官方价省 20%）。定价中心只列起价 `$0.048/秒`（即草稿档）。
+
+| 规格 | 当前价（黄金） | 官方价 |
+|---|---|---|
+| DRAFT | $0.048/秒 | $0.06/秒 |
+| V2V-DRAFT | $0.096/秒 | $0.12/秒 |
+| **HD**（文/图生） | **$0.136/秒** | $0.17/秒 |
+| **FHD**（文/图生） | **$0.232/秒** | $0.29/秒 |
+| **V2V-HD**（续写） | **$0.328/秒** | $0.41/秒 |
+| **V2V-FHD**（续写） | **$0.424/秒** | $0.53/秒 |
+
+模型页 FAQ 的“原价（2026 年 10 月）”即上表官方价列；最终扣费以任务结果 `cost` 为准。
+
+## 5. 项目适配
+
+- 模式参数 `role: 'mode'`：文/图生视频（按是否有图在请求里显式发 `t2v` / `i2v`）与视频续写（`v2v`，必须 1 段视频、不带图）。显式发送 `mode`，避免平台在图视频同传时静默丢图。
+- 比例默认“智能”：只在纯文生视频显示；纯文生视频智能回退 `16:9`，有图或续写发 `auto` 交给平台跟随素材。
+- 计价：时长 × 档位单价（文/图生 hd/fhd，续写 v2v-hd/fhd）；草稿按 DRAFT / V2V-DRAFT 单价。
+- 草稿：开关参数 `apimartFlux3VideoDraft`（默认关），开启时请求发 `draft: true` 且 `resolution` 固定 `hd`；分辨率参数保留显示，表示转正片时的分辨率。
+- 草稿转正片：模型声明续接 `finalize-draft`（仅草稿结果可用），完成时从结果取平台 `task_id` 作为引用；续接参数只把草稿开关关掉、其余沿用草稿参数，直接提交。请求只发 `model` + `draft_from_task_id` + `resolution`，不发 `prompt`；计价按草稿参数的模式与时长 × 正片单价。任务 ID 只在请求构建里使用，不进入界面。
+- 不显示、不请求：`safety_tolerance`（平台默认 2）、`nsfw_check`（provider 强制 false）。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| API 文档（中文） | https://docs.apimart.ai/cn/api-reference/videos/flux-3-video/generation | 否 |
+| API 文档（英文） | https://docs.apimart.ai/en/api-reference/videos/flux-3-video/generation | 否 |
+| 任务查询 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 模型页（价格表、FAQ） | https://apimart.ai/zh/model/flux-3-video | 否 |
+| 定价中心（起价） | https://apimart.ai/zh/pricing | 否 |

package/docs/model-adaptation/FLUX-3-Video/FLUX-3-Video_Fal.md

@@ -0,0 +1,80 @@
+# FLUX 3 Video · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 视频 |
+| 供应商 | Fal |
+| 项目模型 ID | `fal-flux-3-video`（通用标识 `flux-3-video`，与 APIMart 一致） |
+| 平台端点 | 标准版 `blackforestlabs/flux-3/{text-to-video,image-to-video,extend-video,edit-video}`；Max `blackforestlabs/flux-3-max/{text-to-video,image-to-video}`；草稿 `blackforestlabs/flux-3/{text-to-video,image-to-video,extend-video}/draft`、`blackforestlabs/flux-3/draft-enhance` |
+| 接口形态 | Fal 队列（提交 → status → result） |
+| 文档 / 价格可见性 | 公开，无需登录（各端点 `llms.txt` 同时含 schema 与价格） |
+
+## 1. 端点探测
+
+按《文档采集手册》对 `https://fal.ai/models/<endpoint>/llms.txt` 探测（2026-11-07）：
+
+- 200：上表全部端点。
+- 404：`flux-3/video-to-video`、`flux-3/video-continuation`、`flux-3/reference-to-video`、`flux-3-max/{video-to-video,extend-video,reference-to-video}`、`flux-3-max/text-to-video/draft`、`flux-3-max/extend-video/draft`、`flux-3/enhance*`。
+- FLUX 3 Max 页面说明它是“fal 对 FLUX 3 Video 的后训练变体，提示词遵循与画质更好、延迟更低”。
+
+## 2. 各端点字段
+
+结果统一为 `video: File`（`video.url`），另有 `seed`；Max 额外 `timings`；草稿端点额外 `draft_cache: File | null`（OpenAPI：加密的持久缓存包，传给 `draft-enhance` 做全质量渲染；合作方没返回缓存包时为空）。`draft-enhance` 输入只有 `draft_cache_url`（必填，URL 或 data URI）与 `safety_tolerance`，输出只有 `video: File`，沿用草稿的种子与运动、不重新规划。
+
+| 字段 | t2v / i2v | extend-video | edit-video | Max t2v / i2v | 草稿 t2v/i2v/extend |
+|---|---|---|---|---|---|
+| `prompt` | 必填 | 必填 | 必填 | 必填 | 必填 |
+| `image_url` | i2v 必填（单张首帧，PNG/JPEG/WebP） | — | — | i2v 必填 | i2v 必填（URL 或 data URI） |
+| `end_image_url` | — | — | — | i2v 可选（尾帧） | — |
+| `video_url` | — | 必填，MP4 < 50MB、< 15 秒 | 必填，MP4 < 50MB、< 15 秒 | — | extend 必填，≤ 50 MiB |
+| `aspect_ratio` | `auto`(默认) `21:9` `2:1` `16:9` `4:3` `1:1` `3:4` `9:16` | 同左 | — | 同左（`auto`：文生 16:9、图生跟随首图） | 同左 |
+| `resolution` | `720p`(默认) `1080p` `1440p` `2160p` | 同左 | — | `720p`(默认) `1080p` `2K` `4K` | — |
+| `duration` | `auto`(默认) / 5–20 | 同左 | — | 5–20，默认 5 | `auto` / 5–20 |
+| `generate_audio` | 默认 true | 默认 true | — | 默认 true | 默认 true |
+| `safety_tolerance` | 0–4，默认 2 | 同左 | 同左 | — | 同左 |
+| `reasoning_level` | — | — | — | `low` / `high`(默认)，越高越慢 | — |
+| `seed` | — | — | — | 可选 | — |
+| `draft_cache_url` | — | — | — | — | 仅 `draft-enhance` 必填 |
+
+`edit-video` 按提示词重绘输入视频，保留运动、节奏与构图。
+
+## 3. 价格（2026-11-07 各端点 llms.txt）
+
+| 端点 | 单价 |
+|---|---|
+| 标准 t2v / i2v | 720p $0.17/秒、1080p $0.29/秒、2K(1440p) $0.32/秒、4K(2160p) $0.47/秒 |
+| extend-video | 720p $0.41/秒、1080p $0.53/秒（2K/4K 未公布价格） |
+| edit-video | $0.03/秒（720p，按生成视频秒数） |
+| Max t2v / i2v | 标准价 720p $0.17/秒、1080p $0.29/秒；2026-11-07 前 75% 折扣（$0.0425/$0.0725），11-08 至 11-22 五折（$0.085/$0.145），11-23 起恢复标准价；2K/4K 未公布价格 |
+| 草稿 t2v / i2v | $0.06/秒（720p） |
+| 草稿 extend | $0.12/秒（720p） |
+| draft-enhance | $0.29/秒（1080p 全质量） |
+
+## 4. 项目适配
+
+- 一个产品模型：版本（标准 / Max）与模式（文/图生视频、视频续写、视频编辑）都 `role: 'mode'`；Max 只有文/图生视频，选 Max 时隐藏模式。
+- 文/图生视频按是否有图自动切 `text-to-video` / `image-to-video`；标准版图生只用 1 张首帧，Max 第 2 张图映射 `end_image_url`（因此打 `start-end-frame`）。
+- 比例只在纯文生视频显示，智能回退 `16:9`；有首帧发 `auto` 跟随图片。
+- 分辨率：标准 t2v/i2v 四档；续写与 Max 只开放 720p/1080p（其他档位没有公布价格，展示联动裁剪并重置，builder 回退 720p）。编辑不发分辨率、时长、音频。
+- 时长固定 5–20 整数，默认 5，不发 `auto`（按秒计费需要确定秒数）。
+- 计价：时长 × 档位单价；编辑按输入视频时长 × $0.03（读不到时长按上限 15 秒估）；Max 按 11-23 起的标准价预估，标为估算价。
+- 草稿：开关参数 `falFlux3VideoDraft`（默认关），只在标准版文/图生视频与续写显示（Max 与视频编辑没有草稿端点）；开启时路由到对应 `/draft` 端点，不发 `resolution`（草稿固定 720p），分辨率参数隐藏；计价 $0.06/秒、续写草稿 $0.12/秒。
+- 草稿转正片：模型声明续接 `finalize-draft`（仅草稿结果可用），完成时从结果 metadata 的 `draft_cache.url` 取缓存地址作为引用（为空则不能转正片）；续接参数关掉草稿、分辨率记为 1080p，直接提交。请求走 `blackforestlabs/flux-3/draft-enhance`，只发 `draft_cache_url`；计价 $0.29/秒 × 草稿时长。缓存地址只在请求构建里使用，不进入界面。
+- 结果解析：Fal provider 收集媒体地址时跳过 `draft_cache`，避免缓存包被当成第二段视频；它仍原样保留在 metadata 中。
+- 不显示、不请求：`safety_tolerance`（平台默认 2）、Max 的 `seed`。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema 与价格 | https://fal.ai/models/blackforestlabs/flux-3/text-to-video/llms.txt | 否 |
+| 图生视频 schema 与价格 | https://fal.ai/models/blackforestlabs/flux-3/image-to-video/llms.txt | 否 |
+| 视频续写 schema 与价格 | https://fal.ai/models/blackforestlabs/flux-3/extend-video/llms.txt | 否 |
+| 视频编辑 schema 与价格 | https://fal.ai/models/blackforestlabs/flux-3/edit-video/llms.txt | 否 |
+| Max 文生视频 | https://fal.ai/models/blackforestlabs/flux-3-max/text-to-video/llms.txt | 否 |
+| Max 图生视频 | https://fal.ai/models/blackforestlabs/flux-3-max/image-to-video/llms.txt | 否 |
+| 草稿文生 / 图生 / 续写 | https://fal.ai/models/blackforestlabs/flux-3/text-to-video/draft/llms.txt 、 …/image-to-video/draft/llms.txt 、 …/extend-video/draft/llms.txt | 否 |
+| 草稿增强 | https://fal.ai/models/blackforestlabs/flux-3/draft-enhance/llms.txt | 否 |
+| OpenAPI（草稿与草稿增强，含 `draft_cache` 输出结构） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=blackforestlabs/flux-3/text-to-video/draft 、 …?endpoint_id=blackforestlabs/flux-3/draft-enhance | 否 |
+| OpenAPI（各端点） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=blackforestlabs/flux-3/text-to-video | 否 |

package/docs/model-adaptation/Finegrain-Eraser/Finegrain-Eraser_Fal.md

@@ -1,31 +1,31 @@
-# Finegrain Eraser (Mask) · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-28 |
-| SDK 模型 ID | `fal-finegrain-eraser`（可选工具模型，不进入默认 105 目录） |
-| Fal endpoint ID | `fal-ai/finegrain-eraser/mask` |
-| API 文档 | https://fal.ai/models/fal-ai/finegrain-eraser/mask/api |
-| 价格 | Express $0.04 / Standard $0.13 / Premium $0.22 |
-| 登录 | 文档与模型页无需登录；调用需要 Fal Key |
-
-## 协议与字段
-
-使用 Fal 队列公共协议，认证、提交、状态与结果读取同 [Fal 供应商文档](../供应商/Fal.md)。
-输出位于 `image.url`。
-
-| 字段 | 约束 | SDK 策略 |
-|---|---|---|
-| `image_url` | 必填，待处理原图 | `image-upload`，Fal CDN 自动上传 |
-| `mask_url` | 必填；白色区域擦除 | `image-upload`，Fal CDN 自动上传 |
-| `mode` | `express` / `standard` / `premium`，默认 `standard` | 保留为唯一可选参数 |
-| `seed` | 可选 | 项目约定隐藏且不请求 |
-
-Fal 另有 prompt/box 端点；本次严格适配 Photoshop 已启用的 mask 工具，不顺手扩张范围。
-统一画像从本模型 schema 派生为 `operation=image-edit`、`feature=erase`，执行仍走统一 Fal 生成内核。
-
-## 原始链接索引
-
-- https://fal.ai/models/fal-ai/finegrain-eraser/mask/api — mask endpoint、字段、结果与队列示例。
-- https://fal.ai/models/fal-ai/finegrain-eraser/mask — 当前三档价格。
-- https://fal.ai/docs/documentation/model-apis/inference/queue — Fal 队列公共协议。
+# Finegrain Eraser (Mask) · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| SDK 模型 ID | `fal-finegrain-eraser`（可选工具模型，不进入默认 105 目录） |
+| Fal endpoint ID | `fal-ai/finegrain-eraser/mask` |
+| API 文档 | https://fal.ai/models/fal-ai/finegrain-eraser/mask/api |
+| 价格 | Express $0.04 / Standard $0.13 / Premium $0.22 |
+| 登录 | 文档与模型页无需登录；调用需要 Fal Key |
+
+## 协议与字段
+
+使用 Fal 队列公共协议，认证、提交、状态与结果读取同 [Fal 供应商文档](../供应商/Fal.md)。
+输出位于 `image.url`。
+
+| 字段 | 约束 | SDK 策略 |
+|---|---|---|
+| `image_url` | 必填，待处理原图 | `image-upload`，Fal CDN 自动上传 |
+| `mask_url` | 必填；白色区域擦除 | `image-upload`，Fal CDN 自动上传 |
+| `mode` | `express` / `standard` / `premium`，默认 `standard` | 保留为唯一可选参数 |
+| `seed` | 可选 | 项目约定隐藏且不请求 |
+
+Fal 另有 prompt/box 端点；本次严格适配 Photoshop 已启用的 mask 工具，不顺手扩张范围。
+统一画像从本模型 schema 派生为 `operation=image-edit`、`feature=erase`，执行仍走统一 Fal 生成内核。
+
+## 原始链接索引
+
+- https://fal.ai/models/fal-ai/finegrain-eraser/mask/api — mask endpoint、字段、结果与队列示例。
+- https://fal.ai/models/fal-ai/finegrain-eraser/mask — 当前三档价格。
+- https://fal.ai/docs/documentation/model-apis/inference/queue — Fal 队列公共协议。