220 lines
6.9 KiB
Markdown
220 lines
6.9 KiB
Markdown
## Context
|
||
|
||
当前标准 Kling 视频接口具有两个明显特征：
|
||
|
||
- 提交动作分为：
|
||
- `POST /kling/v1/videos/text2video`
|
||
- `POST /kling/v1/videos/image2video`
|
||
- 真正执行版本通过请求体 `model_name` 指定，而不是通过发现到的能力 ID 直接调用
|
||
|
||
同时，运行时发现已经能够识别出能力型视频标识，例如：
|
||
|
||
- `kling_video`
|
||
- `kling_image`
|
||
- `kling_effects`
|
||
- `kling_extend`
|
||
- `kling_lip_sync`
|
||
- `kling_virtual_try_on`
|
||
|
||
这说明 Kling 与 Suno 有相似的结构特征：
|
||
|
||
- 发现层暴露的是能力入口
|
||
- 执行层需要额外版本字段
|
||
|
||
但当前标准 Kling adapter 仍然主要围绕版本型模型 ID 运转，例如 `kling-v1-6`。这让以下几层出现语义错位：
|
||
|
||
1. discovery 发现的是能力
|
||
2. selector 选中的可能是能力
|
||
3. adapter 执行时却把 `model` 理解为可直接提交的执行版本
|
||
|
||
此外，标准 Kling 视频与 `kling-video-o1`、`kling-video-o1-edit` 不是同一条协议语义：
|
||
|
||
- 标准 Kling 视频走 `/kling/v1/videos/{action}`
|
||
- `o1` 系列是另一类特例模型，不应被标准 Kling 能力路由误吞
|
||
|
||
## Goals / Non-Goals
|
||
|
||
- Goals:
|
||
- 让标准 Kling 视频沿用 Suno 式“能力入口 + 执行版本”模式
|
||
- 让 `kling_video` 成为标准 Kling 视频的一等能力模型
|
||
- 让 `model_name` 成为标准 Kling 视频的执行版本字段
|
||
- 让 `text2video / image2video` 的版本限制显式建模
|
||
- 保持旧版本型模型 ID 的兼容，避免历史任务和用户设置立刻失效
|
||
- Non-Goals:
|
||
- 本次不抽象所有 Kling 能力为统一多动作产品面板
|
||
- 本次不处理 `o1` 系列的专用协议
|
||
- 本次不一次性把所有 Kling 高级字段做成复杂 UI 控件
|
||
|
||
## Decisions
|
||
|
||
- Decision: 区分标准 Kling 能力模型和执行版本
|
||
|
||
- `kling_video` 表示标准 Kling 视频能力入口
|
||
- `model_name` 表示具体执行版本，例如 `kling-v3`
|
||
- 发现层与选择层优先使用 `kling_video`
|
||
- 执行层始终向标准接口提交 `model_name`
|
||
|
||
- Decision: action 继续由请求语义决定，而不是再拆成两个能力模型
|
||
|
||
- 显式传入 `klingAction2` 时优先使用
|
||
- 否则：
|
||
- 有参考图 => `image2video`
|
||
- 无参考图 => `text2video`
|
||
|
||
- Decision: 版本合法性绑定到 action
|
||
|
||
- `text2video` 的可选版本：
|
||
- `kling-v3`
|
||
- `kling-v2-6`
|
||
- `kling-v2-1`
|
||
- `kling-v1-6`
|
||
- `kling-v1-5`
|
||
- `image2video` 的可选版本：
|
||
- `kling-v3`
|
||
- `kling-v2-6`
|
||
- `kling-v2-1`
|
||
- `kling-v1-6`
|
||
- `kling-v1-5`
|
||
|
||
- Decision: 历史版本型模型 ID 作为兼容输入，而不是主路径
|
||
|
||
- 若请求模型为 `kling-v1-5` 或 `kling-v1-6`
|
||
- 运行时仍允许提交
|
||
- 但内部按“标准 Kling 能力 + 指定 model_name”解释
|
||
|
||
- Decision: `o1` 系列与标准 Kling 视频能力显式隔离
|
||
|
||
- `kling-video-o1`
|
||
- `kling-video-o1-edit`
|
||
- 不参与标准 `kling.video` binding 推断
|
||
- 不复用 `/kling/v1/videos/{action}` 的标准版本校验
|
||
|
||
- Decision: UI 先暴露最小必要版本选择
|
||
|
||
- 第一阶段保证用户可以为标准 Kling 能力选择：
|
||
- `model_name`
|
||
- `klingAction2`
|
||
- `mode`
|
||
- `cfg_scale`
|
||
- `negative_prompt`
|
||
- `camera_control` 通过平铺字段纳入参数体系：
|
||
- `camera_control_type`
|
||
- `camera_horizontal / vertical / pan / tilt / roll / zoom`
|
||
- `image_tail` 与 `callback_url` 暂不纳入本阶段可视化参数体系
|
||
|
||
- Decision: Kling 数值参数同时在 UI 元数据和 adapter 层校验
|
||
|
||
- `cfg_scale` 取值范围固定为 `[0, 1]`
|
||
- `camera_control` 的六个数值字段固定为 `[-10, 10]` 且必须是整数
|
||
- 参数面板与 MCP schema 暴露相同的边界信息
|
||
- adapter 仍负责最终校验，避免 workflow / MCP 直接绕过 UI
|
||
|
||
## Proposed Data Model
|
||
|
||
```ts
|
||
interface ProviderVideoBindingMetadata {
|
||
allowedDurations?: string[];
|
||
defaultDuration?: string;
|
||
durationMode?: 'request-param' | 'model-alias';
|
||
durationField?: string;
|
||
durationToModelMap?: Record<string, string>;
|
||
strictDurationValidation?: boolean;
|
||
resultMode?: 'inline-url' | 'download-content';
|
||
downloadPathTemplate?: string;
|
||
|
||
versionField?: string;
|
||
versionOptions?: string[];
|
||
defaultVersion?: string;
|
||
versionOptionsByAction?: Record<string, string[]>;
|
||
}
|
||
|
||
interface KlingResolvedRequest {
|
||
action: 'text2video' | 'image2video';
|
||
modelName: string;
|
||
}
|
||
```
|
||
|
||
标准 Kling 视频 binding 期望类似：
|
||
|
||
```ts
|
||
{
|
||
operation: 'video',
|
||
protocol: 'kling.video',
|
||
requestSchema: 'kling.video.auto-action-json',
|
||
submitPath: '/kling/v1/videos/{action}',
|
||
pollPathTemplate: '/kling/v1/videos/{action}/{taskId}',
|
||
metadata: {
|
||
video: {
|
||
versionField: 'model_name',
|
||
defaultVersion: 'kling-v1-6',
|
||
versionOptions: [
|
||
'kling-v3',
|
||
'kling-v2-6',
|
||
'kling-v2-1',
|
||
'kling-v1-6',
|
||
'kling-v1-5'
|
||
],
|
||
versionOptionsByAction: {
|
||
text2video: ['kling-v3', 'kling-v2-6', 'kling-v2-1', 'kling-v1-6', 'kling-v1-5'],
|
||
image2video: ['kling-v3', 'kling-v2-6', 'kling-v2-1', 'kling-v1-6', 'kling-v1-5']
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Execution Flow
|
||
|
||
1. 发现层识别到 `kling_video`
|
||
2. 选择器保留 `profileId::kling_video`
|
||
3. 运行时 planner 解析到标准 Kling 视频 binding
|
||
4. adapter 根据请求判断 action：
|
||
- `text2video`
|
||
- `image2video`
|
||
5. adapter 从以下来源解析执行版本：
|
||
- `params.model_name`
|
||
- binding `defaultVersion`
|
||
- 历史兼容的 `request.model === kling-v*`
|
||
6. adapter 按 action 校验版本是否允许
|
||
7. adapter 构造标准 Kling 请求体并提交
|
||
|
||
## Compatibility Strategy
|
||
|
||
### Discovery / Selection
|
||
|
||
- 新发现到的 `kling_video` 应作为标准主路径能力模型
|
||
- 老的静态版本型模型可以继续存在，但不再作为未来扩展的主心智
|
||
|
||
### Runtime
|
||
|
||
- 当请求模型是 `kling_video` 时：
|
||
- 必须解析 `model_name`
|
||
- 当请求模型是 `kling-v1-5` 或 `kling-v1-6` 时：
|
||
- 直接将该值视为显式执行版本
|
||
- 同时仍走标准 Kling adapter
|
||
|
||
### UI
|
||
|
||
- 若当前选择的是 `kling_video`
|
||
- 参数区应能选择 `model_name`
|
||
- 若当前选择的是旧版本型模型
|
||
- UI 可以继续工作
|
||
- 但内部行为应与显式 `model_name` 一致
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- 风险: 运行时同时支持 `kling_video` 和 `kling-v*`，可能产生双轨心智
|
||
- Mitigation: 将 `kling_video` 作为主路径，仅保留 `kling-v*` 兼容输入
|
||
|
||
- 风险: Kling 版本集合仍按 action 维护，后续若再次分叉，UI 或 workflow 可能产生非法组合
|
||
- Mitigation: 在 adapter 层做最终校验，并在参数层尽量按 action 过滤
|
||
|
||
- 风险: `o1` 系列误被标准 Kling 识别规则吞掉
|
||
- Mitigation: 明确在 binding inference 和 adapter 匹配中排除 `kling-video-o1*`
|
||
|
||
## Open Questions
|
||
|
||
- 默认版本是否应从 `kling-v1-6` 逐步切换到 `kling-v3`
|
||
- `image_tail` 是否在第一阶段就进入 UI 参数面板
|
||
- `mode / cfg_scale / camera_control` 是否应在后续改为动态 binding 参数，而不是继续依赖静态透传
|