@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/llm-adaptation//346/226/207/346/241/243/351/207/207/351/233/206/346/211/213/345/206/214.md

@@ -1,88 +1,88 @@
-# 文档采集手册（LLM 供应商）
-
-> 这份手册只记 LLM 供应商调研中**做过一遍才知道**的东西，是 [docs/model-adaptation/文档采集手册.md](../model-adaptation/文档采集手册.md) 方法论在 LLM 场景下的落地版本；通用方法（`.md` 后缀技巧、SPA 找内容 API、交叉校验）不重复抄写，只记这里特有的坑。
-> 最后更新：2026-08-26（基于 7 家 LLM 供应商的实际采集）
-
-## 一、大多数 LLM 文档站是 Mintlify，`.md` 后缀直接返回原文
-
-`platform.kimi.com`、`docs.bigmodel.cn`、`platform.minimaxi.com`、`api-docs.deepseek.com`（部分页面）在 URL 末尾加 `.md` 都能拿到干净的 Markdown 原文，且首行会自带一条 `llms.txt` 全量索引提示：
-
-```bash
-curl -sL "https://platform.kimi.com/docs/guide/kimi-k3-quickstart.md"
-curl -sL "https://docs.bigmodel.cn/cn/guide/models/text/glm-5.3.md"
-curl -sL "https://platform.minimaxi.com/docs/guides/server-tools.md"
-```
-
-先抓 `<域名>/docs/llms.txt`（Kimi/MiniMax/智谱都有），按关键词过滤出目标模型的全部页面——LLM 供应商的文档比生成模型供应商更"碎"，同一个模型的思考参数、联网搜索、工具调用、定价往往各自独立成页，只看模型主页会漏掉大半细节（例如 Kimi K3 的 `$web_search` 用法、固定采样参数、视觉输入必须 base64 这几条，全部在主页之外的独立页面）。
-
-## 二、Docusaurus 站点（DeepSeek）：先查 sitemap，不要猜 locale 前缀
-
-`api-docs.deepseek.com` 是 Docusaurus，**不支持** `.md` 后缀（会静默 fallback 到别的页面，返回 200 但内容驴唇不对马嘴），也没有 `/zh-cn/` 中文前缀可用（那是根据浏览器语言自动切换的，服务端 sitemap 里只有不带前缀的英文路径）：
-
-```bash
-curl -sL "https://api-docs.deepseek.com/sitemap.xml" | grep -oE "<loc>[^<]+</loc>"
-```
-
-抓到真实 URL 列表后直接 curl 拿完整 SSR HTML，配合下面的 HTML 转文本脚本提取正文，不要在浏览器里跟折叠 UI 搏斗。
-
-```python
-# strip_html.py 核心思路：用 HTMLParser 只保留 article / .theme-doc-markdown 容器内的文本，
-# pre/code 块保留反引号和代码围栏，跳过 script/style/nav/header/footer。
-# 完整实现见本次调研留档，或按需重写——逻辑不复杂，不必依赖第三方库。
-```
-
-## 三、Volcengine 方舟文档：内容 API 对新版块（Responses API）会"假成功、真空"
-
-`docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=<id>&type=online` 对大多数页面能直接拿到 `Result.MDContent`，但**对"进阶使用 → 使用 Responses API"这个分类节点本身**，接口返回 200 且结构完整，`Result` 却是空的——包括在浏览器里发同一个请求也是空，不是登录墙，是这类"目录节点"本身没有正文，真正的内容在它的子页面。
-
-排查方法：用浏览器打开该节点对应的 `docs.volcengine.com/docs/82379/<id>` 页面，`read_page(filter: interactive)` 读出左侧导航栏里子项的 `href`，从 `href` 里拿到真实子页面的 `DocumentID`，再逐个用内容 API 拉取：
-
-```
-Responses API（父节点，内容为空）[1956278]
-├─ 迁移至 Responses API   [1585128]
-├─ 文本生成                [1958520]
-├─ 深度思考                [1956279]
-├─ 多模态理解              [1958521]
-├─ 工具调用                [1958524]
-└─ 结构化输出(beta)        [1958523]
-```
-
-`getDocList?DataSchema=all_second_nav` 拿到的目录树里能看到这些 DocumentID 和 `ParentID` 关系，但父子内容的可用性不能只看目录结构猜，要么试抓一次，要么直接进浏览器看子项链接。
-
-## 四、纯 SPA 站点（MiMo）：`.md` 后缀无效，必须用浏览器渲染取 `innerText`
-
-`mimo.mi.com` 是纯客户端渲染的 SPA（Vite/React 之类），不管加不加 `.md` 后缀，curl 拿到的都是同一份 index.html 外壳（`<title>Xiaomi MiMo Home</title>`，几百字节的 meta 标签，没有正文）。判断方法：`curl` 到的内容不含目标关键词、且多个不同路径返回**完全相同的字节数**，基本可以确认是 SPA 落到了同一个 fallback 页。
-
-处理方式：
-
-1. 用浏览器打开目标 URL，`wait` 2 秒后 `get_page_text` 通常就能拿到渲染后的正文（这个站点用了标准的 `<main>` 容器，抽取效果不错）。
-2. 页面内部导航链接（"Web Search"这类侧边栏项）不一定对应你猜的 URL slug，`read_page` 有时拿不到完整树（返回空），改用 `javascript_tool` 执行 `Array.from(document.querySelectorAll('a')).map(a=>a.href)` 直接把全部 `<a>` 真实 href 枚举出来，比猜路径快得多，且不会漏掉英文/中文双语言路径（MiMo 的英文文档实际路径带 `/docs/en-US/...` 前缀，中文版没有，两者内容深度不同，**英文版信息量明显更全**，优先读英文版）。
-
-## 五、登录墙不代表拿不到数据：先找"控制台之外"的公开镜像
-
-阿里云百炼的模型详情页（`bailian.console.aliyun.com/.../model-market/detail/<model>`）需要登录，自动化浏览器访问会被拦截（`请求失败，请检查网络设置`，不是普通登录跳转，疑似有风控识别自动化指纹）。
-
-**不要止步于此就去问用户登录**——先确认 `help.aliyun.com`（SSR，无需登录）是否已经覆盖了同样信息：
-
-```bash
-curl -sL "https://help.aliyun.com/zh/model-studio/models.md"          # 模型清单
-curl -sL "https://help.aliyun.com/zh/model-studio/text-generation.md" # 协议、Base URL、代码示例
-curl -sL "https://help.aliyun.com/zh/model-studio/model-pricing.md"   # 完整价格表（含控制台看不到的历史档位）
-curl -sL "https://help.aliyun.com/zh/model-studio/web-search.md"      # 联网搜索工具
-```
-
-这次调研里，百炼模型的 Base URL、协议、请求示例、思考模式、联网搜索、完整价格表（含此前遗漏的 `-prime` 优速档）全部从这几个公开页面拿到，控制台页面实际只有"体验中心""账号用量"这类交互功能是必须登录的。**只有确认公开文档站确实覆盖不了、且信息对本次任务是必需的，才应该停下来请用户登录**，不要把"控制台需要登录"直接等同于"这份资料需要登录才能拿到"。
-
-## 六、LLM 供应商的三项高频交叉校验
-
-| 校验 | 为什么 | 这次的实例 |
-|---|---|---|
-| **协议覆盖面**：一份"总览/清单"资料说某供应商"支持 Responses API"，不代表所有模型、所有账号状态都支持 | 官方文档经常在正文里单独标注例外 | GLM-5.3 官方原文写"订阅过 GLM Coding Plan（含已过期）的账号暂时只能走 Chat Completions"；火山方舟官方原文写"`doubao-1-5-pro-32k-character-250715` 不支持 Responses API" |
-| **联网搜索的协议边界**：同一供应商，联网搜索能不能用往往和主协议选择绑定，不能默认"哪个协议都能用" | 服务端工具通常只在部分协议上实现 | 火山方舟联网搜索**只有** Responses API 能用，Chat API 完全不支持；MiMo 联网搜索**只有** Chat Completions 能用，Anthropic 协议不支持；MiniMax 联网搜索 Anthropic + Responses 都支持但纯 Chat Completions 不支持 |
-| **模型是否要求特定请求形态**：官方模型页说"支持图片/视频输入"，不代表能直接套用别的模型的请求 schema | 有的模型要求特定接口/字段结构，用错会直接报错而非降级 | 百炼 `qwen3.8-max` 必须用多模态消息数组格式，套用纯文本模型的字符串 `content` 会报 `url error`；Kimi K3 图片输入必须 base64，传公网 URL 不会报错但模型看不到图 |
-
-**处理原则**：三项校验任何一项没做，接入代码大概率会出现"部分场景能用、部分场景莫名其妙不生效"的问题，且大概率不会在请求阶段报错——LLM 供应商的容错策略普遍是"未知参数静默忽略"而不是"报 400"，比生成模型供应商更难通过报错定位问题，写文档时要把这类边界条件明确列出来，不能只写"支持"二字。
-
----
-
-相关：[README.md](README.md)（协议矩阵与供应商清单）、[docs/model-adaptation/文档采集手册.md](../model-adaptation/文档采集手册.md)（生成模型侧的通用方法论）
+# 文档采集手册（LLM 供应商）
+
+> 这份手册只记 LLM 供应商调研中**做过一遍才知道**的东西，是 [docs/model-adaptation/文档采集手册.md](../model-adaptation/文档采集手册.md) 方法论在 LLM 场景下的落地版本；通用方法（`.md` 后缀技巧、SPA 找内容 API、交叉校验）不重复抄写，只记这里特有的坑。
+> 最后更新：2026-08-26（基于 7 家 LLM 供应商的实际采集）
+
+## 一、大多数 LLM 文档站是 Mintlify，`.md` 后缀直接返回原文
+
+`platform.kimi.com`、`docs.bigmodel.cn`、`platform.minimaxi.com`、`api-docs.deepseek.com`（部分页面）在 URL 末尾加 `.md` 都能拿到干净的 Markdown 原文，且首行会自带一条 `llms.txt` 全量索引提示：
+
+```bash
+curl -sL "https://platform.kimi.com/docs/guide/kimi-k3-quickstart.md"
+curl -sL "https://docs.bigmodel.cn/cn/guide/models/text/glm-5.3.md"
+curl -sL "https://platform.minimaxi.com/docs/guides/server-tools.md"
+```
+
+先抓 `<域名>/docs/llms.txt`（Kimi/MiniMax/智谱都有），按关键词过滤出目标模型的全部页面——LLM 供应商的文档比生成模型供应商更"碎"，同一个模型的思考参数、联网搜索、工具调用、定价往往各自独立成页，只看模型主页会漏掉大半细节（例如 Kimi K3 的 `$web_search` 用法、固定采样参数、视觉输入必须 base64 这几条，全部在主页之外的独立页面）。
+
+## 二、Docusaurus 站点（DeepSeek）：先查 sitemap，不要猜 locale 前缀
+
+`api-docs.deepseek.com` 是 Docusaurus，**不支持** `.md` 后缀（会静默 fallback 到别的页面，返回 200 但内容驴唇不对马嘴），也没有 `/zh-cn/` 中文前缀可用（那是根据浏览器语言自动切换的，服务端 sitemap 里只有不带前缀的英文路径）：
+
+```bash
+curl -sL "https://api-docs.deepseek.com/sitemap.xml" | grep -oE "<loc>[^<]+</loc>"
+```
+
+抓到真实 URL 列表后直接 curl 拿完整 SSR HTML，配合下面的 HTML 转文本脚本提取正文，不要在浏览器里跟折叠 UI 搏斗。
+
+```python
+# strip_html.py 核心思路：用 HTMLParser 只保留 article / .theme-doc-markdown 容器内的文本，
+# pre/code 块保留反引号和代码围栏，跳过 script/style/nav/header/footer。
+# 完整实现见本次调研留档，或按需重写——逻辑不复杂，不必依赖第三方库。
+```
+
+## 三、Volcengine 方舟文档：内容 API 对新版块（Responses API）会"假成功、真空"
+
+`docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=<id>&type=online` 对大多数页面能直接拿到 `Result.MDContent`，但**对"进阶使用 → 使用 Responses API"这个分类节点本身**，接口返回 200 且结构完整，`Result` 却是空的——包括在浏览器里发同一个请求也是空，不是登录墙，是这类"目录节点"本身没有正文，真正的内容在它的子页面。
+
+排查方法：用浏览器打开该节点对应的 `docs.volcengine.com/docs/82379/<id>` 页面，`read_page(filter: interactive)` 读出左侧导航栏里子项的 `href`，从 `href` 里拿到真实子页面的 `DocumentID`，再逐个用内容 API 拉取：
+
+```
+Responses API（父节点，内容为空）[1956278]
+├─ 迁移至 Responses API   [1585128]
+├─ 文本生成                [1958520]
+├─ 深度思考                [1956279]
+├─ 多模态理解              [1958521]
+├─ 工具调用                [1958524]
+└─ 结构化输出(beta)        [1958523]
+```
+
+`getDocList?DataSchema=all_second_nav` 拿到的目录树里能看到这些 DocumentID 和 `ParentID` 关系，但父子内容的可用性不能只看目录结构猜，要么试抓一次，要么直接进浏览器看子项链接。
+
+## 四、纯 SPA 站点（MiMo）：`.md` 后缀无效，必须用浏览器渲染取 `innerText`
+
+`mimo.mi.com` 是纯客户端渲染的 SPA（Vite/React 之类），不管加不加 `.md` 后缀，curl 拿到的都是同一份 index.html 外壳（`<title>Xiaomi MiMo Home</title>`，几百字节的 meta 标签，没有正文）。判断方法：`curl` 到的内容不含目标关键词、且多个不同路径返回**完全相同的字节数**，基本可以确认是 SPA 落到了同一个 fallback 页。
+
+处理方式：
+
+1. 用浏览器打开目标 URL，`wait` 2 秒后 `get_page_text` 通常就能拿到渲染后的正文（这个站点用了标准的 `<main>` 容器，抽取效果不错）。
+2. 页面内部导航链接（"Web Search"这类侧边栏项）不一定对应你猜的 URL slug，`read_page` 有时拿不到完整树（返回空），改用 `javascript_tool` 执行 `Array.from(document.querySelectorAll('a')).map(a=>a.href)` 直接把全部 `<a>` 真实 href 枚举出来，比猜路径快得多，且不会漏掉英文/中文双语言路径（MiMo 的英文文档实际路径带 `/docs/en-US/...` 前缀，中文版没有，两者内容深度不同，**英文版信息量明显更全**，优先读英文版）。
+
+## 五、登录墙不代表拿不到数据：先找"控制台之外"的公开镜像
+
+阿里云百炼的模型详情页（`bailian.console.aliyun.com/.../model-market/detail/<model>`）需要登录，自动化浏览器访问会被拦截（`请求失败，请检查网络设置`，不是普通登录跳转，疑似有风控识别自动化指纹）。
+
+**不要止步于此就去问用户登录**——先确认 `help.aliyun.com`（SSR，无需登录）是否已经覆盖了同样信息：
+
+```bash
+curl -sL "https://help.aliyun.com/zh/model-studio/models.md"          # 模型清单
+curl -sL "https://help.aliyun.com/zh/model-studio/text-generation.md" # 协议、Base URL、代码示例
+curl -sL "https://help.aliyun.com/zh/model-studio/model-pricing.md"   # 完整价格表（含控制台看不到的历史档位）
+curl -sL "https://help.aliyun.com/zh/model-studio/web-search.md"      # 联网搜索工具
+```
+
+这次调研里，百炼模型的 Base URL、协议、请求示例、思考模式、联网搜索、完整价格表（含此前遗漏的 `-prime` 优速档）全部从这几个公开页面拿到，控制台页面实际只有"体验中心""账号用量"这类交互功能是必须登录的。**只有确认公开文档站确实覆盖不了、且信息对本次任务是必需的，才应该停下来请用户登录**，不要把"控制台需要登录"直接等同于"这份资料需要登录才能拿到"。
+
+## 六、LLM 供应商的三项高频交叉校验
+
+| 校验 | 为什么 | 这次的实例 |
+|---|---|---|
+| **协议覆盖面**：一份"总览/清单"资料说某供应商"支持 Responses API"，不代表所有模型、所有账号状态都支持 | 官方文档经常在正文里单独标注例外 | GLM-5.3 官方原文写"订阅过 GLM Coding Plan（含已过期）的账号暂时只能走 Chat Completions"；火山方舟官方原文写"`doubao-1-5-pro-32k-character-250715` 不支持 Responses API" |
+| **联网搜索的协议边界**：同一供应商，联网搜索能不能用往往和主协议选择绑定，不能默认"哪个协议都能用" | 服务端工具通常只在部分协议上实现 | 火山方舟联网搜索**只有** Responses API 能用，Chat API 完全不支持；MiMo 联网搜索**只有** Chat Completions 能用，Anthropic 协议不支持；MiniMax 联网搜索 Anthropic + Responses 都支持但纯 Chat Completions 不支持 |
+| **模型是否要求特定请求形态**：官方模型页说"支持图片/视频输入"，不代表能直接套用别的模型的请求 schema | 有的模型要求特定接口/字段结构，用错会直接报错而非降级 | 百炼 `qwen3.8-max` 必须用多模态消息数组格式，套用纯文本模型的字符串 `content` 会报 `url error`；Kimi K3 图片输入必须 base64，传公网 URL 不会报错但模型看不到图 |
+
+**处理原则**：三项校验任何一项没做，接入代码大概率会出现"部分场景能用、部分场景莫名其妙不生效"的问题，且大概率不会在请求阶段报错——LLM 供应商的容错策略普遍是"未知参数静默忽略"而不是"报 400"，比生成模型供应商更难通过报错定位问题，写文档时要把这类边界条件明确列出来，不能只写"支持"二字。
+
+---
+
+相关：[README.md](README.md)（协议矩阵与供应商清单）、[docs/model-adaptation/文档采集手册.md](../model-adaptation/文档采集手册.md)（生成模型侧的通用方法论）

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

@@ -1,32 +1,32 @@
-# Bria Eraser · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-28 |
-| SDK 模型 ID | `fal-bria-eraser`（可选工具模型，不进入默认 105 目录） |
-| Fal endpoint ID | `fal-ai/bria/eraser` |
-| API 文档 | https://fal.ai/models/fal-ai/bria/eraser/api |
-| 价格 | $0.04/次 |
-| 登录 | 文档与模型页无需登录；调用需要 Fal Key |
-
-## 协议与字段
-
-使用 Fal 队列公共协议，认证、提交、状态与结果读取同 [Fal 供应商文档](../供应商/Fal.md)。
-输出位于 `image.url`。
-
-| 字段 | 约束 | SDK 策略 |
-|---|---|---|
-| `image_url` | 必填，待处理原图 | `image-upload`，Fal CDN 自动上传 |
-| `mask_url` | 必填，二值遮罩 | `image-upload`，Fal CDN 自动上传 |
-| `mask_type` | `manual` / `automatic`，默认 `manual` | Photoshop 遮罩来自用户选区/画笔，固定发送 `manual` |
-| `preserve_alpha` | 可选 | 插件当前未使用，不发送 |
-| `sync_mode` | 可选 | 不发送，统一走队列 |
-
-该模型的统一画像由 schema 派生为图片输入、图片输出、`operation=image-edit`、`feature=erase`；
-模型定义仍为 `type: image`，避免制造新的生成模态或执行协议。
-
-## 原始链接索引
-
-- https://fal.ai/models/fal-ai/bria/eraser/api — endpoint、字段、结果与队列示例。
-- https://fal.ai/models/fal-ai/bria/eraser — 当前 $0.04/次价格。
-- https://fal.ai/docs/documentation/model-apis/inference/queue — Fal 队列公共协议。
+# Bria Eraser · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| SDK 模型 ID | `fal-bria-eraser`（可选工具模型，不进入默认 105 目录） |
+| Fal endpoint ID | `fal-ai/bria/eraser` |
+| API 文档 | https://fal.ai/models/fal-ai/bria/eraser/api |
+| 价格 | $0.04/次 |
+| 登录 | 文档与模型页无需登录；调用需要 Fal Key |
+
+## 协议与字段
+
+使用 Fal 队列公共协议，认证、提交、状态与结果读取同 [Fal 供应商文档](../供应商/Fal.md)。
+输出位于 `image.url`。
+
+| 字段 | 约束 | SDK 策略 |
+|---|---|---|
+| `image_url` | 必填，待处理原图 | `image-upload`，Fal CDN 自动上传 |
+| `mask_url` | 必填，二值遮罩 | `image-upload`，Fal CDN 自动上传 |
+| `mask_type` | `manual` / `automatic`，默认 `manual` | Photoshop 遮罩来自用户选区/画笔，固定发送 `manual` |
+| `preserve_alpha` | 可选 | 插件当前未使用，不发送 |
+| `sync_mode` | 可选 | 不发送，统一走队列 |
+
+该模型的统一画像由 schema 派生为图片输入、图片输出、`operation=image-edit`、`feature=erase`；
+模型定义仍为 `type: image`，避免制造新的生成模态或执行协议。
+
+## 原始链接索引
+
+- https://fal.ai/models/fal-ai/bria/eraser/api — endpoint、字段、结果与队列示例。
+- https://fal.ai/models/fal-ai/bria/eraser — 当前 $0.04/次价格。
+- https://fal.ai/docs/documentation/model-apis/inference/queue — Fal 队列公共协议。

package/docs/model-adaptation/Bria-/345/210/233/346/204/217/346/224/276/345/244/247/Bria-/345/210/233/346/204/217/346/224/276/345/244/247_Fal.md

@@ -1,31 +1,31 @@
-# Bria 创意放大（Fal）
-
-## 契约
-
-| 项目 | 内容 |
-|---|---|
-| endpoint ID | `bria/upscale/creative` |
-| 输入 | `image_url`；Fal 有示例默认图，应用仍严格要求用户提供 1 张源图 |
-| 输出 | `image: Image`，约 2×，最高 10MP |
-| 参数 | `preserve_alpha`，默认 true |
-| 隐藏字段 | `seed`、`sync_mode` |
-| 价格 | `$0.04/张` |
-| 资料核查 | 2026-08-29；公开，无需登录 |
-
-## 队列与适配
-
-使用 `Authorization: Key <FAL_KEY>` 调用 `https://queue.fal.run`，复用标准 Fal
-`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED` 队列、取消和 URL 提取。canonical ID 为
-`bria-creative-upscale`，应用模型 ID 为 `fal-ai-bria-creative-upscale`。
-
-画布按固定 2× 预估尺寸，在上传前阻止超过 10MP 的输出；透明源图允许提交并默认保留 alpha。该模型属于
-创意增强，可能生成新纹理，界面不使用“无损”措辞。已完成端点、请求、固定价、alpha 和输出上限的离线测试；
-未执行真实付费生成。
-
-## 一手资料
-
-| 信息 | 链接 | 登录 |
-|---|---|---|
-| API 文档 | https://fal.ai/models/bria/upscale/creative/api | 否 |
-| OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=bria/upscale/creative | 否 |
-| API Key | https://fal.ai/dashboard/keys | 是 |
+# Bria 创意放大（Fal）
+
+## 契约
+
+| 项目 | 内容 |
+|---|---|
+| endpoint ID | `bria/upscale/creative` |
+| 输入 | `image_url`；Fal 有示例默认图，应用仍严格要求用户提供 1 张源图 |
+| 输出 | `image: Image`，约 2×，最高 10MP |
+| 参数 | `preserve_alpha`，默认 true |
+| 隐藏字段 | `seed`、`sync_mode` |
+| 价格 | `$0.04/张` |
+| 资料核查 | 2026-08-29；公开，无需登录 |
+
+## 队列与适配
+
+使用 `Authorization: Key <FAL_KEY>` 调用 `https://queue.fal.run`，复用标准 Fal
+`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED` 队列、取消和 URL 提取。canonical ID 为
+`bria-creative-upscale`，应用模型 ID 为 `fal-ai-bria-creative-upscale`。
+
+画布按固定 2× 预估尺寸，在上传前阻止超过 10MP 的输出；透明源图允许提交并默认保留 alpha。该模型属于
+创意增强，可能生成新纹理，界面不使用“无损”措辞。已完成端点、请求、固定价、alpha 和输出上限的离线测试；
+未执行真实付费生成。
+
+## 一手资料
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| API 文档 | https://fal.ai/models/bria/upscale/creative/api | 否 |
+| OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=bria/upscale/creative | 否 |
+| API Key | https://fal.ai/dashboard/keys | 是 |

package/docs/model-adaptation/ControlLight/ControlLight_Fal.md

@@ -1,85 +1,85 @@
-# ControlLight（Fal）适配资料
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-29 |
-| 平台 | Fal |
-| 展示名 | ControlLight |
-| API endpoint ID | `fal-ai/control-light` |
-| 模态 | 单图输入 → 暗光增强图片 |
-| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/control-light` |
-| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
-| 价格 | `$0.03 / megapixel` |
-| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
-
-## 1. 能力与产品边界
-
-ControlLight 是基于 FLUX.2 [klein] 9B 的 LoRA，用于抬升暗光曝光并恢复可见细节。它与“重新设计光照方向/风格”不同：核心可见控件应是 `lighting_level` 强度，产品名建议使用“暗光增强”或“低光修复”，不宣称为物理补光。
-
-## 2. 接口与队列契约
-
-- 鉴权：`Authorization: Key <FAL_KEY>`
-- 直连：`POST https://fal.run/fal-ai/control-light`
-- 队列提交：`POST https://queue.fal.run/fal-ai/control-light`
-- 状态：`GET https://queue.fal.run/fal-ai/control-light/requests/{request_id}/status`
-- 结果：`GET https://queue.fal.run/fal-ai/control-light/requests/{request_id}`
-- 取消：`PUT https://queue.fal.run/fal-ai/control-light/requests/{request_id}/cancel`
-- 结果路径：`images[].url`；`images` 必填，`seed` 在 OpenAPI 中也标为必填
-
-队列状态仅有 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` 和 `request_id` 必填，日志、指标、队列位置和各 URL 可选。`COMPLETED` 后必须另取结果并校验媒体 URL；模型 OpenAPI 未定义新错误码、断线恢复或乱序规则，其余沿用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
-
-## 3. 请求字段
-
-| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
-|---|---|---|---|---|
-| `image_url` | string | 是 | 官方未公布文件限制 | 恰好 1 张已有素材，由 Fal CDN 上传 |
-| `lighting_level` | number | 否 | `0.75`；`0..1` | 显示并发送；0 近似不处理，1 为训练范围内最强抬升 |
-| `prompt` | string | 否 | 官方内置一段保留身份、几何和自然颜色的恢复提示词 | 首版不展示、不发送，使用服务端当前默认 |
-| `num_inference_steps` | integer | 否 | `4`；`4..8` | 不展示、不发送 |
-| `guidance_scale` | number | 否 | `1`；`0..20` | 不展示、不发送 |
-| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不发送，保持官方默认 |
-| `seed` | integer/null | 否 | 随机 | 不展示、不发送 |
-| `sync_mode` | boolean | 否 | `false` | 不展示、不发送，使用持久队列 |
-| `output_format` | enum | 否 | `png`；`jpeg` / `png` / `webp` | 按项目约定不展示、不发送 |
-
-## 4. 示例与响应契约冲突
-
-```json
-{
-  "image_url": "https://v3.fal.media/files/.../low-light.png",
-  "lighting_level": 0.75
-}
-```
-
-```json
-{
-  "images": [
-    {
-      "url": "https://v3b.fal.media/files/.../enhanced.png",
-      "width": 768,
-      "height": 1360,
-      "content_type": "image/png"
-    }
-  ],
-  "has_nsfw_concepts": [false]
-}
-```
-
-OpenAPI 把 `seed` 标为必填，但同一份官方 `llms.txt` 的字面响应示例缺少 `seed`。因此解析器只应将非空 `images[].url` 作为成功必要条件，`seed` 按可选元数据读取，不得因为缺少 seed 丢弃有效图片。
-
-## 5. 计价与未知项
-
-- 实时 `llms.txt` 标价 `$0.03 / megapixel`，但未字面说明是输入、输出还是处理像素。
-- 静态目录可保留 `$0.03/MP` 单位价；在未通过 billing event 校验前，不应把估算值表述成最终账单。
-- 官方未给输入图像尺寸/格式上限、输出尺寸算法、延迟 SLA 和结果保留期。
-- 真实验收需记录 0 / 0.75 / 1 三档对主体、噪点、高光溢出和计费的影响。
-
-## 6. 原始链接索引
-
-| 内容 | 链接 | 是否需登录 | 核查日期 |
-|---|---|---|---|
-| 模型页与当前价格 | https://fal.ai/models/fal-ai/control-light | 否 | 2026-08-29 |
-| 实时字段、范围、示例与价格 | https://fal.ai/models/fal-ai/control-light/llms.txt | 否 | 2026-08-29 |
-| OpenAPI（必填、响应与枚举） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/control-light | 否 | 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 |
+# ControlLight（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | ControlLight |
+| API endpoint ID | `fal-ai/control-light` |
+| 模态 | 单图输入 → 暗光增强图片 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/control-light` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
+| 价格 | `$0.03 / megapixel` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+## 1. 能力与产品边界
+
+ControlLight 是基于 FLUX.2 [klein] 9B 的 LoRA，用于抬升暗光曝光并恢复可见细节。它与“重新设计光照方向/风格”不同：核心可见控件应是 `lighting_level` 强度，产品名建议使用“暗光增强”或“低光修复”，不宣称为物理补光。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/control-light`
+- 队列提交：`POST https://queue.fal.run/fal-ai/control-light`
+- 状态：`GET https://queue.fal.run/fal-ai/control-light/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/control-light/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/control-light/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；`images` 必填，`seed` 在 OpenAPI 中也标为必填
+
+队列状态仅有 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` 和 `request_id` 必填，日志、指标、队列位置和各 URL 可选。`COMPLETED` 后必须另取结果并校验媒体 URL；模型 OpenAPI 未定义新错误码、断线恢复或乱序规则，其余沿用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_url` | string | 是 | 官方未公布文件限制 | 恰好 1 张已有素材，由 Fal CDN 上传 |
+| `lighting_level` | number | 否 | `0.75`；`0..1` | 显示并发送；0 近似不处理，1 为训练范围内最强抬升 |
+| `prompt` | string | 否 | 官方内置一段保留身份、几何和自然颜色的恢复提示词 | 首版不展示、不发送，使用服务端当前默认 |
+| `num_inference_steps` | integer | 否 | `4`；`4..8` | 不展示、不发送 |
+| `guidance_scale` | number | 否 | `1`；`0..20` | 不展示、不发送 |
+| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不发送，保持官方默认 |
+| `seed` | integer/null | 否 | 随机 | 不展示、不发送 |
+| `sync_mode` | boolean | 否 | `false` | 不展示、不发送，使用持久队列 |
+| `output_format` | enum | 否 | `png`；`jpeg` / `png` / `webp` | 按项目约定不展示、不发送 |
+
+## 4. 示例与响应契约冲突
+
+```json
+{
+  "image_url": "https://v3.fal.media/files/.../low-light.png",
+  "lighting_level": 0.75
+}
+```
+
+```json
+{
+  "images": [
+    {
+      "url": "https://v3b.fal.media/files/.../enhanced.png",
+      "width": 768,
+      "height": 1360,
+      "content_type": "image/png"
+    }
+  ],
+  "has_nsfw_concepts": [false]
+}
+```
+
+OpenAPI 把 `seed` 标为必填，但同一份官方 `llms.txt` 的字面响应示例缺少 `seed`。因此解析器只应将非空 `images[].url` 作为成功必要条件，`seed` 按可选元数据读取，不得因为缺少 seed 丢弃有效图片。
+
+## 5. 计价与未知项
+
+- 实时 `llms.txt` 标价 `$0.03 / megapixel`，但未字面说明是输入、输出还是处理像素。
+- 静态目录可保留 `$0.03/MP` 单位价；在未通过 billing event 校验前，不应把估算值表述成最终账单。
+- 官方未给输入图像尺寸/格式上限、输出尺寸算法、延迟 SLA 和结果保留期。
+- 真实验收需记录 0 / 0.75 / 1 三档对主体、噪点、高光溢出和计费的影响。
+
+## 6. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/control-light | 否 | 2026-08-29 |
+| 实时字段、范围、示例与价格 | https://fal.ai/models/fal-ai/control-light/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（必填、响应与枚举） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/control-light | 否 | 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/Eleven-v4/Eleven-v4_Fal.md

@@ -0,0 +1,49 @@
+# ElevenLabs Eleven v4（含 v4 Turbo）· Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 音频（语音合成） |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `elevenlabs/tts/eleven-v4`、`elevenlabs/tts/eleven-v4-turbo` |
+| 痕迹AI 模型 ID | `fal-eleven-v4-tts`（canonical `eleven-v4-tts`），v4 / v4 Turbo 用「版本」切换 |
+| 接口形态 | Fal 队列异步 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 请求参数（OpenAPI，2026-11-07 读取；两个端点字段相同）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `text` | string | 是 | — | ≤5000 字符；支持 `[whispering]` 等音频标签与 `/…/` 包裹的 IPA 读音 |
+| `voice` | string | 否 | `Rachel` | 音色名或音色 ID |
+| `stability` | number | 否 | `0.5` | 0–1，越低越有表现力 |
+| `similarity_boost` | number | 否 | `0.75` | 0–1；未接入 |
+| `language_code` | string | 否 | — | ISO 639-1 |
+| `apply_text_normalization` | string | 否 | `auto` | `auto`/`on`/`off`；未接入 |
+| `timestamps` | boolean | 否 | `false` | 返回逐字时间；未接入 |
+| `output_format` | string | 否 | `mp3_44100_128` | 按产品约定不展示、不下发 |
+
+响应：`{ "audio": { "url", ... }, "timestamps": null }`。
+
+## 2. 价格（模型页 publicEndpointBilling，2026-11-07 读取）
+
+| 版本 | 单价 |
+|---|---|
+| v4 | $0.08 / 千字符 |
+| v4 Turbo | $0.04 / 千字符 |
+
+## 3. 适配要点
+
+- 结构照搬 [Eleven v3 · Fal](../TTS-多供应商-2026-09.md) 的参数（音色、稳定度、语言代码），新增「版本」切端点。
+- 音色选择器复用 Eleven v3 的预置音色清单，并允许填自定义音色 ID。
+- 文本超过 5000 字符在发请求前拒绝。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| v4 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=elevenlabs/tts/eleven-v4 | 否 |
+| v4 Turbo schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=elevenlabs/tts/eleven-v4-turbo | 否 |
+| v4 价格 | https://fal.ai/models/elevenlabs/tts/eleven-v4 | 否 |
+| v4 Turbo 价格 | https://fal.ai/models/elevenlabs/tts/eleven-v4-turbo | 否 |