@henjicc/ai-sdk 0.2.8 → 0.3.0

package/docs/model-adaptation/IC-Light-v2/IC-Light-v2_Fal.md

@@ -1,96 +1,99 @@
-# IC-Light v2 · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-29 |
-| 模态 | 图片编辑 / 重打光 |
-| 供应商 | fal.ai（聚合平台） |
-| 平台模型 ID | `fal-ai/iclight-v2` |
-| 接口形态 | 队列异步（推荐）或同步直连 |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-## 1. 能力与边界
-
-IC-Light v2 接收一张源图，通过文字描述和离散的初始光照偏好重新生成光照。Fal 模型页标注可商用；Fal 托管端点不要求本项目部署开源权重。产品首版只把 `initial_latent` 的五个官方值作为离散方向偏好，亮度、色调和轮廓光均由版本化提示词表达，不能宣称为物理精确控制。
-
-上游 IC-Light 仓库采用 Apache-2.0；仓库同时说明本地示例使用的 BRIA RMBG 1.4 权重具有非商用限制。该限制影响自行部署相应去背景权重的方案，不等同于 Fal 托管端点的产品许可。若未来改为自部署，必须重新完成权重来源与商用许可审查。
-
-## 2. 接入协议
-
-- 鉴权：`Authorization: Key $FAL_KEY`
-- 同步：`POST https://fal.run/fal-ai/iclight-v2`
-- 队列：`POST https://queue.fal.run/fal-ai/iclight-v2`，随后按 Fal 通用队列协议查询状态与结果
-- 成功结果：`images[]`，本项目继续复用 Fal 现有图片结果解析、轮询、取消与上传链路
-
-## 3. 输入参数
-
-| 字段 | 类型 | 必填 | 默认 | 首版策略 |
-|---|---|---|---|---|
-| `prompt` | string | 是 | — | 由手动模式提示词编译器生成 |
-| `image_url` | string | 是 | — | 恰好一张源图，由现有 Fal 上传链路提供 |
-| `initial_latent` | enum | 否 | `None` | 仅 `None` / `Left` / `Right` / `Top` / `Bottom` |
-| `image_size` | enum/object | 否 | `square_hd` | 首版按源图比例选择最近常见比例并固定约 1MP |
-| `num_images` | integer | 否 | `1` | 固定 `1` |
-| `num_inference_steps` | integer | 否 | `28` | 固定 `28` |
-| `cfg_scale` | number | 否 | `1` | 固定 `1` |
-| `guidance_scale` | number | 否 | `5` | 固定 `5` |
-| `lowres_denoise` | number | 否 | `0.98` | 固定 `0.98` |
-| `highres_denoise` | number | 否 | `0.95` | 固定 `0.95` |
-| `highres_scale` | number | 否 | `0.5` | 固定 `0.5` |
-| `enable_hr_fix` | boolean | 否 | `false` | 固定 `false`，首版避免额外成本与时延 |
-| `enable_safety_checker` | boolean | 否 | `true` | 固定 `true` |
-| `mask_url` | string | 否 | — | 首版不开放 |
-| `negative_prompt` | string | 否 | — | 不展示、不发送 |
-| `seed` | integer | 否 | — | 不展示、不发送 |
-| `output_format` | enum | 否 | `png` | 不展示、不发送，沿用供应商默认 |
-
-## 4. 请求示例
-
-```json
-{
-  "prompt": "Preserve the subject and composition. Apply a soft warm key light from the left.",
-  "image_url": "https://.../source.png",
-  "initial_latent": "Left",
-  "image_size": { "width": 1376, "height": 768 },
-  "num_images": 1,
-  "num_inference_steps": 28,
-  "cfg_scale": 1,
-  "guidance_scale": 5,
-  "lowres_denoise": 0.98,
-  "highres_denoise": 0.95,
-  "highres_scale": 0.5,
-  "enable_hr_fix": false,
-  "enable_safety_checker": true
-}
-```
-
-## 5. 响应与计价
-
-```json
-{
-  "images": [
-    { "url": "https://...", "width": 1376, "height": 768, "content_type": "image/png" }
-  ]
-}
-```
-
-Fal 模型页公开价格为 **$0.10/百万像素**。首版固定约 1MP、单张输出，目录保守估算为 **$0.10/次**。实际账单仍以 Fal 返回和账户账单为准，登录后的额度、地区可用性与最终账单尚待真实验证。
-
+# IC-Light v2 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-09-10 |
+| 模态 | 图片编辑 / 重打光 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `fal-ai/iclight-v2` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 能力与边界
+
+IC-Light v2 接收一张源图，通过文字描述和离散的初始光照偏好重新生成光照。Fal 模型页标注可商用；Fal 托管端点不要求本项目部署开源权重。产品首版只把 `initial_latent` 的五个官方值作为离散方向偏好，亮度、色调和轮廓光均由版本化提示词表达，不能宣称为物理精确控制。
+
+上游 IC-Light 仓库采用 Apache-2.0；仓库同时说明本地示例使用的 BRIA RMBG 1.4 权重具有非商用限制。该限制影响自行部署相应去背景权重的方案，不等同于 Fal 托管端点的产品许可。若未来改为自部署，必须重新完成权重来源与商用许可审查。
+
+## 2. 接入协议
+
+- 鉴权：`Authorization: Key $FAL_KEY`
+- 同步：`POST https://fal.run/fal-ai/iclight-v2`
+- 队列：`POST https://queue.fal.run/fal-ai/iclight-v2`，随后按 Fal 通用队列协议查询状态与结果
+- 成功结果：`images[]`，本项目继续复用 Fal 现有图片结果解析、轮询、取消与上传链路
+
+## 3. 输入参数
+
+| 字段 | 类型 | 必填 | 默认 | 首版策略 |
+|---|---|---|---|---|
+| `prompt` | string | 是 | — | 由手动模式提示词编译器生成 |
+| `image_url` | string | 是 | — | 恰好一张源图，由现有 Fal 上传链路提供 |
+| `initial_latent` | enum | 否 | `None` | 仅 `None` / `Left` / `Right` / `Top` / `Bottom` |
+| `image_size` | enum/object | 否 | — | 按源图实际比例计算约 1MP 自定义整数宽高，不吸附到预设比例；两边均为 1–14142 |
+| `num_images` | integer | 否 | `1` | 固定 `1` |
+| `num_inference_steps` | integer | 否 | `28` | 固定 `28` |
+| `cfg` | number | 否 | `1` | 固定 `1`，范围 0.01–5；旧文档的 `cfg_scale` 不属于官方字段 |
+| `guidance_scale` | number | 否 | `5` | 固定 `5` |
+| `lowres_denoise` | number | 否 | `0.98` | 固定 `0.98` |
+| `highres_denoise` | number | 否 | `0.95` | 固定 `0.95` |
+| `hr_downscale` | number | 否 | `0.5` | 固定 `0.5`，范围 0.01–1；旧文档的 `highres_scale` 不属于官方字段 |
+| `enable_hr_fix` | boolean | 否 | `false` | 固定 `false`，首版避免额外成本与时延 |
+| `enable_safety_checker` | boolean | 否 | `true` | 固定 `true` |
+| `mask_image_url` | string | 否 | — | 首版不开放 |
+| `negative_prompt` | string | 否 | — | 不展示、不发送 |
+| `seed` | integer | 否 | — | 不展示、不发送 |
+| `output_format` | enum | 否 | `jpeg` | 不展示、不发送，沿用供应商默认 |
+
+## 4. 请求示例
+
+```json
+{
+  "prompt": "Preserve the subject and composition. Apply a soft warm key light from the left.",
+  "image_url": "https://.../source.png",
+  "initial_latent": "Left",
+  "image_size": { "width": 1365, "height": 768 },
+  "num_images": 1,
+  "num_inference_steps": 28,
+  "cfg": 1,
+  "guidance_scale": 5,
+  "lowres_denoise": 0.98,
+  "highres_denoise": 0.95,
+  "hr_downscale": 0.5,
+  "enable_hr_fix": false,
+  "enable_safety_checker": true
+}
+```
+
+## 5. 响应与计价
+
+```json
+{
+  "images": [
+    { "url": "https://...", "width": 1365, "height": 768, "content_type": "image/jpeg" }
+  ]
+}
+```
+
+Fal 模型页公开价格为 **$0.10/百万像素**。首版固定约 1MP、单张输出，目录保守估算为 **$0.10/次**。实际账单仍以 Fal 返回和账户账单为准，登录后的额度、地区可用性与最终账单尚待真实验证。
+
 ## 6. 错误与降级
 
-- 缺少源图或源图超过一张：在请求构建前失败，不提交任务。
-- Fal 凭据、端点或余额不可用：显示明确失败，不自动切换模型。
-- 手动模式不能静默降级到 GPT Image 2；智能模式也不能静默切到 IC-Light。
-- 模型质量、主体保持、时延和真实成本尚未执行付费验证，不影响静态契约完成。
-
-## 7. 一手来源
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Fal 模型页、商用标识与价格 | https://fal.ai/models/fal-ai/iclight-v2 | 否 |
-| Fal schema | https://fal.ai/models/fal-ai/iclight-v2/llms.txt | 否 |
-| Fal OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/iclight-v2 | 否 |
-| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
-| IC-Light 官方仓库与许可证 | https://github.com/lllyasviel/IC-Light | 否 |
-| Fal API Key | https://fal.ai/dashboard/keys | 是 |
+- 2026-09-10 重核官方 OpenAPI：自定义宽高合法，不存在只能选择五种比例的限制。旧代码把约 2:3 原图选成约 3:4 输出，属于本地请求尺寸策略错误；改为直接使用源图比例，仅有整数像素舍入误差。上传原图和下载结果不作非等比拉伸，也不为预设比例额外裁切。Fal 内部如何变换图像未在公开 schema 中说明，不能把输出人物变化全部归因于本地缩放。
+- 亮度、色调和轮廓光只有提示词意图，没有对应数值 API 字段；颜色传达正确不代表生成结果能精确还原预览。手动提示词将主光颜色放在开头，并明确彩色光照射主体，仍需真实生成评估效果。
+
+- 缺少源图或源图超过一张：在请求构建前失败，不提交任务。
+- Fal 凭据、端点或余额不可用：显示明确失败，不自动切换模型。
+- 手动模式不能静默降级到 GPT Image 2；智能模式也不能静默切到 IC-Light。
+- 模型质量、主体保持、时延和真实成本尚未执行付费验证，不影响静态契约完成。
+
+## 7. 一手来源
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Fal 模型页、商用标识与价格 | https://fal.ai/models/fal-ai/iclight-v2 | 否 |
+| Fal schema | https://fal.ai/models/fal-ai/iclight-v2/llms.txt | 否 |
+| Fal OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/iclight-v2 | 否 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| IC-Light 官方仓库与许可证 | https://github.com/lllyasviel/IC-Light | 否 |
+| Fal API Key | https://fal.ai/dashboard/keys | 是 |

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

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

@@ -1,72 +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 |
+# 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

@@ -1,93 +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 |
+# 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 |