Kling 3.0 API：文生视频的请求代码和实测片段

Kling 3.0 的文生视频任务只有一个 POST。接口地址是 https://api.omniakey.com/v1/media/tasks，模型填 kling-3.0，操作填 text_to_video。请求体里有两个必填参数：duration（5、10 或 15 秒）和 mode（std 或 pro）。返回里有一个任务 id，轮询到成功后再下载 MP4。我们 2026 年 10 月 29 日用 5 秒、std 模式跑了两条 1280×720 的片子，文件和画面都量过。

Kling 3.0 的请求体里有什么

请求体一共七个字段，其中 duration 和 mode 是 Kling 必填的两个，决定片长和画质档位。字段名照抄，值按表里的写法填，两个必填项不要漏。

模型页自己的示例发的是 duration 6，还带一个 resolution 字段。这两个值在这里都不对。页面只收 5、10、15 秒，并写明没有单独的 resolution 字段（模型页，2026 年 10 月 29 日核对）。页面的常见问题里，std 对应 720P，pro 对应 1080P。

音频默认就有，页面没有列出开关（2026 年 10 月 29 日核对）。aspect_ratio 只用于文生视频；图生视频由首帧决定画幅，显式传比例会被拒绝。我们这两条都是 5 秒、std、16:9。pro 模式、10 秒和 15 秒、9:16 和 1:1、图生视频和尾帧，都不在这两次里。

结果最受提示词影响。Kling 3.0 提示词指南 讲了提示词的几个部分和镜头写法。

请求代码

一个 Python 文件就能完成提交、轮询和下载。它从环境变量 OMNIAKEY_API_KEY 读 key，创建任务时带上随机的 Idempotency-Key。每次轮询间隔 5 秒，最多 180 次。请求体和下面两条片子一致：模型 kling-3.0，type 填 video，operation 填 text_to_video。duration 5，mode 填 std，画幅 16:9。代码只用 Python 标准库，设好环境变量就能发请求，不需要另装 SDK 或别的依赖。

import json
import os
import time
import urllib.error
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def poll(url, attempts=5):
    for attempt in range(attempts):
        try:
            return request("GET", url)
        except urllib.error.HTTPError as err:
            if err.code < 500 or attempt == attempts - 1:
                raise
        except urllib.error.URLError:
            if attempt == attempts - 1:
                raise
        time.sleep(5 * (attempt + 1))

def text_to_video(prompt, out_path, duration=5, mode="std", aspect_ratio="16:9"):
    body = {
        "model": "kling-3.0",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": prompt},
        "parameters": {"duration": duration, "mode": mode, "aspect_ratio": aspect_ratio},
    }
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    print("task", task, flush=True)
    for _ in range(180):
        time.sleep(5)
        state = poll(f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # signed link: short-lived, so download now
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=300) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

if __name__ == "__main__":
    task = text_to_video(
        "A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on "
        "the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.",
        "paper-boat.mp4",
    )
    print("done", task)

每次轮询都是对任务地址发 GET。循环看 status，不看 progress.percent，后者在出片过程中可能一直是 0。状态离开 queued 和 processing 就停下。succeeded 时从 assets[0].url 下载，其它状态抛出任务自己的错误信息。下载要马上做，因为这条资源链接会过期；过期就再查一次任务，换一条新链接。轮询间隔和次数上限都写在代码里，觉得太慢或太久，直接改这两个数就行。轮询遇到连接断开或服务器 5xx 错误时，最多重试五次，每次多等一会儿。

2026 年 10 月 29 日我们又用同样的设置跑了一次这个文件。第一次轮询时连接断开了，所以现在的轮询会重试。第二次返回的任务 id 是 task_PNB1kPopriUyfcHsXhVWY2hBOEoSUIqM，MP4 量出来 5.04 秒，1280×720，双声道 AAC 音轨。从创建到下载用了 807 秒，前面两条分别是 82.2 秒和 110.7 秒，等待时间差很多，要留出余量。

我们跑的两条片子

两次请求都在 2026 年 10 月 29 日发出，请求体就是上面那组值。纸船的任务 id 是 task_cbOtsBxO75cml3nOmVUu9YG3PkYXW2ja。茶壶的任务 id 是 task_M2Ub1EoCaCUa1FjOZDdWDOuEOS9nRjnt。两条提示词都是原样发出的，任务 id 可以留着排查问题。

纸船

A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.

茶壶

A ceramic teapot sits on a wooden table by a window. Steam rises in slow curls. Soft morning light moves across the table. The camera pushes in slowly. No people, no text.

文件量出来是什么样

剪辑工具在 2026 年 10 月 29 日测量了两个下载文件的尺寸、帧率、时长和音频，都逐项列在下面的列表里，方便对照。

• 纸船 — 尺寸: 1280×720; 帧率: 24.0 fps; 时长: 5.04 秒; 音频: AAC，双声道，44.1 kHz; 平均电平: −50.9 dB; 最大电平: −34.0 dB; 剪接点: 无
• 茶壶 — 尺寸: 1280×720; 帧率: 24.0 fps; 时长: 5.04 秒; 音频: AAC，双声道，44.1 kHz; 平均电平: −54.3 dB; 最大电平: −35.9 dB; 剪接点: 无
• 代码跑出的片段 — 尺寸: 1280×720; 帧率: 24.0 fps; 时长: 5.04 秒; 音频: AAC，双声道，44.1 kHz; 平均电平: −48.4 dB; 最大电平: −20.0 dB; 剪接点: 无

前两条片子的声音很轻：平均电平是 −50.9 dB 和 −54.3 dB，峰值 −34.0 dB 和 −35.9 dB。代码跑出的那条更响，平均电平 −48.4 dB，峰值 −20.0 dB。我们只量了电平，音轨里是什么内容没有测。切镜检测在三条里都没有找到明显或轻微的剪接点，每条都是一镜到底。三条的尺寸、帧率和时长完全一致，对比时不用换算。

画面里发生了什么

两条都照提示词走了，茶壶那条自己多了一点横移。

纸船这条里，船在 5.04 秒里一直待在画面中间，湿漉漉的街道从后面滑过去，看起来就是镜头在跟着船走。暖色路灯的反光一直留在石板上，到最后一帧还在（2026 年 10 月 29 日看帧）。中间没有剪接。

茶壶这条里，蒸汽慢慢卷起来又散掉，早晨的光在木桌面上移动。最后一帧的茶壶比第一帧更大，位置也更靠右下，所以看起来是推近，同时带一点横移。提示词要的是缓慢推近，横移是提示词没有要求的（2026 年 10 月 29 日看帧）。

报错和限制

duration 超出 5、10、15 会返回 HTTP 400 model_price_error。这时不会创建任务（视频 API 文档，2026 年 10 月 29 日核对）。只发这三个整秒值。

创建请求少了 Idempotency-Key 会返回 400 missing_idempotency_key。key 最长 255 个字符。同一个 key 和同一份请求体会返回原任务，HTTP 200，不会重复扣费。同一个 key 换了请求体会返回 409 idempotency_key_reused（媒体 API 总览，2026 年 10 月 29 日核对）。

2026 年 10 月 29 日，用 Python urllib 默认的 User-Agent 发 POST，返回 HTTP 403。正文是 error code: 1010，来自 Cloudflare。换成我们自己的 User-Agent 就通了。创建请求和下载请求都要设 User-Agent。

输出链接是短期的。不要存 assets[].url，过期后重新查任务换一条新的（视频 API 文档，2026 年 10 月 29 日核对）。任务记录在创建后保留 24 小时（媒体 API 总览，2026 年 10 月 29 日核对）。两个 400 都在创建任务时返回，改好请求体再发一次就行。

Kling 3.0 按次计费，不按秒计（视频 API 文档，2026 年 10 月 29 日核对）。当前价格看 OmniaKey 价格页。

常见问题

kling-3.0 支持哪些时长？

5、10、15 秒。其它值返回 HTTP 400 model_price_error，不会创建任务（视频 API 文档，2026 年 10 月 29 日核对）。

std 和 pro 差在哪？

模型页把它们叫作 Standard 和 Pro，std 对应 720P，pro 对应 1080P（2026 年 10 月 29 日核对）。我们只跑了 std，所以我们没有测过两者的差别。

片段有声音吗？

每条都带 AAC 音轨，双声道、44.1 kHz。前两条很轻，平均电平 −50.9 dB 和 −54.3 dB；代码跑出的那条更响，平均电平 −48.4 dB，峰值 −20.0 dB。我们只量了电平，没有判断音轨里是什么。

能不能用一张图开头？

模型页列了图生视频，可以给首帧，也可以再给尾帧（2026 年 10 月 29 日核对）。图生视频由首帧决定画幅，显式传比例会被拒绝。

一条片段要生成多久？

我们 2026 年 10 月 29 日的两次里，纸船用了 110.7 秒，茶壶用了 82.2 秒。两条都是 5 秒、std、16:9。

从 Kling 3.0 模型页 开始，换上你自己的提示词，发同一份请求体就行。