Python 中的 Kling 3.0 Turbo 图生视频 API：Schema、完整脚本与错误处理

kling-3.0-turbo/image-to-video 的 Schema 小巧且严格：一个公开图片 URL、必填的运动提示词、3 到 15 秒的整数时长，以及 720p 或 1080p 的输出。本页是该版本的专属参考，用于校验该请求体，并区分 HTTP 400 错误与异步 TASK_FAILED 结果。

关于通用的创建、轮询、回调与下载流程，请使用 Kling Python 任务运行器与 Omni/Turbo 选择指南。

Turbo 输入 Schema

字段	类型	是否必填	可接受的值
prompt	string	是	描述运动与镜头行为
image_urls	字符串数组	是	恰好一个可公开访问的图片 URL
duration	integer	否	3 至 15 秒
resolution	string	否	720p 或 1080p

Turbo 不接受 sound、aspect_ratio、negative_prompt、seed、mode，也不接受第二个图片 URL。严格 Schema 会拒绝额外属性，而不是静默忽略。

输入图片决定画面形状。创建任务前，请将其上传到公开的存储桶或 CDN；渲染器无法抓取 localhost、私有仪表盘以及已过期的签名 URL。

最小可用请求

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/image-to-video",
    "input": {
      "prompt": "The runner accelerates as the camera tracks from the side",
      "image_urls": ["https://cdn.example.com/first-frame.jpg"],
      "duration": 6,
      "resolution": "1080p"
    }
  }'

成功的响应包含 data.taskId。HTTP 200 仅表示创建成功，而非完成；视频渲染仍在异步进行。

Python 预校验

在网络调用前先校验约束，让明显的错误永远不会创建任务：

from urllib.parse import urlparse

import requests


def turbo_input(prompt: str, image_url: str, duration: int, resolution: str) -> dict:
    if not prompt.strip():
        raise ValueError("prompt is required")
    if type(duration) is not int or not 3 <= duration <= 15:
        raise ValueError("duration must be an integer from 3 to 15")
    if resolution not in {"720p", "1080p"}:
        raise ValueError("resolution must be 720p or 1080p")
    parsed = urlparse(image_url)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError("image_url must be a public HTTP(S) URL")

    return {
        "prompt": prompt,
        "image_urls": [image_url],
        "duration": duration,
        "resolution": resolution,
    }


payload = {
    "model": "kling-3.0-turbo/image-to-video",
    "input": turbo_input(
        prompt="The runner accelerates as the camera tracks from the side",
        image_url="https://cdn.example.com/first-frame.jpg",
        duration=6,
        resolution="1080p",
    ),
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer sk-your-key"},
    json=payload,
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
print(task_id)

此本地检查能发现值的形态问题，但无法证明远程图片可被公开下载。渲染器会在创建任务后执行该抓取。

完整 Python 脚本：提交、轮询、下载

上面的代码片段止于任务 ID。此版本运行完整作业并保存 MP4。它会发送 Idempotency-Key 头，因此超时后重试同一提交会返回原始任务，而不会创建并计费第二个任务：

import os
import time
import uuid

import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}


def run_turbo(prompt: str, image_url: str, duration: int = 5,
              resolution: str = "720p", out_path: str = "turbo.mp4") -> str:
    body = {
        "model": "kling-3.0-turbo/image-to-video",
        "input": turbo_input(prompt, image_url, duration, resolution),
    }
    key = str(uuid.uuid4())  # reuse this key if you retry the same submission
    r = requests.post(API, json=body, headers={**HEADERS, "Idempotency-Key": key}, timeout=30)
    if r.status_code == 400:
        raise ValueError(f"schema error, no task created: {r.text}")
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 900
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if data["status"] == "success":
            video = requests.get(data["output"][0]["url"], timeout=120)
            video.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(video.content)  # the output URL is temporary, so save it now
            return out_path
        if data["status"] == "fail":
            raise RuntimeError(f"TASK_FAILED {task_id}: {data.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)


print(run_turbo(
    "The runner accelerates as the camera tracks from the side",
    "https://cdn.example.com/first-frame.jpg",
))

这样一段 5 秒 720p 的片段费用为 $0.65。在生产环境中，请用顶层 "callback": {"url": "https://your-app.example.com/hiapi/callback"} 替代轮询循环，并按任务 ID 对通知去重。

HTTP 400：任务从未创建

HTTP 400 响应是同步 Schema 校验的结果。典型原因包括：

无效输入	为何失败	修复方式
"duration": "5"	发送了字符串而非整数	改为发送 5
"duration": 20	最大值为 15	选择 3–15
两个 image_urls	Turbo 只接受一个	只保留起始帧
"resolution": "4K"	Turbo 支持 720p 和 1080p	使用 720p 或 1080p，或选择 Omni
"sound": true	sound 不在 Turbo Schema 中	移除该字段或选择 Omni
缺少 prompt	Turbo 需要提示词	添加非空的运动提示词

由于校验在创建前就已失败，没有任务 ID 可供轮询。记录响应体与请求 ID，修正请求体后重新提交新请求。

TASK_FAILED：创建成功，但渲染失败

如果 POST /v1/tasks 返回 HTTP 200 和任务 ID，后续失败属于异步任务生命周期问题，应与 400 区分对待。

常见原因包括：

• 图片 URL 需要 Cookie 或授权头；
• 签名图片 URL 在渲染器抓取前已过期；
• 主机阻止服务端抓取，或重定向到 HTML 页面；
• 文件损坏，或其媒体类型与内容不符；
• 服务商无法完成该次渲染。

记录任务 ID、最终错误码与消息、原始输入 URL 及请求时间。重试前，请确认未经认证的服务器能以 2xx 响应和图片内容类型抓取该图片。盲目重试同一不可访问的 URL 只会再创建一个失败任务。

通用 Python 指南 包含共用的终态轮询循环与输出下载代码；将其保留在那里，可避免在本版本参考页重复生命周期逻辑。

Turbo 定价与模型选择

当前生产费率为：

Turbo 档位	每秒价格	5 秒任务
720p	$0.130	$0.65
1080p	$0.160	$0.80

大批量使用前，请查看实时定价页。Turbo 这一名称描述的是模型变体，并不承诺每个分辨率都更便宜，也不承诺任务会满足固定的渲染时间 SLA。

当你需要尾帧、音频或 4K 时，请选择标准 Kling 3.0（kling-3.0/image-to-video）：它接受一张或两张图片（起始帧与结束帧），带有 sound 开关，720p 无音频时 $0.10/s，1080p 无音频时 $0.129/s。当你需要参考图或参考视频时，请选择 Omni。对于 720p 或 1080p 的单输入帧，请用自己的运动提示词对这些变体进行基准测试，并评估输出质量、排队时间与总成本。

常见问题

Kling 3.0 Turbo 图生视频接受多少张图片？

恰好一个公开图片 URL。第二个图片会触发 Schema 错误（image_urls: maxItems: got 2, want 1）；如需首尾帧控制，请使用标准 Kling 3.0 图生视频。

哪些时长值有效？

发送 3 到 15 的整数。像 "5" 这样的带引号数字是字符串，会校验失败。

Turbo 支持 4K 或音频吗？

不支持 4K：此端点接受 720p 或 1080p。没有 sound 字段，但 Turbo 片段自带音频，且无法关闭。当你需要 4K 或无声输出时，请使用标准 Kling 3.0 或 Omni。

HTTP 400 与 TASK_FAILED 有什么区别？

HTTP 400 表示请求违反 Schema，因此未创建任务。TASK_FAILED 发生在有效的创建响应之后，位于输入抓取或生成阶段。

为什么看似公开的图片 URL 会导致 TASK_FAILED？

该 URL 可能依赖 Cookie、签名已过期、阻止服务端抓取，或返回 HTML 而非图片字节。重试前，请在不带浏览器认证的情况下测试它。