@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/Seedance-2.0/Seedance-2.0_APIMart.md

@@ -0,0 +1,121 @@
+# Seedance 2.0 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `seedance-2.0`（旧名 `seedance-2-0`） |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> 同一份 APIMart 文档同时覆盖 `seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini`，参数结构一致，差异集中在**分辨率上限**与**提示词长度**。本文件只讲标准版。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/videos/generations` → `{ code: 200, data: [{ status: "submitted", task_id }] }`
+- **查询**：`GET /v1/tasks/{task_id}`，状态 `pending` / `processing` / `completed` / `failed`，结果在 `result.videos[]`
+
+## 2. 能力清单
+
+文生视频、图生视频（首帧）、**首尾帧视频**、**参考视频生视频**、**参考音频**、**有声视频**、**连续视频生成（返回尾帧）**、**联网搜索增强**、**私域虚拟人像素材（Asset URL）**。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | `seedance-2.0` |
+| `prompt` | string | 条件 | — | **文生视频必填**；图生视频 / 视频参考生视频可选。限制 4000 字符，**建议 500 字符以内** |
+| `duration` | integer | 可选 | `5` | **4 ~ 15 秒** |
+| `size` | string | 可选 | `16:9` | `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、**`adaptive`**（根据输入图/视频自动匹配）。宽高比须在 0.5–2.5 之间 |
+| `resolution` | string | 可选 | `720p` | `480p` / `720p` / **`1080p`（仅标准版）** / **`4k`（仅标准版）** |
+| `seed` | integer | 可选 | — | 随机种子。**本项目规则：绝对不显示**，不下发 |
+| `generate_audio` | boolean | 可选 | **`true`** | 是否生成配套音频（有声视频） |
+| `return_last_frame` | boolean | 可选 | `false` | `true` 时结果额外返回视频最后一帧的图片 URL，用于连续视频生成 |
+| `tools` | array | 可选 | — | 工具列表，如 `[{"type": "web_search"}]`（联网搜索） |
+| `image_urls` | string[] | 可选 | — | 图生视频参考图。普通 URL 或 `asset://asset_a`。**最多 9 张**。**与 `image_with_roles` 不能同时使用** |
+| `image_with_roles` | array | 可选 | — | 带角色的图片数组，元素为 `{ url, role }`。`role` ∈ `first_frame`（首帧）/ `last_frame`（尾帧）/ `reference_image`（参考人像图，配合 Asset URL）。**与 `image_urls` 不能同时使用** |
+| `video_urls` | string[] | 可选 | — | 参考视频。**最多 3 个，1.8 s < 总时长 < 15.2 s，分辨率需在 480P ~ 720P 之间**。**使用首/尾帧图片时不可用** |
+| `audio_urls` | string[] | 可选 | — | 参考音频。**最多 3 个，总时长 ≤ 15 s**。**必须与参考图片或参考视频一起用**；**使用首/尾帧图片时不可用** |
+| `nsfw_check` | boolean | 可选 | `false` | 见下 |
+
+### 互斥与依赖关系（务必在 UI 层做约束）
+
+- `image_urls` ⊗ `image_with_roles`（二选一）
+- 使用 `image_with_roles` 的首/尾帧时，`video_urls` 与 `audio_urls` **都不可用**
+- `audio_urls` 必须与参考图片或参考视频一起使用
+
+### `nsfw_check` 细节
+
+- 审核范围：文本 `prompt`、`negative_prompt`；图片 `image_urls`、`image_with_roles[].url`、`first_frame_image`、`last_frame_image`；`asset://` 图片素材会反查原始公网 URL 后审核；base64 图片转公网地址后审核
+- **`video_urls`、`audio_urls` 以及视频/音频类型的私域素材不会送审**（审核模型不支持视频和音频）
+- 命中审核时**同步返回 HTTP 400（`nsfw_content_detected`）**，不创建任务、不返回 `task_id`、不扣额度
+- 审核服务不可用/超时/响应异常时采用 **fail-open**（继续提交生成请求），因此**不能作为绝对的内容安全保证**
+- 审核调用本身不向发起视频请求的用户计费
+
+## 4. 私域虚拟人像素材（Asset URL）
+
+**独立端点**：`POST https://api.apimart.ai/v1/seedance2/private-avatar`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `group` | object | 素材组信息 `{ name, description }`。不传 `group_id` 时服务端按此自动创建 `AIGC` 类型素材组。**与 `group_id` 二选一** |
+| `group_id` | string | 已有素材组 ID，传入时跳过素材组创建。**与 `group` 二选一** |
+| `project_name` | string | 项目名称，默认 `default` |
+| `asset_type` | string | `Image`（默认）/ `Video` / `Audio` |
+| `assets` | array | 素材列表，元素为 `{ url, name }`（`url` 需公网可访问）。**单次最多 20 个** |
+| `url` / `name` | string | 单素材兼容写法，与 `assets` 数组二选一 |
+
+响应：`data.id`（本地任务 ID）、`data.object = "seedance.avatar.asset.task"`、`data.status = "processing"`、`data.progress`、`data.model`。
+
+审核结果同样用 `GET /v1/tasks/{id}` 查询：
+- 批量提交时**只要有一个素材审核失败，任务状态就是 `failed`**，但已通过的素材仍可用，出现在 `result.usable_assets`
+- `result.usable_assets[].asset_url` 可直接用于视频生成
+- `result.failed_assets` 中的素材需更换源文件或重新提交
+- 单素材任务也会兼容返回 `result.asset_url`
+
+审核通过后把 `asset://...` 传入视频生成接口即可；服务端识别到 `asset://` 前缀后**直接提交官方生成任务，不会再次触发素材审核**。
+
+Asset URL 支持全部 Seedance 2.0 模型（`seedance-2.0` / `-fast` / `-mini`）。
+
+## 5. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → 视频标签页 `SEEDANCE-2.0`（2026-08-30 复核，1 Credit ≈ $0.1）。当前定价中心与模型页的秒价口径一致，未发现新的价格冲突。
+
+| 规格 | 我们的价格 |
+|---|---|
+| 480P | 0.66 Credits/秒 ≈ **$0.066/秒** |
+| 480P-input | 0.4 Credits/秒 ≈ **$0.04/秒** |
+| 720P | 1.42 Credits/秒 ≈ **$0.142/秒** |
+| 720P-input | 0.8584 Credits/秒 ≈ **$0.08584/秒** |
+| 1080P | 3.544 Credits/秒 ≈ **$0.3544/秒** |
+| 1080P-input | 2.1568 Credits/秒 ≈ **$0.21568/秒** |
+| 4K | 7.22 Credits/秒 ≈ **$0.722/秒** |
+| 4K-input | 4.4432 Credits/秒 ≈ **$0.44432/秒** |
+
+`-input` 档位对应「有参考视频输入」的计费方式（单价更低，但按输入 + 输出总时长计费）。
+
+**数字人（私域人像）另有独立价格** `SEEDANCE-2.0-FACE`：480P 0.992 Credits/秒 ≈ $0.0992/秒、480P-input 0.6 ≈ $0.06/秒、720P 2.136 ≈ $0.2136/秒、720P-input 1.288 ≈ $0.1288/秒、1080P 5 ≈ $0.5/秒、1080P-input 3 ≈ $0.3/秒。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口**有 `seed`**（不下发）；`negative_prompt` 未在参数表列出，但 `nsfw_check` 的审核范围提到了它，接入时按「不注册、不下发」处理。
+- **参数互斥关系是这个模型最容易踩的坑**：`image_urls` / `image_with_roles` 二选一；首尾帧模式下参考视频与参考音频全部失效。UI 必须做互斥禁用，不能只靠后端报错。
+- `generate_audio` **默认 `true`**（会出有声视频），与多数模型默认关闭相反。
+- `1080p` / `4k` **仅标准版支持**，Fast / Mini 传了会失败。
+- 有参考视频时计费按「输入 + 输出总时长」，成本估算不能只按输出时长算。
+- SDK 从 `uploadedVideoFilePaths` / `videos` / `uploadedVideos` 取非空且数量最完整的一组；空数组不遮蔽其他字段。宿主按顺序提供完整 `__videoDurationSeconds: number[]` 时求真实总和，数组不完整时改用 `__totalVideoDurationSeconds`，最后才兼容 `__firstVideoDurationSeconds × 视频数` 的旧近似估算。
+- Asset URL 是一整套独立的素材上传 + 审核流程，若要做数字人必须先接 `private-avatar` 端点。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| seedance-2.0 视频生成 | https://docs.apimart.ai/cn/api-reference/videos/seedance-2-0/generation | 否 |
+| 虚拟人像素材（私域 Asset） | https://docs.apimart.ai/cn/api-reference/videos/seedance-2-0/private-avatar | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（视频标签页搜 SEEDANCE-2.0 / SEEDANCE-2.0-FACE） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

package/docs/model-adaptation/Seedance-2.0/Seedance-2.0_Fal.md

@@ -0,0 +1,97 @@
+# Seedance 2.0 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `bytedance/seedance-2.0/text-to-video`、`bytedance/seedance-2.0/image-to-video`、`bytedance/seedance-2.0/reference-to-video` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议（Fal 通用）
+
+- **鉴权**：`Authorization: Key $FAL_KEY`
+- **同步**：`POST https://fal.run/<endpoint-id>`；**队列**：`POST https://queue.fal.run/<endpoint-id>`，`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）、`GET .../requests/{id}`
+- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
+
+## 2. 能力清单（Fal 把每种输入形态拆成独立端点）
+
+| 能力 | endpoint id |
+|---|---|
+| 文生视频 | `bytedance/seedance-2.0/text-to-video` |
+| 图生视频（首帧，可选尾帧） | `bytedance/seedance-2.0/image-to-video` |
+| 参考生视频（图 / 视频 / 音频多模态） | `bytedance/seedance-2.0/reference-to-video` |
+
+## 3. 请求参数
+
+### 3.1 三个端点共有
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 视频描述 |
+| `resolution` | string | 可选 | `720p` | `480p` / `720p` / `1080p` / `4k` |
+| `duration` | string | 可选 | **`auto`** | `auto`、`"4"` ~ `"15"`（**字符串枚举，不是数字**） |
+| `aspect_ratio` | string | 可选 | **`auto`** | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`（**7 个，没有 `adaptive`**） |
+| `generate_audio` | boolean | 可选 | **`true`** | 是否生成同步音频（音效、环境音、口型同步语音）。**开不开音频价格相同** |
+| `bitrate_mode` | string | 可选 | `standard` | `standard` / `high`（更高码率、更大文件） |
+| `end_user_id` | string | 可选 | — | 终端用户唯一 ID |
+
+### 3.2 仅 `image-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_url` | string | **必填** | 首帧图 URL。JPEG / PNG / WebP，**≤ 30 MB** |
+| `end_image_url` | string | 可选 | 尾帧图 URL；提供后视频从首帧过渡到尾帧。JPEG / PNG / WebP，≤ 30 MB |
+
+### 3.3 仅 `reference-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_urls` | string[] | 可选 | 参考图。**在 prompt 中用 `@Image1`、`@Image2` 引用**。JPEG / PNG / WebP，单张 ≤ 30 MB，**最多 9 张**。**所有模态的文件总数不得超过 12** |
+| `video_urls` | string[] | 可选 | 参考视频。prompt 中用 `@Video1` 引用。MP4 / MOV，**最多 3 个**，合计时长 2–15 s，总大小 < 50 MB，分辨率须在 ~480p (640×640) 与 ~720p (834×1112) 之间 |
+| `audio_urls` | string[] | 可选 | 参考音频。prompt 中用 `@Audio1` 引用。MP3 / WAV，**最多 3 个**，合计时长 ≤ 15 s，单个 ≤ 15 MB。**提供音频时必须至少有一张参考图或一个参考视频** |
+
+## 4. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" }, "seed": 42 }
+```
+
+`video` 与 `seed` 都是必返回字段。
+
+## 5. 价格
+
+来源：三个端点的 `llms.txt`（2026-08-22 读取）。
+
+| 项 | 价格 |
+|---|---|
+| 720p（按秒） | **$0.3034 / 秒** |
+| 1080p（按秒） | **$0.682 / 秒** |
+| token 价（480p / 720p / 1080p） | **$0.014 / 1000 tokens** |
+| token 价（4k） | **$0.008 / 1000 tokens** |
+
+token 数计算：`(输出视频高 × 输出视频宽 × 时长 × 24) / 1024`。
+
+`reference-to-video` 有视频输入时：token 数按 `(高 × 宽 × (输入视频时长 + 输出视频时长) × 24) / 1024` 计算，且**价格 × 0.6**——有视频输入 + 720p 时约 **$0.1814 / 秒**。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 入参**没有 `seed`**（只在输出里回传），也没有负面提示词。
+- `duration` 是**字符串枚举**（`"5"` 而不是 `5`），与 APIMart / KIE 的整数不同，序列化时容易出错。
+- `aspect_ratio` 用 `auto` 表示自适应，APIMart / KIE 用 `adaptive`——名字不同，不能共用常量。
+- 三种输入形态在 Fal 上是**三个不同的 endpoint**，而 APIMart / KIE 是同一个 model 靠字段区分；适配层要按有无图 / 有无参考素材做端点路由。
+- `reference-to-video` 的 prompt 里要用 `@Image1` / `@Video1` / `@Audio1` 显式引用素材，这是 Fal 独有的约定，提示词模板要跟着改。
+- 有视频输入时价格 × 0.6，但按「输入 + 输出总时长」计费。
+- `generate_audio` 默认 `true`，但开关不影响价格。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.0/text-to-video/llms.txt | 否 |
+| 图生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.0/image-to-video/llms.txt | 否 |
+| 参考生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.0/reference-to-video/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |

package/docs/model-adaptation/Seedance-2.0/Seedance-2.0_KIE.md

@@ -0,0 +1,86 @@
+# Seedance 2.0 · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `bytedance/seedance-2` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "bytedance/seedance-2", callBackUrl?, input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **终态**：`state` ∈ `waiting` / `queuing` / `generating` / `success` / `fail`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`；**开启 `return_last_frame` 时结构为 `{ resultUrls: [], firstFrameUrl: [], lastFrameUrl: [] }`**（KIE 通用任务详情文档明确说明）
+
+## 2. 能力清单
+
+KIE 把 Seedance 2.0 系列做成**单端点多能力**：有无首帧/尾帧/参考图/参考视频/参考音频，都在同一个 `model` 下靠字段区分。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 见说明 | — | 文本提示词。schema 标为可选但描述写「必填字段」，长度 3–**20000** 字符 |
+| `input.first_frame_url` | string | 可选 | — | 首帧图片地址，或 `asset://{assetId}` |
+| `input.last_frame_url` | string | 可选 | — | 尾帧图片地址，或 `asset://{assetId}` |
+| `input.reference_image_urls` | array | 可选 | — | 参考图，**最多 9 张**（**与首尾帧张数之和不得超过 9 张**）。格式 jpeg/png/webp/bmp/tiff/gif；宽高比 (0.4, 2.5)；边长 (300, 6000) px；单张 < 30 MB |
+| `input.reference_video_urls` | array | 可选 | — | 参考视频，**最多 3 个**。格式 mp4/mov；分辨率 480p/720p；单个时长 [2, 15] s 且总时长 ≤ 15 s；宽高比 [0.4, 2.5]；边长 [300, 6000] px；总像素 [409600 (640×640), 927408 (834×1112)]；单个 ≤ 50 MB；帧率 [24, 60] |
+| `input.reference_audio_urls` | array | 可选 | — | 参考音频，**最多 3 段**。格式 wav/mp3；单个时长 [2, 15] s 且总时长 ≤ 15 s；单个 ≤ 15 MB |
+| `input.return_last_frame` | boolean | 可选 | `false` | 是否返回视频最后一帧图片 |
+| `input.generate_audio` | boolean | 可选 | **`true`** | 是否生成与画面同步的音频 |
+| `input.resolution` | string | 可选 | `720p` | `480p` / `720p` / `1080p` / `4k` |
+| `input.aspect_ratio` | string | 可选 | `16:9` | `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`adaptive` |
+| `input.duration` | integer | 可选 | `5` | **4–15 秒** |
+| `input.web_search` | boolean | 可选 | — | 是否启用联网搜索 |
+| `input.nsfw_checker` | boolean | 可选 | `false` | `false` 时关闭内容过滤，结果直接返回 |
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)`：
+
+- 普通：`{ "resultUrls": ["https://....mp4"] }`
+- 开启 `return_last_frame`：`{ "resultUrls": [], "firstFrameUrl": [], "lastFrameUrl": [] }`
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `seedance`；1 Credit = $0.005）。
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| 480p no video input | 19 /秒 | **$0.095/秒** | $0.1406 | 32.4% |
+| 480p with video input | 11.5 /秒 | **$0.057/秒** | $0.0844 | 32.5% |
+| 720p no video input | 41 /秒 | **$0.205/秒** | $0.3024 | 32.2% |
+| 720p with video input | 25 /秒 | **$0.125/秒** | $0.1814 | 31.1% |
+| 1080p no video input | 102 /秒 | **$0.51/秒** | $0.6804 | 25.0% |
+| 1080p with video input | 62 /秒 | **$0.31/秒** | $0.4082 | 24.1% |
+| 4K no video input | 208 /秒 | **$1.04/秒** | $1.56 | 33.3% |
+| 4K with video input | 128 /秒 | **$0.64/秒** | $0.93 | 31.2% |
+
+> KIE 的计费说明：**无视频输入时 总价 = 单价 × 输出时长；有视频输入时 总价 = 单价 × (输入 + 输出) 时长**——这就是「with video」单价更低的原因。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
+- `generate_audio` 默认 `true`，会产生有声视频。
+- 参考图与首尾帧**共享 9 张的总额度**，UI 计数要把首帧/尾帧算进去。
+- `return_last_frame` 会改变 `resultJson` 的结构，解析逻辑必须分支处理。
+- `resolution` 档位是 480p / 720p / 1080p / 4k。
+- 有视频输入时计费口径变成「输入 + 输出总时长」，成本预估要区分。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Seedance 2.0 文档 | https://docs.kie.ai/cn/market/bytedance/seedance-2 | 否 |
+| 获取任务详情（含 return_last_frame 的结果结构） | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `seedance`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |

package/docs/model-adaptation/Seedance-2.0-Fast/Seedance-2.0-Fast_APIMart.md

@@ -0,0 +1,89 @@
+# Seedance 2.0 Fast · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | `seedance-2.0-fast` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> APIMart 把 `seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini` 写在**同一份文档**里，参数结构完全一致，差异在**分辨率上限**与**提示词长度**。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/videos/generations` → `{ code: 200, data: [{ status: "submitted", task_id }] }`
+- **查询**：`GET /v1/tasks/{task_id}`，状态 `pending` / `processing` / `completed` / `failed`，结果在 `result.videos[]`
+
+## 2. 能力清单
+
+文生视频、图生视频（首帧）、首尾帧视频、参考视频生视频、参考音频、有声视频、连续视频生成（返回尾帧）、联网搜索增强、私域虚拟人像素材（Asset URL）。**功能与标准版一致**。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | `seedance-2.0-fast` |
+| `prompt` | string | 条件 | — | **文生视频必填**；图生视频 / 视频参考生视频可选。限制 4000 字符，建议 500 字符以内 |
+| `duration` | integer | 可选 | `5` | **4 ~ 15 秒** |
+| `size` | string | 可选 | `16:9` | `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`。宽高比须在 0.5–2.5 之间 |
+| `resolution` | string | 可选 | `720p` | **仅 `480p` / `720p`**（`1080p` 与 `4k` 只有标准版 `seedance-2.0` 支持） |
+| `seed` | integer | 可选 | — | 随机种子。**本项目规则：绝对不显示**，不下发 |
+| `generate_audio` | boolean | 可选 | **`true`** | 是否生成配套音频 |
+| `return_last_frame` | boolean | 可选 | `false` | `true` 时额外返回尾帧图片 URL，用于连续视频生成 |
+| `tools` | array | 可选 | — | 如 `[{"type": "web_search"}]`（联网搜索） |
+| `image_urls` | string[] | 可选 | — | 图生视频参考图。普通 URL 或 `asset://asset_a`。**最多 9 张**。**与 `image_with_roles` 不能同时使用** |
+| `image_with_roles` | array | 可选 | — | `{ url, role }`，`role` ∈ `first_frame` / `last_frame` / `reference_image`。**与 `image_urls` 不能同时使用** |
+| `video_urls` | string[] | 可选 | — | 参考视频。**最多 3 个，1.8 s < 总时长 < 15.2 s，分辨率 480P ~ 720P**。**使用首/尾帧图片时不可用** |
+| `audio_urls` | string[] | 可选 | — | 参考音频。**最多 3 个，总时长 ≤ 15 s**。**必须与参考图片或参考视频一起用**；**使用首/尾帧图片时不可用** |
+| `nsfw_check` | boolean | 可选 | `false` | 命中时同步返回 HTTP 400（`nsfw_content_detected`），不建任务不扣费；审核不可用时 **fail-open**；`video_urls` / `audio_urls` **不送审** |
+
+### 互斥与依赖关系（务必在 UI 层做约束）
+
+- `image_urls` ⊗ `image_with_roles`（二选一）
+- 使用 `image_with_roles` 的首/尾帧时，`video_urls` 与 `audio_urls` **都不可用**
+- `audio_urls` 必须与参考图片或参考视频一起使用
+
+## 4. 私域虚拟人像素材（Asset URL）
+
+独立端点 `POST https://api.apimart.ai/v1/seedance2/private-avatar`，**支持全部 Seedance 2.0 模型**（含本模型）。字段与流程见 [Seedance-2.0_APIMart.md](../Seedance-2.0/Seedance-2.0_APIMart.md#4-私域虚拟人像素材asset-url)：素材组 `group` / `group_id`、`project_name`、`asset_type`（Image/Video/Audio）、`assets`（单次最多 20 个）；审核结果用 `GET /v1/tasks/{id}` 查询，通过的素材出现在 `result.usable_assets`，其 `asset_url` 可直接以 `asset://` 形式传入生成接口。
+
+## 5. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) → 视频标签页（2026-08-30 复核，1 Credit ≈ $0.1）。当前定价中心与模型页的秒价口径一致，未发现新的价格冲突。
+
+`SEEDANCE-2.0-FAST`（4 个档位）
+
+| 规格 | 我们的价格 |
+|---|---|
+| 480P | 0.3984 Credits/秒 ≈ **$0.03984/秒** |
+| 480P-input | 0.2368 Credits/秒 ≈ **$0.02368/秒** |
+| 720P | 0.856 Credits/秒 ≈ **$0.0856/秒** |
+| 720P-input | 0.5128 Credits/秒 ≈ **$0.05128/秒** |
+
+`-input` 档位对应「有参考视频输入」的计费方式（单价更低，但按输入 + 输出总时长计费）。
+
+**数字人（私域人像）另有独立价格** `SEEDANCE-2.0-FAST-FACE`：480P 0.8 Credits/秒 ≈ $0.08/秒、480P-input 0.48 ≈ $0.048/秒、720P 1.72 ≈ $0.172/秒、720P-input 1.032 ≈ $0.1032/秒。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 本接口**有 `seed`**（不下发）。
+- **参数互斥关系是这个模型最容易踩的坑**，UI 必须做互斥禁用。
+- `generate_audio` **默认 `true`**。
+- **`1080p` / `4k` 在本模型上不可用**，只有标准版 `seedance-2.0` 支持。
+- 有参考视频时计费按「输入 + 输出总时长」。
+- SDK 从 `uploadedVideoFilePaths` / `videos` / `uploadedVideos` 取非空且数量最完整的一组；空数组不遮蔽其他字段。宿主按顺序提供完整 `__videoDurationSeconds: number[]` 时求真实总和，数组不完整时改用 `__totalVideoDurationSeconds`，最后才兼容 `__firstVideoDurationSeconds × 视频数` 的旧近似估算。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| seedance-2.0 视频生成（三个版本共用文档） | https://docs.apimart.ai/cn/api-reference/videos/seedance-2-0/generation | 否 |
+| 虚拟人像素材（私域 Asset） | https://docs.apimart.ai/cn/api-reference/videos/seedance-2-0/private-avatar | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（视频标签页） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

package/docs/model-adaptation/Seedance-2.0-Fast/Seedance-2.0-Fast_Fal.md

@@ -0,0 +1,95 @@
+# Seedance 2.0 Fast · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `bytedance/seedance-2.0/fast/text-to-video`、`bytedance/seedance-2.0/fast/image-to-video`、`bytedance/seedance-2.0/fast/reference-to-video` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议（Fal 通用）
+
+- **鉴权**：`Authorization: Key $FAL_KEY`
+- **同步**：`POST https://fal.run/<endpoint-id>`；**队列**：`POST https://queue.fal.run/<endpoint-id>`，`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）、`GET .../requests/{id}`
+- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
+
+## 2. 能力清单（Fal 把每种输入形态拆成独立端点）
+
+| 能力 | endpoint id |
+|---|---|
+| 文生视频 | `bytedance/seedance-2.0/fast/text-to-video` |
+| 图生视频（首帧，可选尾帧） | `bytedance/seedance-2.0/fast/image-to-video` |
+| 参考生视频（图 / 视频 / 音频多模态） | `bytedance/seedance-2.0/fast/reference-to-video` |
+
+## 3. 请求参数
+
+### 3.1 三个端点共有
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 视频描述 |
+| `resolution` | string | 可选 | `720p` | **仅 `480p` / `720p`** |
+| `duration` | string | 可选 | **`auto`** | `auto`、`"4"` ~ `"15"`（**字符串枚举，不是数字**） |
+| `aspect_ratio` | string | 可选 | **`auto`** | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`（**7 个，没有 `adaptive`**） |
+| `generate_audio` | boolean | 可选 | **`true`** | 是否生成同步音频（音效、环境音、口型同步语音）。**开不开音频价格相同** |
+| `bitrate_mode` | string | 可选 | `standard` | `standard` / `high`（更高码率、更大文件） |
+| `end_user_id` | string | 可选 | — | 终端用户唯一 ID |
+
+### 3.2 仅 `image-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_url` | string | **必填** | 首帧图 URL。JPEG / PNG / WebP，**≤ 30 MB** |
+| `end_image_url` | string | 可选 | 尾帧图 URL；提供后视频从首帧过渡到尾帧。JPEG / PNG / WebP，≤ 30 MB |
+
+### 3.3 仅 `reference-to-video`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `image_urls` | string[] | 可选 | 参考图。**在 prompt 中用 `@Image1`、`@Image2` 引用**。JPEG / PNG / WebP，单张 ≤ 30 MB，**最多 9 张**。**所有模态的文件总数不得超过 12** |
+| `video_urls` | string[] | 可选 | 参考视频。prompt 中用 `@Video1` 引用。MP4 / MOV，**最多 3 个**，合计时长 2–15 s，总大小 < 50 MB，分辨率须在 ~480p (640×640) 与 ~720p (834×1112) 之间 |
+| `audio_urls` | string[] | 可选 | 参考音频。prompt 中用 `@Audio1` 引用。MP3 / WAV，**最多 3 个**，合计时长 ≤ 15 s，单个 ≤ 15 MB。**提供音频时必须至少有一张参考图或一个参考视频** |
+
+## 4. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" }, "seed": 42 }
+```
+
+`video` 与 `seed` 都是必返回字段。
+
+## 5. 价格
+
+来源：三个端点的 `llms.txt`（2026-08-22 读取）。
+
+| 项 | 价格 |
+|---|---|
+| 720p（按秒） | **$0.2419 / 秒** |
+| token 价 | **$0.0112 / 1000 tokens** |
+
+token 数计算：`(输出视频高 × 输出视频宽 × 时长 × 24) / 1024`。
+
+`reference-to-video` 有视频输入时：token 数按 `(高 × 宽 × (输入视频时长 + 输出视频时长) × 24) / 1024` 计算，且**价格 × 0.6**——有视频输入 + 720p 时约 **$0.14515 / 秒**。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 入参**没有 `seed`**（只在输出里回传），也没有负面提示词。
+- `duration` 是**字符串枚举**（`"5"` 而不是 `5`），与 APIMart / KIE 的整数不同，序列化时容易出错。
+- `aspect_ratio` 用 `auto` 表示自适应，APIMart / KIE 用 `adaptive`——名字不同，不能共用常量。
+- 三种输入形态在 Fal 上是**三个不同的 endpoint**，而 APIMart / KIE 是同一个 model 靠字段区分；适配层要按有无图 / 有无参考素材做端点路由。
+- `reference-to-video` 的 prompt 里要用 `@Image1` / `@Video1` / `@Audio1` 显式引用素材，这是 Fal 独有的约定。
+- 有视频输入时价格 × 0.6，但按「输入 + 输出总时长」计费。
+- `generate_audio` 默认 `true`，但开关不影响价格。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.0/fast/text-to-video/llms.txt | 否 |
+| 图生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.0/fast/image-to-video/llms.txt | 否 |
+| 参考生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.0/fast/reference-to-video/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |

package/docs/model-adaptation/Seedance-2.0-Fast/Seedance-2.0-Fast_KIE.md

@@ -0,0 +1,78 @@
+# Seedance 2.0 Fast · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `bytedance/seedance-2-fast` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "bytedance/seedance-2-fast", callBackUrl?, input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **终态**：`state` ∈ `waiting` / `queuing` / `generating` / `success` / `fail`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`；**开启 `return_last_frame` 时结构为 `{ resultUrls: [], firstFrameUrl: [], lastFrameUrl: [] }`**
+
+## 2. 能力清单
+
+KIE 把 Seedance 2.0 系列做成**单端点多能力**：有无首帧/尾帧/参考图/参考视频/参考音频，都在同一个 `model` 下靠字段区分。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 见说明 | — | 文本提示词。schema 标为可选但描述写「必填字段」，长度 3–**20000** 字符 |
+| `input.first_frame_url` | string | 可选 | — | 首帧图片地址，或 `asset://{assetId}` |
+| `input.last_frame_url` | string | 可选 | — | 尾帧图片地址，或 `asset://{assetId}` |
+| `input.reference_image_urls` | array | 可选 | — | 参考图，**最多 9 张**（**与首尾帧张数之和不得超过 9 张**）。格式 jpeg/png/webp/bmp/tiff/gif；宽高比 (0.4, 2.5)；边长 (300, 6000) px；单张 < 30 MB |
+| `input.reference_video_urls` | array | 可选 | — | 参考视频，**最多 3 个**。格式 mp4/mov；分辨率 480p/720p；单个时长 [2, 15] s 且总时长 ≤ 15 s；宽高比 [0.4, 2.5]；边长 [300, 6000] px；总像素 [409600, 927408]；单个 ≤ 50 MB；帧率 [24, 60] |
+| `input.reference_audio_urls` | array | 可选 | — | 参考音频，**最多 3 段**。格式 wav/mp3；单个时长 [2, 15] s 且总时长 ≤ 15 s；单个 ≤ 15 MB |
+| `input.return_last_frame` | boolean | 可选 | `false` | 是否返回视频最后一帧图片 |
+| `input.generate_audio` | boolean | 可选 | **`true`** | 是否生成与画面同步的音频 |
+| `input.resolution` | string | 可选 | `720p` | **仅 `480p` / `720p`** |
+| `input.aspect_ratio` | string | 可选 | `16:9` | `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`adaptive` |
+| `input.duration` | integer | 可选 | `5` | **4–15 秒** |
+| `input.web_search` | boolean | 可选 | — | 是否启用联网搜索 |
+| `input.nsfw_checker` | boolean | 可选 | `false` | `false` 时关闭内容过滤，结果直接返回 |
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://....mp4"] }`；开启 `return_last_frame` 时为 `{ "resultUrls": [], "firstFrameUrl": [], "lastFrameUrl": [] }`。
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `seedance`；1 Credit = $0.005）。
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| 480p no video input | 11.7 /秒 | **$0.059/秒** | $0.1125 | 47.6% |
+| 480p with video input | 6.8 /秒 | **$0.034/秒** | $0.0675 | 49.6% |
+| 720p no video input | 24.8 /秒 | **$0.124/秒** | $0.2419 | 48.7% |
+| 720p with video input | 15 /秒 | **$0.075/秒** | $0.1451 | 48.3% |
+
+> KIE 的计费说明：**无视频输入时 总价 = 单价 × 输出时长；有视频输入时 总价 = 单价 × (输入 + 输出) 时长**——这就是「with video」单价更低的原因。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
+- `generate_audio` 默认 `true`，会产生有声视频。
+- 参考图与首尾帧**共享 9 张的总额度**，UI 计数要把首帧/尾帧算进去。
+- `resolution` 档位是 480p / 720p。
+- 有视频输入时计费口径变成「输入 + 输出总时长」，成本预估要区分。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Seedance 2.0 Fast 文档 | https://docs.kie.ai/cn/market/bytedance/seedance-2-fast | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `seedance`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |