@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/model-adaptation/Kling-4.0/Kling-4.0_Fal.md

@@ -0,0 +1,115 @@
+# Kling 4.0 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `kling/v4/{text-to-video,image-to-video,reference-to-video,video-to-video/edit}` |
+| 痕迹AI 模型 ID | `fal-ai-kling-4.0`（canonical `kling-video-4.0`） |
+| 接口形态 | Fal 队列异步 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+Flash 版见 [Kling-4.0-Flash_Fal.md](../Kling-4.0-Flash/Kling-4.0-Flash_Fal.md)。
+
+## 1. 请求参数（OpenAPI，2026-11-07 读取）
+
+### 1.1 `text-to-video`
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `prompt` | string | 与 `multi_prompt` 二选一 | — | ≤26000 字符 |
+| `multi_prompt` | array | 否 | — | 分镜列表，至少 1 镜；每镜 `prompt`（必填，1–512 字符）+ `duration`（整数 1–30，默认 5），成片时长为各镜之和 |
+| `aspect_ratio` | string | 否 | `16:9` | `16:9` / `9:16` / `1:1` / `21:9` |
+| `duration` | integer | 否 | `5` | 3–30 |
+| `resolution` | string | 否 | `1080p` | `720p` / `1080p` |
+
+### 1.2 `image-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `start_image_url` | string | 是 | 首帧；≤30MB，宽高 ≥300px，宽高比 0.4–2.5 |
+| `end_image_url` | string | 否 | 尾帧 |
+| `middle_image_urls` | array | 否 | 首尾之间按顺序的关键帧，最多 8 张 |
+| `prompt` / `multi_prompt` | | 否 | 可都不给 |
+| `duration` / `resolution` | | 否 | 同上；无 `aspect_ratio` |
+
+### 1.3 `reference-to-video`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `prompt` | string | 用 `@Image1`、`@Video1`、`@Element1` 引用素材；与 `multi_prompt` 二选一 |
+| `image_urls` | array | 参考图，最多 10 |
+| `video_urls` | array | 参考视频，最多 5；每段 3–30 秒，与元素视频合计 ≤30 秒 |
+| `multi_prompt` | array | 分镜，结构同 1.1 |
+| `elements` | array | 角色/物体元素，最多 7，其中视频元素最多 3、带 `voice_id` 的最多 3；结构见 1.5 |
+| `voice_ids` | array | 声音，最多 3（未接入） |
+| `start_image_url` / `end_image_url` / `middle_image_urls` | | 可选，计入图片上限（未接入） |
+| `aspect_ratio` | string | `auto` / `16:9` / `9:16` / `1:1` / `21:9`，默认 `16:9` |
+| `duration` / `resolution` | | 同上 |
+
+### 1.4 `video-to-video/edit`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `prompt` | string | 是 | 修改说明，源视频记作 `@Video1` |
+| `video_url` | string | 是 | 源视频 3–30 秒，≤300MB，宽高 700–4553px，宽高比 0.4–2.5 |
+| `video_urls` | array | 否 | 参考视频 `@Video2…`，最多 4；源、参考、元素视频合计 ≤30 秒 |
+| `image_urls` | array | 否 | 参考图 |
+| `elements` | array | 否 | 同 1.3，结构见 1.5 |
+| `duration` | integer | 否 | 3–30，默认等于源视频长度（不下发） |
+| `aspect_ratio` | string | 否 | 不给则跟随源视频 |
+| `resolution` | string | 否 | `720p` / `1080p`，默认 `1080p` |
+
+没有 `multi_prompt`；另有 `voice_ids`、`start_image_url` / `end_image_url` / `middle_image_urls`（未接入）。OpenAPI 中没有 `generate_audio` 字段。
+
+### 1.5 元素（`KlingV4Element`）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `frontal_image_url` | string | 正面主图；≤30MB，宽高 ≥300px，宽高比 0.4–2.5 |
+| `reference_image_urls` | array | 其他角度，1–3 张（schema 只写 maxItems 3，最少 1 张见字段说明） |
+| `video_url` | string | 代替图片的元素视频，3–8 秒，宽高 700–4553px |
+| `voice_id` | string | 绑定声音，需先用 `fal-ai/kling-video/create-voice` 创建（未接入） |
+
+提示词按顺序用 `@Element1`、`@Element2` 引用。
+
+## 2. 响应结构
+
+```json
+{ "video": { "url": "https://.../output.mp4" } }
+```
+
+## 3. 价格（模型页 pricingInfoOverride / publicEndpointBilling，2026-11-07 读取）
+
+| 情形 | 720p | 1080p | 计费时长 |
+|---|---|---|---|
+| 文生 / 图生 / 只用参考图 | $0.157/秒 | $0.235/秒 | 输出时长 |
+| 带参考视频或视频元素 / 视频编辑 | $0.094/秒 | $0.141/秒 | 输入 + 输出时长，且至少为输出的 2 倍 |
+
+参考生视频页原文把“视频元素”和参考视频并列为低价档的触发条件（“With video references or video elements”）。分镜成片时长等于各镜之和，按这个总和计费。
+
+## 4. 适配要点
+
+- 素材尺寸前置校验（2026-11-08）：`videoConstraints` 源视频与元素视频宽高 700–4553 px，视频编辑另校验宽高比 0.4–2.5；元素其他角度图文档未写尺寸，不校验图片。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+- 一个模型、显式 `mode`：文/图生视频、参考生视频、视频编辑。
+- 文/图生视频：0 张图走文生；有图时第 1 张作首帧、最后一张作尾帧、中间按顺序作关键帧（最多 10 张）。
+- 视频编辑：第 1 个视频是源视频，其余作参考（最多 4）；不下发 `duration`，比例选智能时不下发（跟随源视频）。
+- 视频编辑计费按「源视频时长作输出」估算：`max(全部输入时长 + 源时长, 2 × 源时长)`；参考视频时长来自宿主注入的 `__videoDurationSeconds`，未知时每段按 5 秒估。
+- 分镜（`falKling40Shots`，面板 `shot-list`）：文/图生视频与参考生视频可用，视频编辑隐藏且不发送。值为 `[{ id, prompt, duration }]`；非空时只发 `multi_prompt`，不发 `prompt` 与 `duration`，时长参数隐藏；平台两者二选一，项目把主提示词当整体描述拼到每一镜提示词前（换行连接，拼接后仍按每镜 ≤512 字符校验），主提示词可留空。各镜之和按时长参数范围校验为 3–30 秒（schema 没有单独写总和范围），估价按总和。
+- 元素（`falKling40Elements`，面板 `subject-elements`）：参考生视频与视频编辑可用。值为 `[{ id, kind, images, videos, videoSeconds? }]`（`videoSeconds` 只用于估价，不发送）；图片元素 2–4 张，第 1 张作 `frontal_image_url`、其余作 `reference_image_urls`；视频元素只发 `video_url`。媒体字段由公共上传预处理按字段名上传。视频元素估价用上传时读到的时长，读不到按上限 8 秒计入输入时长，避免付费授权偏低。
+- 未接入：`voice_ids` 与元素 `voice_id`（需另建声音）、参考模式里的首尾帧字段。源、参考与元素视频合计 ≤30 秒在提交前无法核对（元素视频时长未知），由平台校验。
+- 官方请求 schema 落在 `tests/fixtures/model-requests-2026-11/fal-kling-4.0-*.json`（含 Flash 两份），由 `tests/catalog/kling-4.0-shots-elements.test.ts` 校验；未做付费真网验收。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/text-to-video | 否 |
+| 图生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/image-to-video | 否 |
+| 参考生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/reference-to-video | 否 |
+| 视频编辑 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/video-to-video/edit | 否 |
+| 模型页与价格 | https://fal.ai/models/kling/v4/text-to-video | 否 |
+| 参考生视频价格 | https://fal.ai/models/kling/v4/reference-to-video | 否 |
+| 视频编辑价格 | https://fal.ai/models/kling/v4/video-to-video/edit | 否 |

package/docs/model-adaptation/Kling-4.0/Kling-4.0_KIE.md

@@ -0,0 +1,61 @@
+# Kling 4.0 · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 项目模型 | `kie-kling-4.0`，通用标识 `kling-video-4.0`；Flash 见 [Kling-4.0-Flash_KIE.md](../Kling-4.0-Flash/Kling-4.0-Flash_KIE.md) |
+| model ID | `kling-4.0/keyframe-to-video`、`kling-4.0/reference-to-video` |
+| 文档与价格 | 公开，无需登录 |
+| 定价（每秒） | 关键帧/无视频输入：720p $0.1425、1080p $0.2125；带视频输入（参考视频或视频元素）：720p $0.085、1080p $0.1275，按 `max(2 × 输出, 输入 + 输出)` 秒计费（多段输入相加；例：10 秒输出 + 5 秒输入计 20 秒，15 秒输入计 25 秒） |
+
+## 请求契约
+
+`POST https://api.kie.ai/api/v1/jobs/createTask`，`{model,input}`。项目用显式模式切换两个端点：文/图生视频 → keyframe，参考生视频 → reference。
+
+### keyframe-to-video
+
+| 字段 | 值与约束 | 项目处理 |
+|---|---|---|
+| prompt | 必填，≤8000；可用 `@first_frame`、`@keyframe_N`、`@last_frame` 指代已上传的帧 | 统一提示词 |
+| duration | 整数 3–30，默认 5；同时限制总帧数：3s→4、4s→5…8s→9、≥9s→10 | 下拉 3–30；超出帧数在提交前报错 |
+| resolution | 720p / 1080p，默认 720p | 展示 |
+| aspect_ratio | auto、16:9、9:16、1:1、21:9；仅无帧时生效，有帧跟随首帧 | 智能比例：有帧不发送也不显示，无帧本地转具体值 |
+| first_frame_url / keyframe_urls（≤8）/ last_frame_url | 公网图片 URL | 上传图片依次映射：第 1 张首帧，末张尾帧，中间为关键帧 |
+
+### reference-to-video
+
+| 字段 | 值与约束 | 项目处理 |
+|---|---|---|
+| image_urls | ≤10 张，边长 300–65536，宽高比 0.4–2.5；`@image_N` 指代 | 上传图片 |
+| video_urls | ≤5 段，每段 2–30 秒；`@video_N` 指代 | 上传视频 |
+| keep_original_sound | 仅有参考视频时生效，默认 false；无参考视频时始终生成原生音频 | 有视频时显示开关 |
+| aspect_ratio | 省略时有素材用 auto，无素材 16:9 | 智能比例：有素材发 auto，无素材 16:9 |
+| elements（≤7，含视频主体 ≤3） | 每项 `name`（必填，1–20 个汉字/字母/数字/下划线，不区分大小写唯一，不能用 `image_N`、`video_N`、`keyframe_N`、`object_N`、`audio_N`、`first_frame`、`last_frame`）+ `image_urls`（2–4 张，第 1 张为主视角）或 `video_url`（3–8 秒单镜头角色视频，短边 ≥700px），二者互斥；可选 `tag`（character/animal/prop/costume/scene/effect/others，视频主体只能 character）、`description`（≤100 字符）、`voice_url`；提示词用 `@name` 引用 | “元素”面板（`kieKling40Elements`），只在参考生视频显示与发送；发 `name` + `image_urls` 或 `video_url`，`tag`、`description`、`voice_url` 不显示不发送 |
+| voices（≤3） | 独立声音，`name` + `audio_url` | 不显示、不请求 |
+
+四类素材合计 ≤15，参考视频加视频主体 ≤5，项目在提交前校验这两条及名称规则。参考视频与视频元素总时长 ≤30 秒由平台校验（元素视频时长提交前未知）。`callBackUrl` 不发送。
+
+**没有分镜**：两个端点的 schema 都没有 `multi_prompt`（`additionalProperties: false`），分镜能力不适用。
+
+估价：带视频输入时视频时长取宿主注入的 `__videoDurationSeconds`，未知时每段参考视频按 5 秒估；视频元素用上传时读到的时长，读不到按上限 8 秒估。
+
+## 事件与失败契约
+
+沿用 [KIE 供应商文档](../供应商/KIE.md) 第 2 节 Market 统一任务契约，未引入新轮询或解析分支。官方请求 schema 见 `tests/fixtures/model-requests-2026-11/kie-kling-4.0-*.json`，由 `tests/catalog/kie-grsai-2026-11.test.ts` 校验；未做付费真网验收。
+
+## 项目适配
+
+- 素材尺寸前置校验（2026-11-08）：`imageConstraints` 边长 300–65536 px、宽高比 0.4–2.5（Flash 文档未写尺寸，不声明）。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+
+## 原始链接索引
+
+均公开，无需登录：
+- [Keyframe To Video](https://docs.kie.ai/market/kling/v4-keyframe-to-video.md)
+- [Reference To Video](https://docs.kie.ai/market/kling/v4-reference-to-video.md)
+- [模型页](https://kie.ai/kling-4-0)
+- [实时价格页](https://kie.ai/pricing)（2026-11-07 核对 6 行 kling 4.0 价格）
+- 带视频输入的计费秒数规则见模型页 pricingDesc（2026-11-07 读取）
+
+## 2026-11-08 关键帧张数随时长收住
+
+关键帧模式每秒 1 张再加首帧、最多 10 张（构建时已按此校验）；上传上限现在也按当前时长计算，5 秒最多 6 张，不再等提交才报错。参考生视频仍是图片 10、视频 5。

package/docs/model-adaptation/Kling-4.0-Flash/Kling-4.0-Flash_Fal.md

@@ -0,0 +1,55 @@
+# Kling 4.0 Flash · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `kling/v4/flash/{text-to-video,image-to-video,reference-to-video,video-to-video}` |
+| 痕迹AI 模型 ID | `fal-ai-kling-4.0-flash`（canonical `kling-video-4.0-flash`） |
+| 接口形态 | Fal 队列异步 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 与 Kling 4.0 标准版的差异
+
+| 项目 | Flash |
+|---|---|
+| 分辨率 | 只有 `720p` |
+| 时长 | 3–20 秒 |
+| 图生视频 | 只有 `start_image_url`，**不接受尾帧和中间关键帧**，无 `aspect_ratio` |
+| 参考生视频 | `prompt` 必填；`image_urls` ≤10、`video_urls` ≤5（每段 3–20 秒，与元素视频合计 ≤20 秒）、`elements` ≤7（视频元素 ≤3）；**不接受声音** |
+| 视频编辑 | 端点 `kling/v4/flash/video-to-video`；源视频 3–20 秒；`video_urls` ≤4、`image_urls` ≤10、`elements` ≤7；**无 `aspect_ratio`** |
+| 分镜 | **四个端点都没有 `multi_prompt`** |
+| 元素结构 | `KlingV4FlashElement`：`frontal_image_url`、`reference_image_urls`（1–3）、`video_url`（3–8 秒）；**没有 `voice_id`** |
+
+其余字段形状与标准版相同，见 [Kling-4.0_Fal.md](../Kling-4.0/Kling-4.0_Fal.md)。
+
+## 2. 价格（模型页 pricingInfoOverride，2026-11-07 读取）
+
+| 情形 | 单价 | 计费时长 |
+|---|---|---|
+| 文生 / 图生 / 只用参考图 | $0.094/秒 | 输出时长 |
+| 带参考视频 / 视频编辑 | $0.063/秒 | 输出时长 + max(输入视频时长, 输出时长) |
+
+Flash 价格原文只写“With video references”；视频元素与参考视频共用 20 秒总时长上限，标准版价格原文也把视频元素列为低价档条件，项目按同样规则把视频元素计入输入时长。
+
+## 3. 适配要点
+
+- 一个模型、显式 `mode`：文/图生视频（0 张图文生、1 张首帧）、参考生视频、视频编辑。
+- 视频编辑不下发 `duration`（输出等于源视频长度），计费按 `源时长 + max(全部输入时长, 源时长)` 估算。
+- 不下发 `resolution`（只有 720p，平台默认即是）。
+- 元素（`falKling40FlashElements`）：参考生视频与视频编辑可用，值结构与映射同标准版（见 Kling-4.0_Fal.md 第 4 节）；视频元素估价用上传时读到的时长，读不到按上限 8 秒计入输入时长。
+- 没有分镜参数（平台不支持 `multi_prompt`）。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/flash/text-to-video | 否 |
+| 图生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/flash/image-to-video | 否 |
+| 参考生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/flash/reference-to-video | 否 |
+| 视频编辑 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=kling/v4/flash/video-to-video | 否 |
+| 模型页与价格 | https://fal.ai/models/kling/v4/flash/text-to-video | 否 |
+| 参考生视频价格 | https://fal.ai/models/kling/v4/flash/reference-to-video | 否 |
+| 视频编辑价格 | https://fal.ai/models/kling/v4/flash/video-to-video | 否 |

package/docs/model-adaptation/Kling-4.0-Flash/Kling-4.0-Flash_KIE.md

@@ -0,0 +1,33 @@
+# Kling 4.0 Flash · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 项目模型 | `kie-kling-4.0-flash`，通用标识 `kling-video-4.0-flash` |
+| model ID | `kling-4.0/flash-keyframe-to-video`、`kling-4.0/flash-reference-to-video` |
+| 文档与价格 | 公开，无需登录 |
+| 定价（每秒） | 首帧/无视频输入 720p $0.085；带视频输入（参考视频或视频元素）720p $0.0565，按 `max(2 × 输出, 输入 + 输出)` 秒计费 |
+
+## 与标准版的差异
+
+请求结构与 [Kling 4.0](../Kling-4.0/Kling-4.0_KIE.md) 相同，差别：
+
+| 项目 | Flash |
+|---|---|
+| resolution | 只有 720p（项目不显示分辨率，固定发送 720p） |
+| duration | 3–20 秒 |
+| keyframe | 只接受 `first_frame_url`；发送中间帧或尾帧会被拒绝，项目限制最多 1 张图 |
+| keyframe aspect_ratio | 16:9、9:16、1:1、21:9，没有 auto；有首帧时跟随首帧（项目不发送，比例选项也隐藏） |
+| reference | 不支持独立 `voices`；参考视频与视频主体总时长须在 2–20 秒，否则任务失败 |
+| elements | 多一个 `type`（`image` 默认 / `video`）：视频主体必须发 `type: "video"` |
+
+elements 与标准版一样接入“元素”面板（`kieKling40FlashElements`），视频元素额外发送 `type: "video"`，图片元素不发 `type`（默认即 image）。同样没有 `multi_prompt`。事件契约沿用 KIE Market 统一任务。
+
+## 原始链接索引
+
+均公开，无需登录：
+- [Flash Keyframe To Video](https://docs.kie.ai/market/kling/v4-flash-keyframe-to-video.md)
+- [Flash Reference To Video](https://docs.kie.ai/market/kling/v4-flash-reference-to-video.md)
+- [模型页](https://kie.ai/kling-4-0-flash)
+- [实时价格页](https://kie.ai/pricing)（2026-11-07 核对 3 行 kling 4.0 flash 价格）
+- 带视频输入的计费秒数规则见模型页 pricingDesc（2026-11-07 读取）

package/docs/model-adaptation/LTX-2.3/LTX-2.3_Fal.md

@@ -0,0 +1,121 @@
+# LTX-2.3 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `fal-ai/ltx-2.3/{text-to-video,image-to-video}[/fast]`、`fal-ai/ltx-2.3/extend-video`、`fal-ai/ltx-2.3/retake-video`、`fal-ai/ltx-2.3/audio-to-video` |
+| 痕迹AI 模型 ID | `fal-ai-ltx-2.3`（canonical `ltx-2.3`），取代已下线的 `fal-ai-ltx-2` |
+| 接口形态 | Fal 队列异步（`queue.fal.run`），与其他 Fal 模型同协议 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 能力与端点
+
+| 能力 | 标准（Pro） | 快速（Fast） |
+|---|---|---|
+| 文生视频 | `fal-ai/ltx-2.3/text-to-video` | `fal-ai/ltx-2.3/text-to-video/fast` |
+| 图生视频 / 首尾帧 | `fal-ai/ltx-2.3/image-to-video` | `fal-ai/ltx-2.3/image-to-video/fast` |
+| 延长视频 | `fal-ai/ltx-2.3/extend-video` | — |
+| 视频重拍（局部重生成） | `fal-ai/ltx-2.3/retake-video` | — |
+| 音频生视频 | `fal-ai/ltx-2.3/audio-to-video`（单一端点，不分标准/快速） | — |
+
+同家族另有 `reframe`、`ltx-2.3-quality/*`、`ltx-2.3-22b/*` 端点，本次未接入（见第 6 节）。
+
+## 2. 请求参数（OpenAPI，2026-11-07 读取）
+
+### 2.1 文生视频 / 图生视频
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 是 | — | |
+| `image_url` | string | 图生必填 | — | 首帧 |
+| `end_image_url` | string | 否 | — | 尾帧，给出即生成首尾帧过渡（标准与快速图生都支持） |
+| `duration` | integer | 否 | `6` | 标准：`6/8/10`；快速：`6/8/10/12/14/16/18/20`，**超过 10 秒只支持 25 FPS + 1080p** |
+| `resolution` | string | 否 | `1080p` | `1080p` / `1440p` / `2160p` |
+| `fps` | integer | 否 | `25` | `24` / `25` / `48` / `50` |
+| `aspect_ratio` | string | 否 | 文生 `16:9`，图生 `auto` | 文生 `16:9` / `9:16`；图生另有 `auto`（按首图） |
+| `generate_audio` | boolean | 否 | `true` | |
+| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不下发 |
+
+### 2.2 延长视频 `extend-video`
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `video_url` | string | 是 | — | |
+| `prompt` | string | 否 | — | 延长部分的描述 |
+| `duration` | number | 否 | `5` | 2–20 秒 |
+| `mode` | string | 否 | `end` | `end` 接在结尾 / `start` 加在开头 |
+| `context` | number | 否 | 自动 | 用作上下文的秒数（1–20）；不展示、不下发 |
+
+### 2.3 视频重拍 `retake-video`
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `video_url` | string | 是 | — | |
+| `prompt` | string | 是 | — | |
+| `start_time` | number | 否 | `0` | 0–20 秒 |
+| `duration` | number | 否 | `5` | 2–20 秒 |
+| `retake_mode` | string | 否 | `replace_audio_and_video` | `replace_audio` / `replace_video` / `replace_audio_and_video` |
+
+### 2.4 音频生视频 `audio-to-video`
+
+OpenAPI `required` 只有 `audio_url`；字段顺序 `audio_url, image_url, prompt, guidance_scale, aspect_ratio, enable_safety_checker`。没有 `duration`、`resolution`、`fps`、`generate_audio`、`seed` 字段。
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `audio_url` | string | 是 | — | 2–20 秒（描述另写“pro models support a maximum of 10 seconds”，本端点未标明属于哪一档）；模型页接受 mp3 / ogg / wav / m4a / aac |
+| `image_url` | string \| null | 否 | — | 首帧图；不传时 `prompt` 必填 |
+| `prompt` | string \| null | 无图时必填 | — | 1–5000 字符；有图时描述如何让图动起来 |
+| `guidance_scale` | number \| null | 否 | 官方说明：文生 5、有图 9 | 1–50；不展示、不下发，交给官方按有无图取默认 |
+| `aspect_ratio` | string | 否 | `auto` | `auto` / `16:9` / `9:16`；`auto` 按首帧图，无图回退 16:9 |
+| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不下发 |
+
+## 3. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" } }
+```
+
+音频生视频的 `video` 是 `VideoFile`：必有 `url`，可选 `content_type`、`file_name`、`file_size`、`width`、`height`、`fps`、`duration`、`num_frames`，与其他端点同一解析路径。
+
+## 4. 价格（模型页 pricingInfoOverride，2026-11-07 读取）
+
+| 端点 | 1080p | 1440p | 2160p |
+|---|---|---|---|
+| 文生 / 图生（标准） | $0.08/秒 | $0.16/秒 | $0.32/秒 |
+| 文生 / 图生（快速） | $0.06/秒 | $0.12/秒 | $0.24/秒 |
+| 延长视频 | $0.10/秒 | | |
+| 视频重拍 | $0.10/秒 | | |
+| 音频生视频 | $0.10/秒（不分分辨率） | | |
+
+音频生视频模型页原文：“$0.10 per second of generated video. Pay-per-second, no minimums.” 按生成视频秒数计费；schema 没有时长参数，视频长度跟随输入音频，所以估价 = 音频时长 × $0.10（“视频与音频等长”是据此推断，页面未逐字写明）。
+
+## 5. 适配要点
+
+- 一个模型、显式 `mode`：文/图生视频（0 张图文生、1 张首帧、2 张首尾帧自动路由）、延长视频、视频重拍、音频生视频。快速/标准用「快速模式」开关切端点。
+- 时长下拉含 12–20 秒；展示层联动在非「快速 + 1080p + 25 FPS」时隐藏这些选项，builder 也会拒绝不合法组合。
+- 智能比例：有图时发 `auto`，无图回退 `16:9`。
+- 延长视频计费按延长秒数，重拍按重拍秒数。
+- 音频生视频是第四个 `mode`：必须 1 段音频，可选 1 张首帧图，无图时 builder 要求提示词；只保留比例（智能 → `auto`），分辨率、时长、帧率、生成音频、快速模式都隐藏且不下发。
+- 音频时长走 `pricing.mediaContext`（`mediaType: 'audio'`、`metric: 'durationSeconds'`、`targetParam: '__audioDurationSeconds'`，只在音频生视频模式生效）：宿主用 ffprobe 读容器时长补进 calculator，生成面板、画布节点估价与提交前的付费确认共用这一份；calculator 通过 `resolveUploadedAudioDurationSeconds` 读取，读不到时按最长 20 秒估。
+
+## 6. 未接入的端点
+
+- `reframe`、`ltx-2.3-quality/*`、`ltx-2.3-22b/*`：不在本次范围。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ltx-2.3/text-to-video | 否 |
+| 文生视频（快速）schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ltx-2.3/text-to-video/fast | 否 |
+| 图生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ltx-2.3/image-to-video | 否 |
+| 图生视频（快速）schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ltx-2.3/image-to-video/fast | 否 |
+| 延长视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ltx-2.3/extend-video | 否 |
+| 视频重拍 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ltx-2.3/retake-video | 否 |
+| 音频生视频 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/ltx-2.3/audio-to-video | 否 |
+| 模型页与全家族价格 | https://fal.ai/models/fal-ai/ltx-2.3/text-to-video | 否 |
+| 音频生视频模型页与价格 | https://fal.ai/models/fal-ai/ltx-2.3/audio-to-video | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |