Jammy/TrueGrowth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5119ac0ef84a4c3c35107e6cf5584c712fb57019
TrueGrowth/openspec/changes/update-kling-capability-version-routing/design.md

6.9 KiB
Raw Blame History

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

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 期望类似：

{
  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 参数，而不是继续依赖静态透传
Reference in New Issue View Git Blame Copy Permalink