kling-video-generator

Kling 3.0 Omni 视频生成器

此技能可使用 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 调用之前，必须先根据用户请求设计提示词。提示词的质量是获得良好结果的最重要因素。

1. 参考提示词指南：阅读 /home/ubuntu/skills/kling-video-generator/references/prompt_guide.md，了解编写有效提示词的核心原则、官方公式和少样本示例。

2. 确定场景：判断用户请求属于以下哪种场景：

   • 单镜头视频（基于文本、图像或视频）
   • 多镜头视频（包含多个场景的分镜脚本）

3. 编写提示词：

   • 对于单镜头，按照指南中的公式编写一条详细提示词。
   • 对于多镜头，为每个镜头／场景分别编写提示词。
   • 使用模板语法：如果用户提供了参考图像、元素或视频，必须在提示词中使用 <<<image_1>>>、<<<element_1>>>、<<<video_1>>> 模板语法来明确引用它们。这是 Omni 模型的一项核心功能。

阶段 2：参数构建

准备好提示词后，按照以下决策树构建最终 API 请求载荷。这可确保遵守通过大量测试发现的所有参数约束和依赖关系。

graph TD
    A[Start] --> B{Multi-shot or Single-shot?};
    B -- Multi-shot --> C[Set `multi_shot: true`];
    B -- Single-shot --> D[Set `multi_shot: false`];

    C --> E{Set `shot_type: "customize"`};
    E --> F[Construct `multi_prompt` array from prompts];
    F --> G[Calculate total duration from `multi_prompt`];
    G --> H[Set top-level `duration`];
    H --> Z[Final Payload];

    D --> I{Video input provided?};
    I -- Yes --> J{Editing or Reference?};
    I -- No --> K[Text/Image-to-Video Path];

    J -- Editing --> L[Set `refer_type: "base"`];
    J -- Reference --> M[Set `refer_type: "feature"`];

    L --> N[Ignore `duration` parameter];
    M --> O[Set `aspect_ratio`];
    N --> P{Audio handling};
    O --> P;

    K --> Q{Audio handling};
    P --> R{Audio handling};

    subgraph R [Audio Handling]
        direction LR
        R1{Want audio output?} -- Yes --> R2[Set `sound: "on"`];
        R1 -- No --> R3[Set `sound: "off"`];
        R2 --> R4{Video input exists?};
        R4 -- Yes --> R5[ERROR: `sound:on` is incompatible with video input];
        R4 -- No --> R6[OK];
    end

    Q --> Z;
    R6 --> Z;
    R3 --> Z;
    R5 --> Stop([Stop/Error]);

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

以下并非完整列表，而是对最关键且不易察觉的规则的总结，必须遵守。如需完整指南，请参阅 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	index 必须从 1 开始。总时长必须与顶层 duration 一致。最多 6 个镜头。
aspect_ratio	feature 模式下必填。
image_list	不输入视频时最多 7 张图片；输入视频时最多 4 张图片。

---

执行

要执行视频生成任务，请使用提供的 Python 脚本，该脚本会处理身份验证和轮询。

1. 设置环境变量：确保已设置 KLING_ACCESS_KEY 和 KLING_SECRET_KEY。

2. 构造负载：按照上述工作流为 API 调用创建 JSON 负载。

3. 运行脚本：

   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 的所有细节和限制，从而减少错误并获得更可预测的结果。