@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/model-adaptation/HappyHorse-1.1/HappyHorse-1.1_APIMart.md

@@ -0,0 +1,66 @@
+# HappyHorse 1.1 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 项目模型 ID | `apimart-happyhorse-1.1`（通用标识 `happyhorse-1.1`，与 `kie-happyhorse-1.1` 相同） |
+| 平台模型 ID | `happyhorse-1.1`（阿里云百炼 HappyHorse 1.1） |
+| 接口形态 | 异步任务 |
+| 文档 / 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- 提交：`POST /v1/videos/generations` → `data[0].task_id`
+- 查询：`GET /v1/tasks/{task_id}`，完成后读 `data.result.videos[0].url[0]`
+
+## 2. 能力（统一入口，按字段自动路由）
+
+| 传入字段 | 模式 |
+|---|---|
+| 仅 `prompt` | 文生视频 |
+| `prompt` + `first_frame_image` | 图生视频（以图为首帧） |
+| `prompt` + `image_urls`（1–9 张） | 参考图生视频（生成全新画面） |
+
+路由优先级 `first_frame_image` > `image_urls` > 仅 `prompt`；两个媒体字段互斥，同传返回 400 `mixed_media_not_allowed`。
+
+## 3. 请求参数
+
+| 字段 | 取值 | 说明 |
+|---|---|---|
+| `model` | `happyhorse-1.1` | 必填 |
+| `prompt` | ≤ 2500 字符 | |
+| `first_frame_image` | URL 或 base64 | JPEG/JPG/PNG/BMP/WEBP，短边 ≥ 300px，宽高比 1:2.5–2.5:1，≤ 10MB |
+| `image_urls` | 1–9 张，URL 或 base64 | 短边推荐 ≥ 720p，短边/长边 ≥ 0.4，≤ 10MB |
+| `resolution` | `720P` / `1080P` | 默认 `1080P` |
+| `duration` | 3–15 任意整数 | 默认 5 |
+| `size` | `16:9` / `9:16` / `1:1` / `4:3` / `3:4` | 默认 16:9；图生视频忽略 |
+| `watermark` / `seed` | | 项目不显示、不请求 |
+| `nsfw_check` | 默认 false | 项目固定 false |
+
+## 4. 价格
+
+来源：[HappyHorse 1.1 模型页](https://apimart.ai/zh/model/happyhorse-1-1)（2026-11-07 读取，黄金价 = 当前价）；定价中心起步价 `happyhorse-1.1 $0.13/秒` 一致。
+
+| 分辨率 | 单价 |
+|---|---|
+| 720P | $0.13 / 秒 |
+| 1080P | $0.172 / 秒 |
+
+所有模式只按分辨率 × 秒数计费（API 文档）。
+
+## 5. 项目适配
+
+- 素材尺寸前置校验（2026-11-08）：`imageConstraints` 首帧短边 ≥ 300 px、宽高比 0.4–2.5；参考图只校验宽高比 0.4–2.5（短边 ≥ 720 px 是推荐值，不拦）。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+- 与 `kie-happyhorse-1.1` 同结构：`role: 'mode'` 模式（文/图生视频、参考图生视频）。文/图生视频 0 张文生、1 张首帧；参考模式 1–9 张。
+- 比例默认“智能”：有图按首图比例、无图回退 16:9；图生视频隐藏比例且不发送 `size`。
+- 不显示、不请求：`watermark`、`seed`。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| API 文档 | https://docs.apimart.ai/cn/api-reference/videos/happyhorse-1.1/generation | 否 |
+| 模型页（价格） | https://apimart.ai/zh/model/happyhorse-1-1 | 否 |
+| 定价中心（起步价） | https://apimart.ai/zh/pricing | 否 |

package/docs/model-adaptation/HappyHorse-1.1/HappyHorse-1.1_KIE.md

@@ -1,27 +1,31 @@
-# HappyHorse 1.1 · KIE
-
-核对日期：2026-09-24；公开页面，无需登录；未执行付费生成。
-
-官方接口：[文生视频](https://docs.kie.ai/38309290e0.md)、[图生视频](https://docs.kie.ai/38308980e0.md)、[参考图视频](https://docs.kie.ai/38309489e0.md)。价格来自 [官方模型页](https://kie.ai/happyhorse-1-1) 的三个模式页：均为 720p 22.5 credits/s（$0.1125/s）、1080p 29 credits/s（$0.145/s），不计充值赠送。
-
-统一使用 `POST https://api.kie.ai/api/v1/jobs/createTask`，Bearer 认证；`model` 分别是 `happyhorse-1-1/text-to-video`、`image-to-video`、`reference-to-video`。共享任务查询 `GET /api/v1/jobs/recordInfo?taskId=...`，不用回调接收服务。
-
-| 模式 | input 必填与约束 | 禁止混入的字段 |
-|---|---|---|
-| 文生 | prompt；resolution 720p/1080p，duration 整数 3–15 默认 5；aspect_ratio 默认 16:9 | image_urls、reference_image |
-| 图生 | image_urls 数组，恰好 1 张；prompt 可省略；resolution、duration 同上 | aspect_ratio、reference_image |
-| 参考 | reference_image 1–9 张，prompt；resolution、duration、aspect_ratio 同文生 | image_urls |
-
-比例：16:9、9:16、1:1、4:3、3:4、4:5、5:4、9:21、21:9。参考图顺序对应提示词 `[Image 1]` 等编号。图生图像为 JPG/PNG/WEBP、≤20 MB、宽高均≥300、比例 0.4–2.5；参考图最短边≥400、≤20 MB。文件经官方 KIE 上传入口回填，界面不提供 URL 输入框。
-
-文生 prompt 的 schema `maxLength=4999` 与说明 5000 有冲突，SDK 采用较严格 4999；图生/参考上限 5000，超限报错，不截断。中文长度建议≤2500；素材像素/内容最终由服务端校验。界面一个模型、标准/参考两个模式，标准按是否有图片选择文生或图生。
-
-| 事件/响应 | 类型与可空性 | 行为 |
-|---|---|---|
-| 创建成功 | code:number=200，data.taskId:string | 返回 pending；缺 ID 且无产物拒绝 |
-| 查询等待 | data.state:string=waiting/queuing/generating | 有界轮询，不重复创建 |
-| 查询成功 | state=success，resultJson:string 内含 resultUrls:string[]；failCode/failMsg 可为 null | 返回产物；缺 URL 报错 |
-| 查询失败 | state=fail，failCode/failMsg:string；resultJson 可空或省略 | 失败终止 |
-| 查询错误、超时、取消 | 非 200 / 超预算 / AbortSignal | 沿共享 KIE/polling 收口，不误判成功、不付费重放 |
-
-字面请求、创建响应及成功/失败回调示例保存在 `tests/fixtures/kie/happyhorse-1.1-*.json`；回调只作为结果字段样本，不代表 SDK 接收回调。正常请求、边界、价格与共享轮询负例由目录测试和既有 provider/polling 测试验证。
+# HappyHorse 1.1 · KIE
+
+核对日期：2026-09-24；公开页面，无需登录；未执行付费生成。
+
+官方接口：[文生视频](https://docs.kie.ai/38309290e0.md)、[图生视频](https://docs.kie.ai/38308980e0.md)、[参考图视频](https://docs.kie.ai/38309489e0.md)。价格来自 [官方模型页](https://kie.ai/happyhorse-1-1) 的三个模式页：均为 720p 22.5 credits/s（$0.1125/s）、1080p 29 credits/s（$0.145/s），不计充值赠送。
+
+统一使用 `POST https://api.kie.ai/api/v1/jobs/createTask`，Bearer 认证；`model` 分别是 `happyhorse-1-1/text-to-video`、`image-to-video`、`reference-to-video`。共享任务查询 `GET /api/v1/jobs/recordInfo?taskId=...`，不用回调接收服务。
+
+| 模式 | input 必填与约束 | 禁止混入的字段 |
+|---|---|---|
+| 文生 | prompt；resolution 720p/1080p，duration 整数 3–15 默认 5；aspect_ratio 默认 16:9 | image_urls、reference_image |
+| 图生 | image_urls 数组，恰好 1 张；prompt 可省略；resolution、duration 同上 | aspect_ratio、reference_image |
+| 参考 | reference_image 1–9 张，prompt；resolution、duration、aspect_ratio 同文生 | image_urls |
+
+比例：16:9、9:16、1:1、4:3、3:4、4:5、5:4、9:21、21:9。参考图顺序对应提示词 `[Image 1]` 等编号。图生图像为 JPG/PNG/WEBP、≤20 MB、宽高均≥300、比例 0.4–2.5；参考图最短边≥400、≤20 MB。文件经官方 KIE 上传入口回填，界面不提供 URL 输入框。
+
+文生 prompt 的 schema `maxLength=4999` 与说明 5000 有冲突，SDK 采用较严格 4999；图生/参考上限 5000，超限报错，不截断。中文长度建议≤2500；素材像素/内容最终由服务端校验。界面一个模型、标准/参考两个模式，标准按是否有图片选择文生或图生。
+
+| 事件/响应 | 类型与可空性 | 行为 |
+|---|---|---|
+| 创建成功 | code:number=200，data.taskId:string | 返回 pending；缺 ID 且无产物拒绝 |
+| 查询等待 | data.state:string=waiting/queuing/generating | 有界轮询，不重复创建 |
+| 查询成功 | state=success，resultJson:string 内含 resultUrls:string[]；failCode/failMsg 可为 null | 返回产物；缺 URL 报错 |
+| 查询失败 | state=fail，failCode/failMsg:string；resultJson 可空或省略 | 失败终止 |
+| 查询错误、超时、取消 | 非 200 / 超预算 / AbortSignal | 沿共享 KIE/polling 收口，不误判成功、不付费重放 |
+
+字面请求、创建响应及成功/失败回调示例保存在 `tests/fixtures/kie/happyhorse-1.1-*.json`；回调只作为结果字段样本，不代表 SDK 接收回调。正常请求、边界、价格与共享轮询负例由目录测试和既有 provider/polling 测试验证。
+
+## 项目适配
+
+- 素材尺寸前置校验（2026-11-08）：`imageConstraints` 图生首帧宽高 ≥ 300 px、比例 0.4–2.5；参考图最短边 ≥ 400 px。提交前读取素材实际宽高，不合格直接提示，不发付费请求。

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

@@ -1,99 +1,99 @@
-# 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. 错误与降级
-
-- 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 | 是 |
+# 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. 错误与降级
+
+- 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 |