@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/Gemini-Omni-Flash/Gemini-Omni-Flash_APIMart.md

@@ -0,0 +1,124 @@
+# Gemini Omni Flash · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | **两条独立渠道**：`gemini-omni-flash-preview`（官方直连）与 `Omni-Flash-Ext` |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> APIMart 上 Gemini Omni Flash 是两个平台模型、两份文档，能力集合与限制差异很大；Henji 产品中统一为一个“Gemini Omni Flash”入口，通过首项“渠道”（普通 / 官方）切换，运行时仍严格按各渠道契约、价格和限制分支。
+
+## 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}`
+- **轮询建议**（`Omni-Flash-Ext` 文档）：提交后等 **5–10 秒**再开始查询，之后每 5–10 秒一次；**单个任务通常约 3–5 分钟完成**
+
+---
+
+## 2. 渠道 A：`gemini-omni-flash-preview`（Google 官方直连）
+
+Google 官方 Gemini Omni Flash 全能多模态视频生成模型。支持文生视频、图生视频、**视频生视频（编辑）**，可混合文本 + 图片 + 视频输入。输出 **720p / 24fps / 3–10 秒 / 含音频**；支持**对话式多轮编辑**。
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | 固定 `gemini-omni-flash-preview` |
+| `prompt` | string | 必填 | — | 文本指令。文生视频为场景描述；图/视频生视频为动作/风格/编辑指令。**`prompt` 与参考素材（`image_urls` / `video_urls`）至少提供其一** |
+| `image_urls` | array | 可选 | — | 参考图，**最多 16 张**。`http(s)://` URL，支持 JPEG / PNG。多主体可传多张并在 prompt 中描述互动 |
+| `video_urls` | array | 可选 | — | 参考 / 待编辑视频，**最多 1 个**（不支持多视频引用）。`http(s)://` 直链或 `data:video/...`。**参考视频 1–24 秒，官方建议 ≤ 3 秒**。**与 `extend_from_task_id` 互斥** |
+| `aspect_ratio` | string | 可选 | `16:9` | **仅 `16:9` / `9:16`**，其它值按 `16:9` 处理。**传入 `video_urls` 后本参数失效** |
+| `resolution` | string | 可选 | `720p` | **当前仅支持 `720p`** |
+| `extend_from_task_id` | string | 可选 | — | 上一次生成任务的 `task_id`（对话式多轮编辑）。**与 `video_urls` 互斥** |
+| `nsfw_check` | boolean | 可选 | `false` | 提交前内容审核 |
+
+### 价格（`GEMINI-OMNI-FLASH-PREVIEW`）
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)（2026-08-22，1 个档位）。
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 720P | 0.88 Credits/秒 ≈ **$0.088/秒** | $0.11 | 20% |
+
+---
+
+## 3. 渠道 B：`Omni-Flash-Ext`
+
+统一视频生成模型。支持文生视频、单图生视频、**参考视频**和 **3 张参考图融合**；支持 **720p / 1080p / 4k**，**4 / 6 / 8 / 10 秒**。
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | — | 固定 `Omni-Flash-Ext` |
+| `prompt` | string | 必填 | — | 建议详细描述场景、人物、动作、环境、镜头运动、画面风格和**音频提示** |
+| `duration` | integer | 可选 | `6` | **仅支持 `4`、`6`、`8`、`10`**；传 5、7 等返回 `invalid_duration`。**传入 `video_urls` 时不需要也不能同时传 `duration`** |
+| `resolution` | string | 可选 | `720p` | `720p` / `1080p` / `4k`（**不区分大小写**）；其它返回 `invalid_resolution` |
+| `aspect_ratio` | string | 可选 | `16:9` | `16:9` / `9:16` |
+| `size` | string | 可选 | — | 兼容字段，含义同 `aspect_ratio`；同时传入时建议保持一致 |
+| `generation_type` | string | 可选 | — | `frame`（首帧模式，`image_urls` **只能 1 张**）/ `reference`（参考模式，`image_urls` **可 1 张或 3 张**） |
+| `image_urls` | array | 可选 | — | 可不传（文生视频）/ 1 张（单图生视频）/ 3 张（参考图融合，仅 `generation_type=reference`）。**不支持 2 张图的首尾帧模式**，传 2 张返回 `unsupported_image_count`；4 张及以上未实测验证，不建议使用。只支持公网可访问 URL |
+| `video_urls` | array | 可选 | — | **0 或 1 个**参考视频；2 个及以上返回 `unsupported_video_count`。**可与 `image_urls` 同时传入**（图片作身份/构图参考，视频作动态参考）。只支持公网 HTTP/HTTPS URL |
+| `nsfw_check` | boolean | 可选 | `false` | 提交前内容审核 |
+
+### 错误码
+
+| HTTP | 错误类型 | 含义 | 处理建议 |
+|---|---|---|---|
+| 400 | `invalid_request_error` | `model` 不是 `Omni-Flash-Ext`、`prompt` 为空或 JSON 格式错误 | 检查请求体 |
+| 400 | `invalid_duration` | `duration` 不是 4/6/8/10 | 改成支持的时长 |
+| 400 | `invalid_resolution` | `resolution` 不是 720p/1080p/4k | 改成支持的分辨率 |
+| 400 | `unsupported_image_count` | `image_urls` 数量不受支持（常见于传 2 张） | 改成 0、1 或 3 张 |
+| 400 | `unsupported_video_count` | `video_urls` 传了 2 个及以上 | 改成 0 或 1 个 |
+| 401 | `authentication_error` | Token 无效 | 检查 Bearer Token |
+| 402 | `payment_required` | 余额不足 | 充值后重试 |
+| 429 | `rate_limit_error` | 触发限流 | 降低并发或稍后重试 |
+
+任务失败时，任务查询接口在 `data.error` 返回失败原因，常见为上游配额暂时耗尽、内容审核未通过或上游超时。
+
+### 价格（`OMNI-FLASH-EXT`）
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)（2026-08-22，**16 个档位，按次计费**，1 Credit ≈ $0.1）。
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 | 3.5 Credits/次 ≈ **$0.35/次** | $0.4375 | 20% |
+| 720P-4S | 2.5 ≈ **$0.25/次** | $0.3125 | 20% |
+| 720P-6S | 3 ≈ **$0.3/次** | $0.375 | 20% |
+| 720P-8S | 3.5 ≈ **$0.35/次** | $0.4375 | 20% |
+| 720P-10S | 4 ≈ **$0.4/次** | $0.5 | 20% |
+| 720P-VIDREF | 0.8 ≈ **$0.08/次** | $0.1 | 20% |
+| 1080P-4S | 2.5 ≈ **$0.25/次** | $0.3125 | 20% |
+| 1080P-6S | 3 ≈ **$0.3/次** | $0.375 | 20% |
+| 1080P-8S | 3.5 ≈ **$0.35/次** | $0.4375 | 20% |
+| 1080P-10S | 4 ≈ **$0.4/次** | $0.5 | 20% |
+| 1080P-VIDREF | 0.8 ≈ **$0.08/次** | $0.1 | 20% |
+| 4K-4S | 7.5 ≈ **$0.75/次** | $0.9375 | 20% |
+| 4K-6S | 8 ≈ **$0.8/次** | $1 | 20% |
+| 4K-8S | 8.5 ≈ **$0.85/次** | $1.0625 | 20% |
+| 4K-10S | 9 ≈ **$0.9/次** | $1.125 | 20% |
+| 4K-VIDREF | 2.4 ≈ **$0.24/次** | $0.3 | 20% |
+
+> **按次计费**（不是按秒），且 720P 与 1080P 同价；`VIDREF`（有参考视频）档位便宜很多。
+
+## 4. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 这两条渠道都没有这两个字段。
+- **两条渠道差异极大**：官方渠道只有 720p、时长 3–10 秒、参考图最多 16 张、支持 `extend_from_task_id` 多轮编辑；Ext 渠道有 1080p/4k、时长只能 4/6/8/10、参考图只能 0/1/3 张、没有多轮编辑。产品入口可以合并，但渠道选择必须驱动参数显隐、校验、请求、轮询与计价，不能把两套契约混用。
+- Ext 渠道**不支持 2 张图的首尾帧**——这是与几乎所有其他视频模型都不同的限制，UI 必须挡住。
+- Ext 渠道传参考视频时**不能同时传 `duration`**。
+- 官方渠道传 `video_urls` 后 `aspect_ratio` 失效。
+- Ext 渠道按次计费，时长与分辨率决定档位，成本估算逻辑与「按秒」模型完全不同。
+
+## 5. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Gemini Omni Flash 视频生成（官方渠道） | https://docs.apimart.ai/cn/api-reference/videos/gemini-omni-flash-preview/generation | 否 |
+| Omni-Flash-Ext 视频生成 | https://docs.apimart.ai/cn/api-reference/videos/omni-flash-ext/generation | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（视频标签页搜 GEMINI-OMNI-FLASH-PREVIEW / OMNI-FLASH-EXT） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |

package/docs/model-adaptation/Gemini-Omni-Flash/Gemini-Omni-Flash_Fal.md

@@ -0,0 +1,84 @@
+# Gemini Omni Flash · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `google/gemini-omni-flash/image-to-video`、`google/gemini-omni-flash/reference-to-video` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> **Fal 上没有 `google/gemini-omni-flash/text-to-video` 端点**（2026-08-22 实测返回 404）。纯文生视频只能走 APIMart 或 KIE。
+
+## 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 |
+|---|---|
+| 图生视频 | `google/gemini-omni-flash/image-to-video` |
+| 参考生视频（多参考图） | `google/gemini-omni-flash/reference-to-video` |
+
+## 3. 请求参数
+
+### 3.1 `google/gemini-omni-flash/image-to-video`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | **必填** | — | 描述图片应如何被动画化 |
+| `image_url` | string | **必填** | — | 待动画化的输入图 URL |
+| `aspect_ratio` | string | 可选 | `16:9` | **仅 `16:9` / `9:16`** |
+| `duration` | integer | 可选 | **`8`** | **3 ~ 10 秒**（整数，注意 APIMart Ext / KIE 只允许 4/6/8/10） |
+
+### 3.2 `google/gemini-omni-flash/reference-to-video`
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | **必填** | — | 视频描述。**可用 `<IMAGE_REF_0>` 这样的标签把参考图内联绑定到角色**（见 Fal 的 Omni Flash prompt guide） |
+| `image_urls` | string[] | **必填** | — | 要融入视频的参考图 URL 列表 |
+| `aspect_ratio` | string | 可选 | `16:9` | `16:9` / `9:16` |
+| `duration` | integer | 可选 | `8` | 3 ~ 10 秒 |
+
+## 4. 响应结构
+
+```json
+{ "video": { "url": "https://v3b.fal.media/files/.../output.mp4" } }
+```
+
+## 5. 价格（按 token）
+
+来源：两个端点的 `llms.txt`（2026-08-22 读取）。
+
+| 计费项 | 单价 |
+|---|---|
+| 输入 token（文本 / 音频 / 视频） | **$1.875 / 1M tokens** |
+| 输出 token | **$21.875 / 1M tokens** |
+
+**720p 视频约合 $0.13 / 秒。**
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点两个字段都没有。
+- **Fal 没有纯文生视频端点**，产品若要文生视频必须走别的供应商。
+- **`duration` 是整数且支持 3–10 的连续取值**，默认 8；而 APIMart 的 Ext 渠道与 KIE 都只允许 4/6/8/10——跨供应商的时长选项必须分别裁剪。
+- `aspect_ratio` 只有横竖两种，没有 1:1。
+- 参考图的角色绑定用 `<IMAGE_REF_0>` 标签，与 APIMart 官方渠道（自然语言描述）、KIE（character_ids 资产）都不同。
+- 按 token 计费，成本估算不能按次或按秒简单换算。
+- Fal 上没有 KIE 那套语音 / 角色资产端点。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 图生视频模型页 | https://fal.ai/models/google/gemini-omni-flash/image-to-video | 否 |
+| 图生视频 schema + 价格 | https://fal.ai/models/google/gemini-omni-flash/image-to-video/llms.txt | 否 |
+| 参考生视频模型页 | https://fal.ai/models/google/gemini-omni-flash/reference-to-video | 否 |
+| 参考生视频 schema + 价格 | https://fal.ai/models/google/gemini-omni-flash/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/Gemini-Omni-Flash/Gemini-Omni-Flash_KIE.md

@@ -0,0 +1,129 @@
+# Gemini Omni Flash · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 视频（配套语音与角色能力） |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID / 端点 | `gemini-omni-video`（任务）、`POST /api/v1/omni/audio/create`、`POST /api/v1/omni/character/create` |
+| 接口形态 | 视频走**异步任务**；语音与角色是**独立的同步创建端点** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> ⚠️ KIE 的 Gemini Omni 是**三个端点组成的一套体系**：先用 `omni/audio/create` 造语音、用 `omni/character/create` 造角色，再把拿到的 `audio_ids` / `character_ids` 喂给 `gemini-omni-video`。上一版适配只做了视频生成，**语音与角色两块完全遗漏**。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **视频提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "gemini-omni-video", callBackUrl?, input }`
+- **视频查询**：`GET /api/v1/jobs/recordInfo?taskId=...`，`JSON.parse(resultJson)` → `{ resultUrls: [...] }`
+- **语音创建**：`POST /api/v1/omni/audio/create`
+- **角色创建**：`POST /api/v1/omni/character/create`
+
+## 2. 端点 A：`gemini-omni-video`（多模态视频生成）
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `input.prompt` | string | **必填** | — | 视频提示词，最多 **20000** 字符。描述画面内容、风格、镜头语言或角色行为 |
+| `input.image_urls` | array | 可选 | — | 参考图片。单个文件 ≤ **20 MB**；须公开可访问；**最多 7 张** |
+| `input.audio_ids` | array | 可选 | — | 由 **`gemini-omni-audio`** 接口生成的音频 ID 数组，用于旁白 / 对白 / 配乐 / 声音参考。**最多 3 个** |
+| `input.video_list` | array | 可选 | — | 视频片段数组。**最多 1 个，且占用 2 张图片额度**。每项 `{ url, start, ends }`：单个文件 ≤ **100 MB**、视频时长 ≤ **30 s**、`ends > start` 且 **`ends - start` ≤ 10 s** |
+| `input.character_ids` | array | 可选 | — | 由 **`gemini-omni-character`** 接口生成的角色 ID 数组。**每个 `character_id` 占用 1 个 image slot；基础最多 7 个；若同时传 `video_list`（占 2 个 slot），`character_ids` 最多 3 个** |
+| `input.duration` | string | **必填** | — | **`"4"` / `"6"` / `"8"` / `"10"`（字符串）**。**仅在无视频输入时生效**；有视频输入时输出时长由模型决定，本参数被忽略 |
+| `input.aspect_ratio` | string | 可选 | — | `16:9`（横屏）/ `9:16`（竖屏） |
+| `input.seed` | integer | 可选 | 自动 | `[0, 2147483647]`。**本项目规则：绝对不显示**，不下发 |
+| `input.resolution` | string | 可选 | `720p` | `720p` / `1080p` / `4k` |
+
+### image slot 计算（关键约束）
+
+图片额度总共 **7 个 slot**，被以下三者共同占用：
+- 每张 `image_urls` 图片：1 slot
+- 每个 `character_ids`：1 slot
+- `video_list`（最多 1 个）：**2 slot**
+
+因此有视频输入时，`character_ids` 最多 3 个。UI 计数必须按这个规则统一算。
+
+## 3. 端点 B：`POST /api/v1/omni/audio/create`（生语音）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `audio_id` | string | **必填** | 预设语音角色枚举（30 个，见下） |
+| `name` | string | **必填** | 语音名称，最长 **210** 字符 |
+| `voice_description` | string | 可选 | 语音特征描述（音色、风格、语速、情绪），最长 **20000** 字符 |
+| `example_dialogue` | string | 可选 | 对话示例（如「你好,我是Adam」），最长 **120** 字符 |
+
+### `audio_id` 预设音色全表
+
+| ID | 描述 | ID | 描述 |
+|---|---|---|---|
+| `achernar` | 女声，柔和，高音调 | `laomedeia` | 女声，欢快，中高音调 |
+| `achird` | 男声，友好，中音调 | `leda` | 女声，年轻，中高音调 |
+| `algenib` | 男声，沙哑，低音调 | `orus` | 男声，沉稳，中低音调 |
+| `algieba` | 男声，随和，中低音调 | `puck` | 男声，欢快，中音调 |
+| `alnilam` | 男声，沉稳，中低音调 | `pulcherrima` | 无性别，前置感，中高音调 |
+| `aoede` | 女声，轻快，中音调 | `rasalgethi` | 男声，知性，中音调 |
+| `autonoe` | 女声，明亮，中音调 | `sadachbia` | 男声，生动，低音调 |
+| `callirrhoe` | 女声，随和，中音调 | `sadaltager` | 男声，博学，中音调 |
+| `charon` | 男声，知性，低音调 | `schedar` | 男声，平稳，中低音调 |
+| `despina` | 女声，流畅，中音调 | `sulafat` | 女声，温暖，中音调 |
+| `enceladus` | 男声，气声，低音调 | `umbriel` | 男声，流畅，低音调 |
+| `erinome` | 女声，清晰，中音调 | `vindemiatrix` | 女声，温柔，中音调 |
+| `fenrir` | 男声，活泼，偏年轻音调 | `zephyr` | 女声，明亮，中高音调 |
+| `gacrux` | 女声，成熟，中音调 | `zubenelgenubi` | 男声，随性，中低音调 |
+| `iapetus` | 男声，清晰，中低音调 | `kore` | 女声，干练，中音调 |
+
+## 4. 端点 C：`POST /api/v1/omni/character/create`（生角色）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `descriptions` | string | **必填** | 角色描述：外观、身份、风格、服饰或性格设定 |
+| `image_urls` | array | **必填** | 角色参考图，**仅支持 1 张**。单张 ≤ **20 MB**，须公开可访问 |
+| `audio_ids` | array | 可选 | 由 `gemini-omni-audio` 生成的音频 ID，用于补充声音特征、语气或人设参考 |
+| `character_name` | string | 可选 | 角色名称 |
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `gemini-omni`；1 Credit = $0.005）。**按次（per video）计费，不是按秒。**
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| 720p 4s 无视频输入 | 63 /条 | **$0.315/条** | $0.5 | 37.0% |
+| 720p 6s 无视频输入 | 84 /条 | **$0.42/条** | $0.75 | 44.0% |
+| 720p 8s 无视频输入 | 105 /条 | **$0.525/条** | $1 | 47.5% |
+| 720p 10s 无视频输入 | 126 /条 | **$0.63/条** | $1.25 | 49.6% |
+| 1080p 4s 无视频输入 | 63 /条 | **$0.315/条** | N/A | — |
+| 1080p 6s 无视频输入 | 84 /条 | **$0.42/条** | N/A | — |
+| 1080p 8s 无视频输入 | 105 /条 | **$0.525/条** | N/A | — |
+| 1080p 10s 无视频输入 | 126 /条 | **$0.63/条** | N/A | — |
+| 4k 4s 无视频输入 | 147 /条 | **$0.735/条** | N/A | — |
+| 4k 6s 无视频输入 | 168 /条 | **$0.84/条** | N/A | — |
+| 4k 8s 无视频输入 | 189 /条 | **$0.945/条** | N/A | — |
+| 4k 10s 无视频输入 | 210 /条 | **$1.05/条** | N/A | — |
+| 720p 有视频输入 | 168 /条 | **$0.84/条** | N/A | — |
+| 1080p 有视频输入 | 168 /条 | **$0.84/条** | N/A | — |
+| 4k 有视频输入 | 252 /条 | **$1.26/条** | N/A | — |
+
+定价页未列出 `omni/audio/create` 与 `omni/character/create` 的价格，接入前需确认这两个端点是否单独计费。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 的 `gemini-omni-video` **有 `seed`**，必须主动不注册、不下发。
+- **这是一套三端点体系**，语音与角色是可复用资产（先创建拿 ID，再在视频里引用），需要独立的资产管理交互，不能塞进单次生成的参数面板。
+- **image slot 是共享额度**（图片 1 / 角色 1 / 视频 2，总计 7），前端计数必须统一。
+- `duration` 是**字符串**且只有 4/6/8/10；**有视频输入时该参数静默失效**。
+- **按次计费**：720p 与 1080p 同价，4k 更贵；有视频输入时价格固定且明显更高。
+- `video_list` 的截取窗口 `ends - start` 必须 ≤ 10 秒。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Gemini Omni 生视频 | https://docs.kie.ai/cn/market/gemini-omni-video | 否 |
+| Gemini Omni Audio 生语音 | https://docs.kie.ai/cn/market/gemini-omni-audio | 否 |
+| Gemini Omni Character 生角色 | https://docs.kie.ai/cn/market/gemini-omni-character | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `gemini-omni`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |

package/docs/model-adaptation/Grok-Imagine/Grok-Imagine_KIE.md

@@ -0,0 +1,36 @@
+# Grok Imagine · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 图片 |
+| 供应商 | KIE.ai |
+| 平台模型 ID | `grok-imagine/text-to-image`、`grok-imagine/image-to-image` |
+| 接口形态 | `POST /api/v1/jobs/createTask` + `GET /api/v1/jobs/recordInfo` |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 模式
+
+- 文生图使用 `grok-imagine/text-to-image`，`enable_pro=false` 是 Standard，`enable_pro=true` 是 Quality。
+- 图生图使用 `grok-imagine/image-to-image`，输入 1 张图片。
+
+## 2. 价格与输出单位
+
+KIE 定价使用 `1 Credit = $0.005`。
+
+| 模式 | Credits | 总价 | 计价输出单位 |
+|---|---:|---:|---|
+| Standard 文生图 | 4 / 次 | $0.02 / 次 | 2 张图 |
+| Quality 文生图 | 5 / 次 | $0.025 / 次 | **4 张图** |
+| 图生图 | 4 / 张 | $0.02 / 张 | 1 张图 |
+
+SDK calculator 返回的是整次请求价格：Quality 仍是 `$0.025`，但说明必须写明该次输出 4 张，不能写成 2 张。
+
+## 3. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| Grok Imagine 文生图 | https://docs.kie.ai/cn/market/grok-imagine/text-to-image | 否 |
+| Grok Imagine 图生图 | https://docs.kie.ai/cn/market/grok-imagine/image-to-image | 否 |
+| 模型专页 | https://kie.ai/grok-imagine | 否 |
+| 当前定价 | https://kie.ai/pricing | 否 |

package/docs/model-adaptation/Grok-Imagine-2.0/Grok-Imagine-2.0_APIMart.md

@@ -0,0 +1,250 @@
+# Grok Imagine 2.0 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | **两条独立渠道**：`grok-imagine-2.0-ext`（EXT）与 `grok-imagine-image-2.0`（官方） |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> APIMart 上 Grok Imagine 2.0 有**三份文档、两条渠道**：
+>
+> - **`grok-imagine-2.0-ext`**：仅文生图 + **图层与选区编辑（segment / region_edit）**
+> - **`grok-imagine-image-2.0`（官方渠道）**：文生图 + 单图编辑 + 多图参考（1–3 张）
+>
+> 上一版适配只覆盖了基础生成，**图层与选区编辑整块能力被遗漏**。
+> Henji 产品中基础图片生成合并为一个“Grok Imagine Image 2.0”入口，通过首项“渠道”（普通 / 官方）切换；图层与选区编辑仍属于依赖结果卡片的独立连续工作流，不塞入普通生成参数。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/images/generations`
+- **查询**：`GET /v1/tasks/{task_id}`，状态 `pending` / `processing` / `completed` / `failed`
+- **轮询建议**（图层编辑文档）：从 **2 秒**间隔开始，逐步退避到最多 **5 秒**，总超时 **10 分钟**；切换源图或离开页面时用 `AbortController` 终止旧轮询
+- ⚠️ **任务查询即使返回 HTTP 200，`data.status` 仍可能是 `failed`**，必须按 `data.status` 判断成败并展示 `data.error`
+
+### 推荐请求头
+
+| Header | 要求 | 说明 |
+|---|---|---|
+| `Authorization` | 必须 | `Bearer <APIMart API Key>` |
+| `Content-Type` | 必须 | `application/json` |
+| `Accept` | 推荐 | `application/json` |
+| `Idempotency-Key` | **强烈推荐** | 每次「用户确认的一次逻辑生成」用新 UUID（1–191 个可见 ASCII 字符）；**网络重试必须复用同一 key 与完全相同的 body**。同 key 任务仍在处理时可能返回 `409 idempotency_in_progress`；返回 `idempotency_result_indeterminate` 时**停止自动重提并保留原 Key**，尤其不要为结果不确定的付费 `region_edit` 换新 Key |
+| `X-APIMart-Response-Version` | 强烈推荐 | 固定 `2026-07-27`，确保响应结构稳定（`data.id`） |
+
+> 安全提示（文档反复强调）：不要把 API Key 写进浏览器包（`VITE_*` / `NEXT_PUBLIC_*`）、LocalStorage、URL 或前端日志；浏览器只调业务 BFF，由服务端持有 Key。
+
+---
+
+## 2. 渠道 A：`grok-imagine-2.0-ext`（文生图）
+
+### 2.1 能力与限制
+
+| 维度 | 说明 |
+|---|---|
+| 模型名 | 固定 `grok-imagine-2.0-ext` |
+| 能力 | **仅文生图** |
+| 张数 `n` | `1`–`12`，默认 `1` |
+| 比例 `size` | 7 种比例 + 5 种兼容像素写法 |
+| 输出 | **仅 `response_format=url`** |
+| 不支持 | 图生图、`stream=true`、`quality` 字段、`style`、`b64_json` / `base64` |
+| 计费 | 固定单价，按**实际成功交付张数**计费 |
+| 结果时效 | 图片链接有效期 **72 小时** |
+
+### 2.2 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `model` | string | 是 | — | 固定 `grok-imagine-2.0-ext` |
+| `prompt` | string | 是 | — | 去空格后不能为空，提交前请 `trim` |
+| `n` | integer | 否 | `1` | `1`–`12`。**显式传 `0` 会报错** |
+| `size` | string | 否 | — | 比例：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`9:16`、`16:9`。兼容像素写法：`1024x1024`、`1024x1792`、`1792x1024`、`720x1280`、`1280x720`。**不在白名单内（如 `1:2`、`2:1`、`4:5`、`auto`）返回 `400 invalid_size`** |
+| `nsfw_check` | boolean | 否 | `false` | `true` 时用 `omni-moderation-latest` 预审 |
+
+> 同一比例下实际像素可能与兼容表不一致（如 `1:1` 可能返回 1408×1408）。**以返回图片为准，不要反推改写 `size`。**
+
+---
+
+## 3. 渠道 A 扩展：图层与选区编辑（`segment` / `region_edit`）
+
+两者都复用同一个异步图片入口 `POST /v1/images/generations`，靠 `operation` 字段区分。
+
+| 操作 | 用途 | 关键输入 | 完成结果 | 计费 |
+|---|---|---|---|---|
+| `segment` | 识别对象并获取图层、边界框和精确遮罩 | 已完成单图任务的 `source_task_id` | `image_id`、`image_url`、`objects` | **免费**（`cost` / `credits_cost` 均为 0） |
+| `region_edit` | 修改多边形、矩形或对象所在区域 | segment 返回的 `image_id` + 编辑提示词 + 选区 | 新图片 URL 和新 `image_id` | **按完成任务结算** |
+
+> ⚠️ `source_task_id` 与 `image_id` **不可互换**：`segment` 用来源**任务** ID；`region_edit` 用**图片资产** ID。编辑后要重新取图层时，把本次 `region_edit` 的 `task_id` 作为新的 `source_task_id`。
+
+### 3.1 `segment` 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `model` | string | 是 | `grok-imagine-2.0-ext` | 固定 |
+| `operation` | string | 是 | `segment` | 固定 `segment` |
+| `source_task_id` | string | 是 | — | 当前用户**已完成**的 Grok **单图**任务 ID（必须成功、属于图片任务、最终结果仅 1 张图）。**不要同时发 `image_id` 或 `image_index`** |
+| `include_mask_rle` | boolean | 否 | `true` | 是否返回 COCO compressed RLE。需要精确描边 / 画笔 / 多边形编辑时应显式设为 `true` |
+| `cache_only` | boolean | 否 | `false` | 仅查缓存，未命中不回源。**不能与 `refresh=true` 同用** |
+| `cached_only` | boolean | 否 | `false` | 传给上游的缓存提示，不代表本地一定命中 |
+| `refresh` | boolean | 否 | `false` | 强制跳过缓存重取。不要用于普通编辑器流程，**不能与 `cache_only=true` 同用** |
+| `nsfw_check` | boolean | 否 | `false` | 审核来源图片 |
+
+`segment` **不需要 `prompt`**，也不要发送 `billing_model_name`、`n`、`size`、`response_format`。
+
+### 3.2 `segment` 完成响应
+
+`data.result` **直接是分段结果，不包在 `images` 里**：
+
+```json
+{ "code": 200, "data": { "id": "task_...", "status": "completed", "progress": 100,
+  "cost": 0, "credits_cost": 0,
+  "result": { "created": 1786784507, "source_task_id": "task_...",
+    "image_id": "6b78a7c3-...", "image_url": "https://.../source.jpg",
+    "cached": false, "from_cache": true, "cache_status": "hit",
+    "objects": [ { "index": 0, "name": "red sports car",
+      "box_xyxy": [38.1, 689.8, 945.8, 1065.4], "score": 0.9765625,
+      "mask_size": [1792, 1008], "mask_url": "",
+      "mask_rle": { "size": [1792, 1008], "counts": "..." } } ] } } }
+```
+
+| 字段 | 说明 |
+|---|---|
+| `result.image_id` | 来源图片的资产 ID，后续 `region_edit` 使用此值 |
+| `result.image_url` | 与 `image_id` 对齐的公网图片 URL |
+| `objects[].index` | 服务端原始对象索引；使用 `object_indices` 时**必须原样保留** |
+| `objects[].box_xyxy` | mask 像素坐标 `[x1,y1,x2,y2]` |
+| `objects[].score` | 识别置信度，**可能为 `null`** |
+| `objects[].mask_size` | **`[height, width]`**，不可写死图片尺寸 |
+| `objects[].mask_rle` | COCO compressed RLE，精确描边的首选数据 |
+| `objects[].mask_url` | 可选的遮罩图片 URL，**可能为空** |
+
+没有有效 `mask_rle` 或 `mask_url` 的对象只能用于矩形近似编辑，不能标记为精确图层。
+
+### 3.3 `region_edit` 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `model` | string | 是 | 固定 `grok-imagine-2.0-ext` |
+| `operation` | string | 是 | 固定 `region_edit` |
+| `image_id` | string | 是 | 当前源图资产 ID。首次编辑用 segment 的 `result.image_id`；连续编辑用上次编辑返回的新 `image_id` |
+| `prompt` | string | 是 | 描述如何修改选区，去空格后不能为空 |
+| `selection_regions` | array | △ | **精确多边形选区**，推荐用于正式图层和画笔编辑。坐标**归一化到 0~1**，支持 `outer` 与可选 `holes`；`points` 可用扁平数组或 `[[x0,y0],...]`；每个 ring 至少 3 对坐标 |
+| `boxes` | array | △ | 矩形选区，每项 `[x1,y1,x2,y2]`。可用归一化坐标；**用像素坐标时必须同时传 `mask_size`**。每个 box 恰好 4 个非负有限数字且 `x2>x1`、`y2>y1` |
+| `object_indices` | array | △ | segment 返回的原始 `objects[].index`。上游按**对象边界框**编辑，**只适合快速联调或矩形近似**。索引必须来自同一 `image_id` 的 segment 响应，不要用前端过滤 / 排序后的数组下标 |
+| `mask_size` | array | 条件 | 像素 `boxes` 使用的 `[height, width]`，两个值都必须为正整数 |
+| `nsfw_check` | boolean | 否 | 审核编辑提示词与输入图 |
+
+`selection_regions` / `boxes` / `object_indices` **至少有一个非空**；接口允许组合，但建议一次只用一种。
+
+**不要发送**：`billing_model_name`、`size`、`aspect_ratio`、`source_aspect_ratio`、`source_size`、`image_urls`。`n` 只能省略或为 `1`；`claim_asset` 只能省略或为 `false`；`response_format` 只能省略或为 `url`；不支持 Base64 输出与 `stream=true`。
+
+### 3.4 错误码
+
+| HTTP | 错误码 | 常见原因 | 处理 |
+|---|---|---|---|
+| 400 | `invalid_operation` | `operation` 缺失或不支持 | 只用 `segment` / `region_edit` |
+| 400 | `invalid_source_task` | segment 来源任务不可用，或传了 `image_id` / `image_index` | 用当前用户已完成的 Grok 单图任务 ID |
+| 400 | `conflicting_cache_flags` | 同时用 `cache_only` 和 `refresh` | 二选一 |
+| 400 | `missing_image_id` | region edit 缺资产 ID | 用 segment 返回的 `result.image_id` |
+| 400 | `empty_prompt` | 编辑提示词为空 | 前端阻止提交 |
+| 400 | `invalid_selection_regions` | 无选区、坐标、点数或 box 非法 | 前端校验并标记 |
+| 400 | `invalid_object_index` | 对象索引非法 | 保留原始索引 |
+| 400 | `invalid_claim_asset` | `claim_asset=true` | 省略或设 `false` |
+| 400 | `invalid_n` | `n` 不是 1 | 省略或设 1 |
+| 400 | `invalid_response_format` | 请求 Base64 等 | 省略或用 `url` |
+| 400 | `invalid_stream` | 请求流式 | 移除 `stream` |
+| 401 / 403 | — | Key 无效或模型未开通 | 检查 Key 与账户权限 |
+
+---
+
+## 4. 渠道 B：`grok-imagine-image-2.0`（官方渠道）
+
+### 4.1 能力
+
+| 模型 | 分辨率 | `quality` | 输入图 | 输出张数 |
+|---|---|---|---|---|
+| `grok-imagine-image-2.0` | `1k`、`2k` | **仅文生图**支持 `low`、`medium` | 0–3 张 | **1–10 张** |
+
+| 场景 | `image_urls` | 处理方式 |
+|---|---|---|
+| 文生图 | 不发送 | 根据提示词生成 |
+| 单图编辑 | 1 张 | 根据提示词编辑参考图 |
+| 多图参考 | 2–3 张 | 按数组顺序融合或参考多张图 |
+
+**提交成功时 HTTP 状态为 `202`**，任务 ID 在 `data.id`，可用 `data.poll_url` 或 `GET /v1/tasks/{task_id}` 轮询。
+
+### 4.2 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `model` | string | 是 | `grok-imagine-image-2.0` | 固定值 |
+| `prompt` | string | 是 | — | 去首尾空格后不能为空，**最多 8000 字符**。多图参考时可用 `<IMAGE_0>` / `<IMAGE_1>` / `<IMAGE_2>` 按数组顺序引用 |
+| `n` | integer | 否 | `1` | `1`–`10` |
+| `aspect_ratio` | string | 否 | — | 完整允许值：`1:1`、`3:4`、`4:3`、`9:16`、`16:9`、`2:3`、`3:2`、`9:19.5`、`19.5:9`、`9:20`、`20:9`、`1:2`、`2:1`、`auto`（**14 种**）。**新接入不要发送像素尺寸字符串** |
+| `resolution` | string | 否 | `1k` | `1k` / `2k` |
+| `quality` | string | 否 | `medium` | `low` / `medium`。**仅文生图支持；请求含 `image_urls` 时不要发送**（加参考图时要清除表单遗留值） |
+| `image_urls` | array | 否 | — | 参考图，**1–3 张**。仅接受公网可访问的绝对 `http(s)` URL。**没有参考图时应省略本字段，不要发空数组**；数组顺序保留；重复图片按多张输入处理并按张计费 |
+| `nsfw_check` | boolean | 否 | `false` | 审核提示词与输入图 |
+
+### 4.3 上传本地参考图
+
+`POST /v1/uploads/images`，表单字段固定为 `file`（`multipart/form-data`）。支持 JPEG / PNG / WebP，单张 **≤ 10 MiB**；使用 `FormData` 时不要手动设置 `Content-Type`。
+
+### 4.4 报价接口（推荐）
+
+官方渠道提供**预估价格接口**。参数：`model`（必填）、`n`、`aspect_ratio`、`resolution`、`quality`（仅 2.0 文生图传）、`input_images`（等于 `image_urls.length`，无参考图为 0）。
+
+返回字段：`final_usd`（**唯一应展示的预估总价**）、`unit_price_usd`、`input_surcharge_usd`、`image_count`、`input_images`、以及服务端规范化后的 `resolution` / `quality` / `aspect_ratio`。
+
+> ⚠️ **不要用 `unit_price_usd × image_count + input_surcharge_usd` 替代 `final_usd`**——用户折扣、分组价格和整单取整会让自算结果不同。输入图片从第 1 张开始计费，按输入张数计算，**不乘输出数量 `n`**。
+
+## 5. 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)（2026-08-22 读取，1 Credit ≈ $0.1）。
+
+**GROK-IMAGINE-2.0-EXT**
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 | 0.15 Credits/张 ≈ **$0.015/张** | $0.01875 | 20% |
+| `region-edit` | 0.15 Credits/张 ≈ **$0.015/张** | $0.01875 | 20% |
+
+> 注：`grok-imagine-2.0-ext` 的 API 文档正文写「$0.08/张」，与定价中心的 $0.015/张不一致，**以定价中心与报价接口的 `final_usd` 为准**。
+
+**GROK-IMAGINE-IMAGE-2.0**（官方渠道）
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 1K@low | 0.32 Credits/张 ≈ **$0.032/张** | $0.04 | 20% |
+| 1K@medium | 0.48 Credits/张 ≈ **$0.048/张** | $0.06 | 20% |
+| 2K@low | 0.48 Credits/张 ≈ **$0.048/张** | $0.06 | 20% |
+| 2K@medium | 0.64 Credits/张 ≈ **$0.064/张** | $0.08 | 20% |
+| 输入参考图 | 0.08 Credits/张 ≈ **$0.008/张** | $0.01 | 20% |
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 这两条渠道都没有这两个字段。
+- **两条渠道能力互补**：基础图片生成可以合成一个产品入口，但参数显隐、输入限制、请求和计价必须随“渠道”严格分支；EXT 只能文生图但另有图层/选区编辑，官方渠道能图生图和多图参考但没有 segment。
+- **图层与选区编辑是完整的第二套工作流**（segment → region_edit → 连续编辑），需要「结果卡片 → 分割 → 框选/多边形 → 编辑」的交互载体，不能塞进普通出图参数里。
+- `segment` 免费但 `region_edit` 付费，且强烈依赖 `Idempotency-Key` 防重复扣费；结果不确定时不能自动换 Key 重提。
+- `mask_size` 是 `[height, width]`，不是 `[width, height]`，写反会导致选区错位。
+- 官方渠道的 `quality` **只在文生图时能发**，加了参考图必须清掉，否则报错。
+- 比例白名单差异极大：EXT 只有 7 种且不支持 `auto`；官方渠道有 14 种且支持 `auto`、`9:19.5`、`20:9` 这类罕见比例。
+- 官方渠道提交返回 **202**（不是 200），状态机要覆盖。
+- 价格应走报价接口取 `final_usd`，不要前端硬编码。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Grok Imagine 2.0 Ext 图像生成 | https://docs.apimart.ai/cn/api-reference/images/grok-imagine-2.0-ext/generation | 否 |
+| Grok Imagine 2.0 Ext 图层与选区编辑 | https://docs.apimart.ai/cn/api-reference/images/grok-imagine-2.0-ext/layer-region-edit | 否 |
+| Grok Imagine Image 2.0 官方图像生成与编辑 | https://docs.apimart.ai/cn/api-reference/images/grok-imagine-2.0-ext/official | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（搜 GROK-IMAGINE-2.0-EXT / GROK-IMAGINE-IMAGE-2.0） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |