@henjicc/ai-sdk 0.8.0 → 0.10.0

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

@@ -1,94 +1,98 @@
-# Seedance 2.5 · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-30 |
-| 模态 | 视频 |
-| 供应商 | fal.ai（聚合平台） |
-| 平台模型 ID | `bytedance/seedance-2.5/text-to-video`、`bytedance/seedance-2.5/image-to-video`、`bytedance/seedance-2.5/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. 能力清单
-
-| 能力 | endpoint id |
-|---|---|
-| 文生视频 | `bytedance/seedance-2.5/text-to-video` |
-| 图生视频（首帧，可选尾帧） | `bytedance/seedance-2.5/image-to-video` |
-| 参考生视频（图 / 视频 / 音频多模态） | `bytedance/seedance-2.5/reference-to-video` |
-
-## 3. 请求参数
-
-### 3.1 三个端点共有
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `prompt` | string | 必填 | — | 视频描述 |
-| `resolution` | string | 可选 | `720p` | `480p` / `720p` / `1080p`（**无 4k**） |
-| `duration` | string | 可选 | `auto` | `auto`、`"4"` ~ **`"30"`**（**字符串枚举**，2.0 只到 `"15"`） |
-| `aspect_ratio` | string | 可选 | `auto` | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
-| `generate_audio` | boolean | 可选 | **`true`** | 是否生成同步音频 |
-| `bitrate_mode` | string | 可选 | `standard` | `standard` / `high` |
-| `end_user_id` | string | 可选 | — | 终端用户唯一 ID |
-
-### 3.2 仅 `image-to-video`
-
-`image_url`（必填，首帧图）、`end_image_url`（可选，尾帧图）。JPEG / PNG / WebP，≤ 30 MB。
-
-### 3.3 仅 `reference-to-video`
-
-`image_urls` / `video_urls` / `audio_urls`，在 prompt 中用 `@Image1` / `@Video1` / `@Audio1` 引用。
-
-> 具体上限以端点 `llms.txt` 为准（2.5 上游支持 30 图 / 10 视频 / 10 音频）。
-
-## 4. 响应结构
-
-```json
-{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" }, "seed": 42 }
-```
-
-## 5. 价格
-
-来源：三个端点的 `llms.txt`（2026-08-30 重新读取）。
-
-| 项 | 价格 |
-|---|---|
-| 720p（按秒，约） | **$0.4730 / 秒** |
-| 480p（按秒，约） | **$0.2205 / 秒** |
-| token 价（480p / 720p） | **$0.0214 / 1000 tokens** |
-| token 价（1080p，约） | **$0.0234 / 1000 tokens** |
-| 1080p 官方页秒价文案 | **约 $1.164 / 秒** |
-| 1080p 按同页 token 公式计算 | **约 $1.13724 / 秒** |
-
-token 数约为 `(输出视频高 × 输出视频宽 × 时长 × 24) / 1024`。
-
-> **官方价格冲突，暂不替供应商猜结论**：同一官方资料同时出现 1080p 约 `$1.164/秒`，以及 `$0.0234/1000 tokens`。按 1920×1080、24 fps 代入同页公式得到 `48,600 tokens/秒 × $0.0234/1000 = $1.13724/秒`，两者不一致。本次只记录冲突，不据此改动静态价格；后续应以 Fal pricing API 或真实 billing event 确认。
-
-`reference-to-video` 有视频输入时：token 数按 `(高 × 宽 × (输入视频时长 + 输出视频时长) × 24) / 1024`，且**价格 × 0.6**——有视频输入 + 720p 时约 **$0.2838 / 秒**。**有视频参考时输入与输出视频都要计费。**
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 入参没有 `seed`（只在输出里回传），也没有负面提示词。
-- `duration` 是**字符串枚举**且 2.5 支持到 `"30"`，与 2.0 的 `"15"` 上限不同。
-- `aspect_ratio` 用 `auto`，APIMart / KIE 用 `adaptive`。
-- Fal 上**没有 `output_format`（mov）、没有 `omni_reference_task_type`、没有 watermark**，视频编辑 / 延长这类子任务类型无法显式声明。
-- 三种输入形态是三个独立 endpoint，需要按有无图 / 有无参考素材路由。
-- 有视频输入时价格 × 0.6，但按「输入 + 输出总时长」计费。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| 文生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.5/text-to-video/llms.txt | 否 |
-| 图生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.5/image-to-video/llms.txt | 否 |
-| 参考生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.5/reference-to-video/llms.txt | 否 |
-| Fal 当前价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） |
-| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
-| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+# Seedance 2.5 · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `bytedance/seedance-2.5/text-to-video`、`bytedance/seedance-2.5/image-to-video`、`bytedance/seedance-2.5/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. 能力清单
+
+| 能力 | endpoint id |
+|---|---|
+| 文生视频 | `bytedance/seedance-2.5/text-to-video` |
+| 图生视频（首帧，可选尾帧） | `bytedance/seedance-2.5/image-to-video` |
+| 参考生视频（图 / 视频 / 音频多模态） | `bytedance/seedance-2.5/reference-to-video` |
+
+## 3. 请求参数
+
+### 3.1 三个端点共有
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 视频描述 |
+| `resolution` | string | 可选 | `720p` | `480p` / `720p` / `1080p`（**无 4k**） |
+| `duration` | string | 可选 | `auto` | `auto`、`"4"` ~ **`"30"`**（**字符串枚举**，2.0 只到 `"15"`） |
+| `aspect_ratio` | string | 可选 | `auto` | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
+| `generate_audio` | boolean | 可选 | **`true`** | 是否生成同步音频 |
+| `bitrate_mode` | string | 可选 | `standard` | `standard` / `high` |
+| `end_user_id` | string | 可选 | — | 终端用户唯一 ID |
+
+### 3.2 仅 `image-to-video`
+
+`image_url`（必填，首帧图）、`end_image_url`（可选，尾帧图）。JPEG / PNG / WebP，≤ 30 MB。
+
+### 3.3 仅 `reference-to-video`
+
+`image_urls` / `video_urls` / `audio_urls`，在 prompt 中用 `@Image1` / `@Video1` / `@Audio1` 引用。
+
+> 具体上限以端点 `llms.txt` 为准（2.5 上游支持 30 图 / 10 视频 / 10 音频）。
+
+## 4. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" }, "seed": 42 }
+```
+
+## 5. 价格
+
+来源：三个端点的 `llms.txt`（2026-08-30 重新读取）。
+
+| 项 | 价格 |
+|---|---|
+| 720p（按秒，约） | **$0.4730 / 秒** |
+| 480p（按秒，约） | **$0.2205 / 秒** |
+| token 价（480p / 720p） | **$0.0214 / 1000 tokens** |
+| token 价（1080p，约） | **$0.0234 / 1000 tokens** |
+| 1080p 官方页秒价文案 | **约 $1.164 / 秒** |
+| 1080p 按同页 token 公式计算 | **约 $1.13724 / 秒** |
+
+token 数约为 `(输出视频高 × 输出视频宽 × 时长 × 24) / 1024`。
+
+> **官方价格冲突，暂不替供应商猜结论**：同一官方资料同时出现 1080p 约 `$1.164/秒`，以及 `$0.0234/1000 tokens`。按 1920×1080、24 fps 代入同页公式得到 `48,600 tokens/秒 × $0.0234/1000 = $1.13724/秒`，两者不一致。本次只记录冲突，不据此改动静态价格；后续应以 Fal pricing API 或真实 billing event 确认。
+
+`reference-to-video` 有视频输入时：token 数按 `(高 × 宽 × (输入视频时长 + 输出视频时长) × 24) / 1024`，且**价格 × 0.6**——有视频输入 + 720p 时约 **$0.2838 / 秒**。**有视频参考时输入与输出视频都要计费。**
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 入参没有 `seed`（只在输出里回传），也没有负面提示词。
+- `duration` 是**字符串枚举**且 2.5 支持到 `"30"`，与 2.0 的 `"15"` 上限不同。
+- `aspect_ratio` 用 `auto`，APIMart / KIE 用 `adaptive`。
+- Fal 上**没有 `output_format`（mov）、没有 `omni_reference_task_type`、没有 watermark**，视频编辑 / 延长这类子任务类型无法显式声明。
+- 三种输入形态是三个独立 endpoint，需要按有无图 / 有无参考素材路由。
+- 有视频输入时价格 × 0.6，但按「输入 + 输出总时长」计费。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.5/text-to-video/llms.txt | 否 |
+| 图生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.5/image-to-video/llms.txt | 否 |
+| 参考生视频 schema + 价格 | https://fal.ai/models/bytedance/seedance-2.5/reference-to-video/llms.txt | 否 |
+| Fal 当前价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+
+## 2026-11-08 官方格式核对
+
+图生视频端点的 `aspect_ratio` 官方只收 `auto`：有首帧图时比例跟随图片，界面隐藏比例（2026-11-08 按官方 OpenAPI 核对）。来源：https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=<端点>（无需登录）。

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

@@ -1,89 +1,94 @@
-# Seedance 2.5 · KIE
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 视频 |
-| 供应商 | KIE.ai（聚合平台） |
-| 平台模型 ID | `bytedance/seedance-2-5` |
-| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.kie.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "bytedance/seedance-2-5", 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. 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `input.prompt` | string | 可选 | — | 文本提示词，最多 **30000** 字符 |
-| `input.first_frame_url` | string | 可选 | — | 首帧图片地址或 `asset://{assetId}`。**不能与 `reference_image_urls` / `reference_video_urls` / `reference_audio_urls` 同时使用** |
-| `input.last_frame_url` | string | 可选 | — | 尾帧图片地址或 `asset://{assetId}`。**不可单独只传 `last_frame_url`，必须同时传 `first_frame_url`** |
-| `input.reference_image_urls` | array | 可选 | — | 参考图，**最多 30 张**（与首尾帧张数之和不超过 30）。格式 jpeg/png/webp/bmp/tiff/gif；宽高比 (0.4, 2.5)；边长 (300, 6000) px；单张 < 30 MB。**与首尾帧场景互斥** |
-| `input.reference_video_urls` | array | 可选 | — | 参考视频，**最多 10 个**。格式 mp4/mov；分辨率 480p/720p；宽高比 [0.4, 2.5]；边长 [300, 6000] px；总像素 [409600, 927408]；单个 ≤ **200 MB**；帧率 [24, 60]；单个时长 [2, 30] s；**总时长 ≤ 30 s**。**与首尾帧场景互斥** |
-| `input.reference_audio_urls` | array | 可选 | — | 参考音频，**最多 10 段**。格式 wav/mp3；单个 ≤ 15 MB；单段时长 [2, 30] s；总时长 ≤ 30 s。**与首尾帧场景互斥** |
-| `input.return_last_frame` | boolean | 可选 | `false` | 是否返回视频最后一帧图片。**`draft=true` 时不支持传 `true`** |
-| `input.generate_audio` | boolean | 可选 | **`true`** | 是否生成与画面同步的音频 |
-| `input.resolution` | string | 可选 | `720p` | `480p` / `720p` / `1080p`（**无 4k**） |
-| `input.aspect_ratio` | string | 可选 | **`adaptive`** | `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`adaptive` |
-| `input.duration` | integer | 可选 | `5` | **4–30 秒**。特殊值 **`-1`**：自动选择时长——视频编辑任务下匹配输入视频时长，其他任务类型在有效范围内自主选择 |
-| `input.output_format` | string | 可选 | `mp4` | `mp4` / `mov` |
-| `input.web_search` | string | 可选 | — | 是否开启联网搜索（**schema 类型标注为 string，不是 boolean，接入前实测确认**） |
-| `input.nsfw_checker` | boolean | 可选 | `false` | `false` 时关闭内容过滤 |
-
-> KIE 的 schema 里出现了 `draft` 的说明（`return_last_frame` 描述提到 `draft=true`），但请求体中**没有 `draft` 字段**，接入前需确认。
-
-### 与 APIMart 的差异
-
-- KIE **没有 `omni_reference_task_type`**（APIMart 用它把编辑 / 延长的异步报错提前成同步报错）
-- KIE 没有 `watermark`、没有 `tools`（改为 `web_search` 布尔/字符串开关）
-- KIE 把首尾帧与参考素材做成**硬互斥**（APIMart 是自动降级为 `reference_image`）
-
-## 3. 响应结构
-
-`state=success` 后 `JSON.parse(resultJson)`：
-- 普通：`{ "resultUrls": ["https://....mp4"] }`
-- 开启 `return_last_frame`：`{ "resultUrls": [], "firstFrameUrl": [], "lastFrameUrl": [] }`
-
-## 4. 价格
-
-来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `seedance`；1 Credit = $0.005）。
-
-| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
-|---|---|---|---|---|
-| 480p no video | 28 /秒 | **$0.140/秒** | $0.2205 | 36.5% |
-| 480p with video | 17 /秒 | **$0.085/秒** | $0.1323 | 35.8% |
-| 720p no video | 63 /秒 | **$0.315/秒** | $0.4730 | 33.4% |
-| 720p with video | 38 /秒 | **$0.190/秒** | $0.2838 | 33.0% |
-| 1080p no video | 114 /秒 | **$0.570/秒** | $1.1372 | 49.9% |
-| 1080p with video | 68.5 /秒 | **$0.3425/秒** | $0.6823 | 49.8% |
-
-> 计费规则：**无视频输入时 总价 = 单价 × 输出时长；有视频输入时 总价 = 单价 × (输入 + 输出) 时长**。
-
-## 5. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
-- `output_format` 默认不显示、不请求。
-- **首尾帧与参考素材在 KIE 上是硬互斥**，UI 必须二选一，不能像 APIMart 那样自动降级。
-- `last_frame_url` 不能单独传，必须配 `first_frame_url`。
-- `aspect_ratio` 默认 `adaptive`（2.0 系列默认 `16:9`），跨代不能共用默认值。
-- `web_search` 的 schema 类型是 string 而非 boolean，接入前实测。
-- 有视频输入时计费按「输入 + 输出总时长」。
-- `resultJson` 是 JSON 字符串，必须二次 parse；`return_last_frame` 会改变结构。
-
-## 6. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Bytedance Seedance 2.5 | https://docs.kie.ai/cn/market/bytedance/seedance-2-5 | 否 |
-| 获取任务详情（含 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 | **是** |
+# Seedance 2.5 · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `bytedance/seedance-2-5` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "bytedance/seedance-2-5", 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. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | 可选 | — | 文本提示词，最多 **30000** 字符 |
+| `input.first_frame_url` | string | 可选 | — | 首帧图片地址或 `asset://{assetId}`。**不能与 `reference_image_urls` / `reference_video_urls` / `reference_audio_urls` 同时使用** |
+| `input.last_frame_url` | string | 可选 | — | 尾帧图片地址或 `asset://{assetId}`。**不可单独只传 `last_frame_url`，必须同时传 `first_frame_url`** |
+| `input.reference_image_urls` | array | 可选 | — | 参考图，**最多 30 张**（与首尾帧张数之和不超过 30）。格式 jpeg/png/webp/bmp/tiff/gif；宽高比 (0.4, 2.5)；边长 (300, 6000) px；单张 < 30 MB。**与首尾帧场景互斥** |
+| `input.reference_video_urls` | array | 可选 | — | 参考视频，**最多 10 个**。格式 mp4/mov；分辨率 480p/720p；宽高比 [0.4, 2.5]；边长 [300, 6000] px；总像素 [409600, 927408]；单个 ≤ **200 MB**；帧率 [24, 60]；单个时长 [2, 30] s；**总时长 ≤ 30 s**。**与首尾帧场景互斥** |
+| `input.reference_audio_urls` | array | 可选 | — | 参考音频，**最多 10 段**。格式 wav/mp3；单个 ≤ 15 MB；单段时长 [2, 30] s；总时长 ≤ 30 s。**与首尾帧场景互斥** |
+| `input.return_last_frame` | boolean | 可选 | `false` | 是否返回视频最后一帧图片。**`draft=true` 时不支持传 `true`** |
+| `input.generate_audio` | boolean | 可选 | **`true`** | 是否生成与画面同步的音频 |
+| `input.resolution` | string | 可选 | `720p` | `480p` / `720p` / `1080p`（**无 4k**） |
+| `input.aspect_ratio` | string | 可选 | **`adaptive`** | `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`adaptive` |
+| `input.duration` | integer | 可选 | `5` | **4–30 秒**。特殊值 **`-1`**：自动选择时长——视频编辑任务下匹配输入视频时长，其他任务类型在有效范围内自主选择 |
+| `input.output_format` | string | 可选 | `mp4` | `mp4` / `mov` |
+| `input.web_search` | boolean | 可选 | — | 是否开启联网搜索（官方 OpenAPI 早期标为 string，2026-11-08 复查已改为 boolean） |
+| `input.nsfw_checker` | boolean | 可选 | `false` | `false` 时关闭内容过滤 |
+
+> KIE 的 schema 里出现了 `draft` 的说明（`return_last_frame` 描述提到 `draft=true`），但请求体中**没有 `draft` 字段**，接入前需确认。
+
+### 与 APIMart 的差异
+
+- KIE **没有 `omni_reference_task_type`**（APIMart 用它把编辑 / 延长的异步报错提前成同步报错）
+- KIE 没有 `watermark`、没有 `tools`（改为 `web_search` 布尔开关）
+- KIE 把首尾帧与参考素材做成**硬互斥**（APIMart 是自动降级为 `reference_image`）
+
+## 3. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)`：
+- 普通：`{ "resultUrls": ["https://....mp4"] }`
+- 开启 `return_last_frame`：`{ "resultUrls": [], "firstFrameUrl": [], "lastFrameUrl": [] }`
+
+## 4. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `seedance`；1 Credit = $0.005）。
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| 480p no video | 28 /秒 | **$0.140/秒** | $0.2205 | 36.5% |
+| 480p with video | 17 /秒 | **$0.085/秒** | $0.1323 | 35.8% |
+| 720p no video | 63 /秒 | **$0.315/秒** | $0.4730 | 33.4% |
+| 720p with video | 38 /秒 | **$0.190/秒** | $0.2838 | 33.0% |
+| 1080p no video | 114 /秒 | **$0.790/秒** | $1.1372 | 49.9% |
+| 1080p with video | 68.5 /秒 | **$0.475/秒** | $0.6823 | 49.8% |
+
+> 计费规则：**无视频输入时 总价 = 单价 × 输出时长；有视频输入时 总价 = 单价 × (输入 + 输出) 时长**。
+
+## 5. 适配要点
+
+- 素材尺寸前置校验（2026-11-08）：`imageConstraints` 边长 300–6000 px、宽高比 0.4–2.5；`videoConstraints` 边长 300–6000 px、总像素 409,600–927,408、宽高比 0.4–2.5。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
+- `output_format` 默认不显示、不请求。
+- **首尾帧与参考素材在 KIE 上是硬互斥**，UI 必须二选一，不能像 APIMart 那样自动降级。
+- `last_frame_url` 不能单独传，必须配 `first_frame_url`。
+- `aspect_ratio` 默认 `adaptive`（2.0 系列默认 `16:9`），跨代不能共用默认值。
+- `web_search` 按官方 OpenAPI 发布尔值（早期文档写 string，已更正）。
+- 有视频输入时计费按「输入 + 输出总时长」。
+- `resultJson` 是 JSON 字符串，必须二次 parse；`return_last_frame` 会改变结构。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Bytedance Seedance 2.5 | https://docs.kie.ai/cn/market/bytedance/seedance-2-5 | 否 |
+| 获取任务详情（含 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 | **是** |
+
+## 2026-10-12 价格复核
+
+本次按 t170 已确认表更新 calculator 与基础报价；输入视频计费公式不变。官方来源：[https://kie.ai/pricing](https://kie.ai/pricing)（公开无需登录），不使用会员专属折扣或第三方对比列。

package/docs/model-adaptation/Seedance-2.5/Seedance-2.5_/347/201/253/345/261/261/345/274/225/346/223/216.md

@@ -0,0 +1,102 @@
+# Seedance 2.5 · 火山引擎
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 视频 |
+| 供应商 | 火山方舟（官方） |
+| 项目模型 ID | `volcengine-seedance-2.5`（通用标识 `seedance-2.5`） |
+| 平台模型 ID | `doubao-seedance-2-5-260628` |
+| 接口形态 | 异步任务（提交 + 轮询） |
+| 文档 / 价格可见性 | 公开，无需登录；开通 Seedance 2.x 需账户余额 > 200 元、200 元以上节省计划或资源包余量 |
+
+## 1. 接入协议
+
+- Base URL：`https://ark.cn-beijing.volces.com`；鉴权 `Authorization: Bearer <ARK_API_KEY>`
+- 提交：`POST /api/v3/contents/generations/tasks` → `{ "id": "cgt-..." }`（响应只有 `id`）
+- 查询：`GET /api/v3/contents/generations/tasks/{id}`；任务 ID 有效期 7 天，结果 URL 24 小时有效（Seedance 2.5 URL 最多下载 100 次），项目按统一媒体转存链路落盘
+- 取消：`DELETE /api/v3/contents/generations/tasks/{id}` 只能取消 `queued` 任务，`running` 不可取消。SDK 取消只停止本地轮询，不调用 DELETE
+
+## 2. 能力（按传入素材区分，三类互斥不可混用）
+
+| 场景 | content |
+|---|---|
+| 文生视频 | 仅 `text` |
+| 首帧 | 1 个 `image_url`，`role: first_frame`（或不填） |
+| 首尾帧 | 2 个 `image_url`，`role` 必填 `first_frame` / `last_frame`；尾帧比例不一致时以首帧为准裁剪 |
+| 全模态参考 | `image_url` + `role: reference_image`、`audio_url` + `role: reference_audio`、`video_url` + `role: reference_video`；参考图 1–30 张、参考音频最多 10 段（单段 2–30 秒，总 ≤ 30 秒），可只传音频 |
+
+图片支持公网 URL、`data:image/<格式>;base64,` 与 `asset://`；单张 < 30 MB，宽高比 0.4–2.5，边长 300–6000 px，请求体 ≤ 64 MB。音频支持公网 URL、`data:audio/<格式>;base64,`（格式 wav / mp3）与 `asset://`；单段 ≤ 15 MB。**参考视频只收公网 URL 或 `asset://`，不收 Base64**：最多 10 段，单段 2–30 秒（编辑任务 4–30 秒），合计 ≤ 30 秒，mp4 / mov，单个 ≤ 200 MB，24–60 fps。本地视频经设置里的“通用文件上传服务”（KIE / Fal）托管成公网地址后提交，一家都没配置时提交前提示去设置；2.5 另有 `omni_reference_task_type`（项目「任务类型」：自动 / 参考生成 / 视频编辑 / 视频延长），编辑与延长至少一段参考视频、`ratio` 必须 `adaptive`，编辑的 `duration` 必须 `-1`。
+
+不支持直接上传含真人人脸的参考图 / 视频（需走官方授权素材或虚拟人像库）。
+
+## 3. 请求参数
+
+| 字段 | 取值 | 项目处理 |
+|---|---|---|
+| `model` | `doubao-seedance-2-5-260628` | 固定 |
+| `content` | 见第 2 节 | 提示词为空时不发 text 项；文生视频必须有提示词 |
+| `resolution` | `480p` / `720p` / `1080p`（1080p 为 10bit H.265）；默认 `720p` | 始终显式发送 |
+| `ratio` | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`；默认 `adaptive` | 「智能」发 `adaptive` |
+| `duration` | 4–30，或 `-1` 智能时长（官方默认 `-1`） | 4 起，默认 5 |
+| `generate_audio` | boolean，默认 true；输出固定双声道 | 开关 |
+| `return_last_frame` | boolean，默认 false；为 true 时结果多一个 `content.last_frame_url`（jpeg，无水印） | 开关；结果按「视频 ‖ 尾帧」顺序返回 |
+| `tools` | `[{ "type": "web_search" }]` | 「联网搜索」开关 |
+| `watermark` | boolean，默认 false | 固定 false |
+| `seed`、`camera_fixed`、`frames`、`service_tier` | 仅 Seedance 1.0 系列 | 不发送 |
+
+## 4. 价格
+
+来源：[模型价格](https://www.volcengine.com/docs/82379/1544106)（官方更新时间 2026-11-03，2026-11-07 读取，无需登录），在线推理，元 / 百万 token：
+
+| 输出分辨率 | 输入不含视频 | 输入含视频 |
+|---|---|---|
+| 480p / 720p | ¥70 | ¥42 |
+| 1080p | ¥77 | ¥46 |
+
+- 视频价格 = token 单价 × token 用量；token ≈ (输入视频时长 + 输出时长) × 输出宽 × 输出高 × 24 / 1024，准确值以查询结果 `usage.completion_tokens` 为准；仅成功生成计费。
+- 典型价：480p 16:9 5 秒 ¥3.36；720p ¥7.56；1080p ¥18.71（官方「价格示例」）。
+- 不带参考视频时按「输入不含视频」单价；带参考视频时按「输入含视频」单价，token 用量计入输入视频时长（读不到时长按输出时长估、封顶合计上限；2.5 编辑任务输出时长按输入时长估）。像素按官方表与所选比例，智能比例按 16:9。含视频时官方另有最低 token 用量（与分辨率、比例、输出时长有关，官方给的是飞书表格与计算器）：价格示例中输入 2–4 秒同价、与按输入 4 秒算出的 token 一致（如 2.0 480p 16:9 输出 5 秒：(4+5)×864×496×24/1024×¥28/百万 = ¥2.53），项目按“输入视频不足 4 秒按 4 秒计”估算。
+
+## 5. 事件 / 状态矩阵
+
+| 状态 | 前置 | 字段契约 | 空值语义 | 下一状态 | 对外输出 | 终态 / 错误 |
+|---|---|---|---|---|---|---|
+| 提交成功 | — | `id` string 必有 | 缺 `id` 判 `invalid_response` | queued | pending + taskId | 否 |
+| 提交失败 | — | HTTP 4xx/5xx，`error.code` / `error.message` | — | — | 无 | 是；余额、未开通、无权限按 `providerAccessErrors` 归类为不可重试 |
+| `queued` | 提交 | `status`；`content` 可缺 | 无结果 | running / cancelled / expired | 无 | 否，继续查询 |
+| `running` | queued | 同上 | 无结果 | succeeded / failed / expired | 无 | 否，继续查询 |
+| `succeeded` | running | `content.video_url` 必有；`content.last_frame_url` 仅 `return_last_frame` 时有；`usage.completion_tokens` | `video_url` 缺失判 `empty_result` | — | completed，URL 为视频（+ 尾帧） | 是 |
+| `failed` | queued / running | `error.code` / `error.message`（成功时 `error` 为 null） | `error` 缺失时用固定原因 | — | 无 | 是，`provider_task_failed`，不续查 |
+| `cancelled` | queued | — | — | — | 无 | 是；记录 24 小时后自动删除 |
+| `expired` | queued / running | `execution_expires_after`（默认 172800 秒） | 官方无 error 示例 | — | 无 | 是 |
+| 缺 `status` / 查询 HTTP 5xx / 网络错误 | 任意 | — | — | 保持 | 无 | 计入连续查询失败，连续 20 次后 `provider_task_unreachable` |
+
+不变量：只有 `succeeded` 且带 `video_url` 才算有效 final；用户取消时停止计时器与查询，不发 DELETE；官方未说明是否会乱序回退状态，SDK 不依赖状态顺序，只看当次状态。Seedance 2.5 部分任务类型要排到被消费时才返回报错（官方「报错机制」），因此失败可能在 `queued` 之后很久才出现。
+
+## 6. 项目适配
+
+- 素材尺寸前置校验（2026-11-08）：`imageConstraints` 边长 300–6000 px、宽高比 0.4–2.5；文档未写参考视频尺寸，不校验视频。提交前读取素材实际宽高，不合格直接提示，不发付费请求。
+- 产品模型 `volcengine-seedance-2.5`，参数交互与 APIMart 同家族入口一致：`role: 'mode'` 模式（文/图生视频、参考生视频）+ 比例 + 分辨率 + 时长 + 声音 / 尾帧 / 联网搜索开关。
+- 2.5 首帧 / 首尾帧任务只接受 `ratio: "adaptive"`，SDK 在有首帧时强制发 `adaptive`。
+- 参考模式默认显式发 `omni_reference_task_type: "reference"`（项目「任务类型」默认“参考生成”），提交时即校验限制，也避免 `auto` 因提示词里的“替换 / 删除”被判成编辑任务后异步失败；选“视频编辑 / 视频延长”时至少一段参考视频、比例固定 `adaptive`，编辑的时长固定 `-1` 并隐藏时长控件；“自动判断”放在最后。
+- 「自动时长」开关发 `duration: -1`，计价按 30 秒预估。
+- 未接入：`draft` 样片模式、`output_format: mov`（产品约定不暴露输出格式）、`priority`、`callback_url`、`execution_expires_after`、`safety_identifier`。
+- 本地图片、音频由方舟官方支持的 Data URI 发送；本地读出的 `audio/mpeg`、`audio/x-wav` 等 MIME 在发送前改成官方格式名 `mp3` / `wav`。
+- Fixture：`packages/ai-sdk/tests/fixtures/volcengine/video-*.json`；状态迁移与取消测试：`packages/ai-sdk/tests/providers/video-async-official.test.ts`；请求构建与价格：`packages/ai-sdk/tests/catalog/official-videos.test.ts`。未做真实付费调用。
+
+- 界面与请求一致（2026-11-08“所选即所发”离线检查）：首帧 / 首尾帧与编辑、延长任务只接受 adaptive，比例参数在这些情况下隐藏。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 创建视频生成任务 API | https://www.volcengine.com/docs/82379/1520757 | 否 |
+| 查询视频生成任务 API | https://www.volcengine.com/docs/82379/1521309 | 否 |
+| 取消或删除视频生成任务 | https://www.volcengine.com/docs/82379/1521720 | 否 |
+| 模型列表（模型 ID、分辨率、时长、限流） | https://www.volcengine.com/docs/82379/1330310 | 否 |
+| 模型价格 | https://www.volcengine.com/docs/82379/1544106 | 否 |
+| 错误码 | https://www.volcengine.com/docs/82379/1299023 | 否 |
+| Seedance 2.5 教程 / 2.0 系列教程 | https://www.volcengine.com/docs/82379/2607688 ; https://www.volcengine.com/docs/82379/2291680 | 否 |
+
+> 机器可读原文：`https://docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=<id>&type=online`。

package/docs/model-adaptation/Seedream-5.0-Flash/Seedream-5.0-Flash_APIMart.md

@@ -0,0 +1,64 @@
+# Seedream 5.0 Flash · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 项目模型 ID | `apimart-seedream-5.0-flash`（通用标识 `seedream-5.0-flash`，与 `volcengine-seedream-5.0-flash` 相同） |
+| 平台模型 ID | `seedream-5-0-flash` |
+| 接口形态 | 异步任务 |
+| 文档 / 价格可见性 | 公开，无需登录 |
+
+## 1. 接入协议
+
+- 提交：`POST /v1/images/generations` → `data[0].task_id`
+- 查询：`GET /v1/tasks/{task_id}`，完成后读 `data.result.images[]`；链接有效 72 小时
+
+## 2. 能力
+
+单图模型：文生图、图生图、最多 10 张参考图融合；提示词内 `<point>` / `<bbox>` 坐标或手绘标记图做交互编辑。`n > 1`、`sequential_image_generation`、`stream`、`tools`、超过 10 张参考图直接 400。
+
+## 3. 请求参数
+
+| 字段 | 取值 | 说明 |
+|---|---|---|
+| `model` | `seedream-5-0-flash` | 必填 |
+| `prompt` | string | 必填（图层拆分可省略） |
+| `resolution` | `1K`（默认）/ `1.5K` / `2K` | 1.5K 与 1K 同价 |
+| `size` | `auto` / `1:1` `4:3` `3:4` `16:9` `9:16` `3:2` `2:3` `2:1` `1:2` `21:9` / 精确像素 | 列表外比例返回 400；精确像素时忽略 `resolution` |
+| `image_urls` | ≤ 10，公网 URL 或小写格式的 Data URI | 单张 ≤ 30 MB、宽高比 1/16–16 |
+| `background` | `opaque` / `transparent` | 透明只用于恰好 1 张带透明通道输入图的图生图，且需 png；项目不请求 |
+| `layer_decomposition` | boolean | 见第 4 节冲突说明；项目不接入 |
+| `optimize_prompt_options` | `{ mode: "standard" }` | 项目不请求 |
+| `output_format` | `jpeg` / `png` | 项目不请求 |
+| `watermark` / `nsfw_check` | 默认 false | 项目不请求 |
+| `n` | 只能 1 | 项目固定 1 |
+
+1K 档像素：1:1 1024×1024、16:9 1312×736；1.5K：1:1 1536×1536、16:9 2048×1152；2K：1:1 2048×2048、16:9 2560×1440。
+
+## 4. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing) 图像区 `seedream-5-0-flash`（1 个价格档位）与 [Seedream 5.0 Flash 模型页](https://apimart.ai/zh/model/seedream-5-0-flash)（2026-11-07 读取，黄金价 = 当前价）。
+
+| 规格 | 单价 |
+|---|---|
+| 1K / 1.5K / 2K | $0.01371 / 张（0.1371 Credits） |
+
+模型页说明“所有尺寸（1K/1.5K/2K 或精确像素）统一单张价格，单价低于 Seedream 5.0 Pro”。
+
+**文档冲突（保留不采纳）**：API 文档“计费说明”写 ≤ 2.61M 像素 $0.045 / 张、> 2.61M $0.09 / 张，并称第 2 张起参考图另计加价——这组数字与 Seedream 5.0 Pro 文档相同，定价中心与模型页都只给出统一 $0.01371，按“实时价格页优先于 API 文档正文”采用后者；参考图加价单价在定价中心没有列出，项目估价不含该项。API 文档描述了图层拆分，但模型页常见问题称“Pro 提供 Flash 不支持的图层拆分”，两处冲突且拆分无独立价格，项目暂不接入图层拆分。
+
+## 5. 项目适配
+
+- 参考 `apimart-seedream-5.0-lite` / `-pro` 结构，只保留比例与分辨率两个通用参数。
+- 比例默认“智能”：按首图比例取最近支持比例，无图回退 `1:1`，始终发具体比例。
+- 分辨率默认 1.5K（与 1K 同价、画质更好）。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| API 文档 | https://docs.apimart.ai/cn/api-reference/images/seedream-5-0-flash/generation | 否 |
+| 模型页（价格、与 Pro / Lite 的区别） | https://apimart.ai/zh/model/seedream-5-0-flash | 否 |
+| 定价中心 | https://apimart.ai/zh/pricing | 否 |

package/docs/model-adaptation/Seedream-5.0-Flash/Seedream-5.0-Flash_/347/201/253/345/261/261/345/274/225/346/223/216.md

@@ -1,18 +1,18 @@
-# Seedream 5.0 Flash · 火山方舟
-
-核对日期：2026-09-24；公开无需登录，未执行付费生成。
-
-来源：[发布公告](https://docs.volcengine.com/docs/ark/model-release-announcement?lang=zh)、[Pro / Flash 教程](https://docs.volcengine.com/docs/ark/seedream-5-0-pro?lang=zh)、[价格](https://docs.volcengine.com/docs/ark/model-pricing?lang=zh)。官方明确基础调用只替换 Model ID，公共契约复用 Pro 实现。
-
-- Model ID：`doubao-seedream-5-0-flash-260915`；`POST https://ark.cn-beijing.volces.com/api/v3/images/generations`，Bearer 认证。
-- 文生、图生/多图参考、交互编辑、图层拆分；输入上限 10 张，拆分必须 1 张；1K/1.5K/2K，PNG/JPEG；Flash 只支持标准提示词优化。
-- SDK 沿用 Pro 的生成/编辑与拆分模式、图片上传、智能比例和结构化图层输出。旧 Pro 参数名与模型 ID 保持不变。
-- 输入图免费，输出 ¥0.12/张；拆分数量只有返回后可知，提交前返回不可估算，不能显示 ¥0.12 为整单总价。
-
-| 响应 | 字段与行为 |
-|---|---|
-| 同步成功 | `data` 图片数组，`url` 字符串；由共享图片适配器收集 URL |
-| 图层拆分 | 与 Pro 相同的 layers/base-image 元数据，经 `parseSeedreamLayerStack` 返回结构化图层 |
-| 错误、缺失产物、取消 | 沿共享 Volcengine provider 失败收口；不把空结果当成功，不建立重复收费重试 |
-
-官方字面调用中的 Pro Model ID 可按同页明确说明替换成 Flash；测试将此区别标为官方字段构造，不能冒充 Flash 真网样本。共享 Pro 正反测试继续运行，新增 Flash 定向验证模型路由、图片限制、价格和拆分不可估算。
+# Seedream 5.0 Flash · 火山方舟
+
+核对日期：2026-09-24；公开无需登录，未执行付费生成。
+
+来源：[发布公告](https://docs.volcengine.com/docs/ark/model-release-announcement?lang=zh)、[Pro / Flash 教程](https://docs.volcengine.com/docs/ark/seedream-5-0-pro?lang=zh)、[价格](https://docs.volcengine.com/docs/ark/model-pricing?lang=zh)。官方明确基础调用只替换 Model ID，公共契约复用 Pro 实现。
+
+- Model ID：`doubao-seedream-5-0-flash-260915`；`POST https://ark.cn-beijing.volces.com/api/v3/images/generations`，Bearer 认证。
+- 文生、图生/多图参考、交互编辑、图层拆分；输入上限 10 张，拆分必须 1 张；1K/1.5K/2K，PNG/JPEG；Flash 只支持标准提示词优化。
+- SDK 沿用 Pro 的生成/编辑与拆分模式、图片上传、智能比例和结构化图层输出。旧 Pro 参数名与模型 ID 保持不变。
+- 输入图免费，输出 ¥0.12/张；拆分数量只有返回后可知，提交前返回不可估算，不能显示 ¥0.12 为整单总价。
+
+| 响应 | 字段与行为 |
+|---|---|
+| 同步成功 | `data` 图片数组，`url` 字符串；由共享图片适配器收集 URL |
+| 图层拆分 | 与 Pro 相同的 layers/base-image 元数据，经 `parseSeedreamLayerStack` 返回结构化图层 |
+| 错误、缺失产物、取消 | 沿共享 Volcengine provider 失败收口；不把空结果当成功，不建立重复收费重试 |
+
+官方字面调用中的 Pro Model ID 可按同页明确说明替换成 Flash；测试将此区别标为官方字段构造，不能冒充 Flash 真网样本。共享 Pro 正反测试继续运行，新增 Flash 定向验证模型路由、图片限制、价格和拆分不可估算。