aliyun-kling-video

Kling V3 视频生成

验证

mkdir -p output/aliyun-kling-video
python -m py_compile skills/ai/video/aliyun-kling-video/scripts/generate_kling_video.py && echo "py_compile_ok" > output/aliyun-kling-video/validate.txt

通过标准：命令以 0 退出，且生成 output/aliyun-kling-video/validate.txt。

输出和证据

• 将任务 ID、轮询响应和最终视频 URL 保存到 output/aliyun-kling-video/。
• 至少保留一份端到端运行日志，以便排查问题。

前置条件

• 安装依赖项（建议在 venv 中安装）：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install requests

• 在环境中设置 DASHSCOPE_API_KEY（必须使用北京地域的 API Key）。
• 在百炼控制台启用 Kling——搜索“kling”并激活。

关键模型名称

• kling/kling-v3-video-generation — 标准模型：t2v、i2v（首帧、首帧+尾帧）
• kling/kling-v3-omni-video-generation — omni 模型：增加参考生成视频、视频编辑、多主体参考

功能

功能	模型	所需媒体
文本生成视频	两者	无
智能分镜（多镜头）	两者	无（使用 multi_prompt）
图像生成视频（首帧）	两者	first_frame
图像生成视频（首帧+尾帧）	两者	first_frame + last_frame
参考生成视频	仅 omni	refer 和/或 feature
视频编辑	仅 omni	base + 可选的 refer

API 端点（仅异步）

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

必需的请求头：

• Authorization: Bearer $DASHSCOPE_API_KEY
• Content-Type: application/json
• X-DashScope-Async: enable

地域：仅限北京。没有新加坡端点。

规范化接口

请求（输入）

• prompt（字符串，有条件必填）— 最多 2500 个字符。shot_type=intelligence 时必填。对于 omni 参考生成视频，请使用 <<<element_1>>>、<<<image_1>>>、<<<video_1>>> 引用媒体。
• negative_prompt（字符串，可选）— 要排除的内容
• media（数组，可选）— 包含 type 和 url 的媒体对象：
  • 标准模型类型：first_frame、last_frame
  • Omni 模型类型：first_frame、last_frame、refer、base、feature
• multi_shot（布尔值，可选）— 启用多镜头生成（默认值：false）
• shot_type（字符串，有条件必填）— intelligence（AI 自动拆分）或 customize（手动）。当 multi_shot=true 时必填。
• multi_prompt（数组，可选）— shot_type=customize 时用于每个镜头的提示词
• element_list（数组，可选）— 多主体元素图像（仅 omni 模型）
• keep_original_sound（字符串，可选）— no（默认值）或 yes，适用于视频（仅 omni 模型）

请求（参数）

• mode（字符串，可选）— pro（默认值，1080P）或 std（720P）
• aspect_ratio（字符串，有条件必填）— 16:9（默认值）、9:16、1:1。对于 t2v 和参考生成视频必填。
• duration（整数，可选）— 视频时长 [3, 15] 秒（默认值：5）。使用参考视频时为 [3, 10]。
• audio（布尔值，可选）— 生成音频（默认值：false）。会影响定价。
• watermark（布尔值，可选）— 添加“可灵 AI”水印（默认值：false）

媒体输入限制

图像（first_frame、last_frame、refer）：

• 格式：JPEG、JPG、PNG（不支持透明度）
• 分辨率：每边 [300, 8000] 像素
• 最大大小：10MB

视频（base、feature）：

• 格式：mp4、mov
• 时长：3-10 秒
• 分辨率：每边 [720, 2160] 像素
• 帧率：24-60 fps
• 最大大小：200MB

媒体组合规则

kling/kling-v3-video-generation：

• i2v 首帧：first_frame（1 张图像）
• i2v 首帧+尾帧：first_frame + last_frame（各 1 张）

kling/kling-v3-omni-video-generation（包含以上全部功能，此外还支持）：

• 参考：仅 feature（1 个视频），或仅 refer（最多 7 个，可包含元素），或 feature+refer（1 个视频 + 最多 4 个，可包含元素），或 feature+first_frame（1 个视频 + 1 张图像）
• 视频编辑：仅 base（1 个视频），或 base+refer（1 个视频 + 最多 4 个，可包含元素）

响应（任务创建）

• output.task_id（字符串）— 有效期 24 小时
• output.task_status（字符串）— PENDING | RUNNING | SUCCEEDED | FAILED | CANCELED
• request_id（字符串）

响应（任务结果）

• output.video_url（字符串）— 生成的视频 URL
• output.watermark_video_url（字符串）— 带水印的视频 URL
• usage.duration（整数）、usage.size（字符串）、usage.fps（整数）、usage.audio（布尔值）

快速开始（Python + HTTP）

import os
import json
import time
import requests

API_KEY = os.getenv("DASHSCOPE_API_KEY")
BASE_URL = "https://dashscope.aliyuncs.com/api/v1"

def create_kling_task(req: dict) -> str:
    """Create a Kling video generation task and return task_id."""
    payload = {
        "model": req.get("model", "kling/kling-v3-video-generation"),
        "input": {"prompt": req.get("prompt", "")},
        "parameters": {
            "mode": req.get("mode", "pro"),
            "duration": req.get("duration", 5),
            "audio": req.get("audio", False),
            "watermark": req.get("watermark", False),
        },
    }
    if req.get("aspect_ratio"):
        payload["parameters"]["aspect_ratio"] = req["aspect_ratio"]
    if req.get("negative_prompt"):
        payload["input"]["negative_prompt"] = req["negative_prompt"]
    if req.get("media"):
        payload["input"]["media"] = req["media"]

    resp = requests.post(
        f"{BASE_URL}/services/aigc/video-generation/video-synthesis",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
            "X-DashScope-Async": "enable",
        },
        json=payload,
    )
    resp.raise_for_status()
    data = resp.json()
    return data["output"]["task_id"]


def poll_task(task_id: str, interval: int = 15) -> dict:
    """Poll until task completes. Returns final response."""
    while True:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        resp.raise_for_status()
        data = resp.json()
        status = data["output"]["task_status"]
        if status in ("SUCCEEDED", "FAILED", "CANCELED"):
            return data
        time.sleep(interval)

使用示例

# Text-to-video
task_id = create_kling_task({
    "prompt": "一只小猫在月光下奔跑",
    "aspect_ratio": "16:9",
    "duration": 5,
    "mode": "std",
})

# Image-to-video (first frame)
task_id = create_kling_task({
    "prompt": "花朵绽放的延时摄影",
    "media": [{"type": "first_frame", "url": "https://example.com/flower.jpg"}],
    "duration": 5,
})

# Reference-to-video with omni model
task_id = create_kling_task({
    "model": "kling/kling-v3-omni-video-generation",
    "prompt": "一只<<<element_1>>>在月光下奔跑",
    "media": [{"type": "refer", "url": "https://example.com/cat.jpg"}],
    "aspect_ratio": "16:9",
})

错误处理

错误	可能原因	操作
401/403	缺少或无效的 API Key	检查环境变量，必须使用北京区域
400 InvalidParameter	媒体组合不正确或缺少必需参数	根据模型的媒体规则进行验证
"does not support synchronous calls"	缺少 X-DashScope-Async: enable 请求头	添加必需的请求头
429	速率限制或配额限制	采用退避策略重试

输出位置

• 默认输出：output/aliyun-kling-video/videos/
• 使用 OUTPUT_DIR 覆盖基础目录。

反模式

• 请勿使用 kling/kling-v3-video-generation 或 kling/kling-v3-omni-video-generation 以外的模型名称。
• 请勿同步调用此 API——必须使用异步请求头。
• 请勿在标准模型中使用 refer、base 或 feature 媒体类型——这些类型仅适用于 omni。
• 请勿混用不兼容的媒体组合。
• 视频 URL 会过期；请立即下载并持久化保存。
• 仅限北京区域——请勿使用新加坡端点。

工作流

1. 确认用户意图：t2v、i2v、参考图转视频、编辑或分镜。
2. 选择合适的模型（基本 t2v/i2v 使用标准模型，参考图/编辑使用 omni）。
3. 准备包含正确类型和有效 URL 的媒体数组。
4. 创建异步任务并轮询结果。
5. 在 URL 过期前下载并保存生成的视频。

参考资料

• 完整的 HTTP API 详情请参阅 references/api_reference.md。
• 来源链接请参阅 references/sources.md。