@henjicc/ai-sdk 0.9.0 → 0.10.0

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 |

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

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

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