kling-studio

用途

kling-studio 是一个基于 Kling 3.0 Omni 模型的全功能视频生成技能，用于生成和操作视频。它提供了一套结构化工作流，根据用户意图构建 API 请求，确保符合模型复杂的参数约束。

主要能力

文生视频：根据文本描述生成视频。
图生视频：用描述性提示词让静态图像动起来。
视频到视频（编辑）：根据提示词修改已有视频（例如改变主体、风格）。
视频到视频（参考）：使用已有视频作为镜头运动和风格的参考。
多镜头生成：创建包含多个不同场景或镜头的视频。
音频生成：生成带同步音频的视频，包括语音和音效。

参考文件

该技能包含以下参考文件：

references/api_reference.md — 完整的官方 API 参数参考，包括所有字段、类型、约束、互斥规则（R1–R10）、能力矩阵和调用示例。在构建任何 API 调用前应先阅读此文件。
references/prompt_guide.md — Kling 3.0 Omni 提示词编写原则、官方公式、模板语法，以及所有主要场景的少样本示例。
scripts/kling_api.py — 用于 JWT 认证、任务创建和轮询的 Python 工具类。

使用方式

工作流：从用户意图到 API 调用

要正确使用 Kling API，必须遵循以下决策工作流来构建 API 载荷。过程分为两个主要阶段：提示词设计和参数构建。

阶段 1：提示词设计

在构建 API 调用之前，必须先根据用户请求设计提示词。提示词质量是获得好结果的最重要因素。

查阅提示词指南：阅读 /home/ubuntu/skills/kling-studio/references/prompt_guide.md，了解核心原则、官方公式和编写有效提示词的少样本示例。
识别场景：确定用户请求属于以下哪种场景：
- 单镜头视频（来自文本、图像或视频）
- 多镜头视频（包含多个场景的分镜）
编写提示词：
- 单镜头：按照指南公式编写一个详细提示词。
- 多镜头：为每个镜头/场景分别编写提示词。
使用模板语法：如果用户提供参考图像、元素或视频，必须在提示词中使用 <<<image_1>>>、<<<element_1>>>、<<<video_1>>> 模板语法显式引用它们。这是 Omni 模型的核心功能。

阶段 2：参数构建

提示词准备好后，按照以下决策树构建最终 API 请求载荷，确保遵守所有参数约束和相互依赖关系。

决策流程概述：

判断是多镜头还是单镜头。
- 多镜头：设置 multi_shot: true，设置 shot_type: "customize"，根据提示词构建 multi_prompt 数组，从 multi_prompt 计算总时长，设置顶层 duration，得到最终载荷。
- 单镜头：设置 multi_shot: false。
  - 是否提供视频输入？
    - 是：判断是编辑还是参考。
      - 编辑：设置 refer_type: "base"，忽略 duration 参数，进入音频处理。
      - 参考：设置 refer_type: "feature"，设置 aspect_ratio，进入音频处理。
    - 否：走文生视频/图生视频路径，进入音频处理。
音频处理：
- 是否需要音频输出？
  - 是：设置 sound: "on"。
    - 是否存在视频输入？
      - 是：错误：sound:on 与视频输入不兼容。
      - 否：正常。
  - 否：设置 sound: "off"。

关键参数规则（来自测试）

以下不是完整列表，而是必须遵守的最关键、最不明显的规则摘要。完整指南请参考 prompt_guide.md。

refer_type：必须显式指定，不要省略。默认值为 base，但不可靠。编辑用 base，参考用 feature。
duration：在 base 模式下被忽略。在 customize 模式下，必须等于 multi_prompt 时长之和。
sound：与 video_list 不兼容。如果提供了参考视频，不能设为 on。
shot_type：对于 Omni 模型，multi_shot: true 时必须为 customize。不支持 intelligence。
multi_prompt：索引必须从 1 开始。总时长必须与顶层 duration 匹配。最多 6 个镜头。
aspect_ratio：feature 模式下必需。
image_list：无视频输入时最多 7 张图像，有视频输入时最多 4 张图像。

执行

要执行视频生成任务，使用提供的 Python 脚本，它处理认证和轮询。

设置环境变量：确保已设置 KLING_ACCESS_KEY 和 KLING_SECRET_KEY。
构建载荷：按照上述工作流创建 API 调用的 JSON 载荷。
运行脚本：

from kling_api import KlingAPI

# Get keys from environment
access_key = os.environ.get("KLING_ACCESS_KEY")
secret_key = os.environ.get("KLING_SECRET_KEY")
api = KlingAPI(access_key, secret_key)

# Your constructed payload
payload = {
    "model_name": "kling-v3-omni",
    # ... other parameters based on the workflow ...
}

# Create and poll the task
task_response = api.create_omni_video_task(payload)
if task_response and task_response.get("code") == 0:
    task_id = task_response.get("data", {}).get("task_id")
    print(f"Task created: {task_id}")
    result = api.poll_for_completion(task_id)
    if result:
        print("Final video URL:", result.get("videos", [{}])[0].get("url"))

这种结构化方法确保正确处理 Kling 3.0 Omni API 的所有细节和约束，减少错误并提高结果的可预测性。

适用场景

适用于需要通过 Kling 3.0 Omni 模型生成或编辑视频的场景，包括文生视频、图生视频、视频编辑、视频参考、多镜头视频以及带音频的视频生成。

限制

sound:on 与视频输入不兼容。
multi_prompt 最多 6 个镜头。
image_list 无视频输入时最多 7 张图像，有视频输入时最多 4 张图像。
其他收费、价格、平台等信息暂未提供。