Kling 4.0 API 入门：用 Python 和 cURL 生成第一条视频

PoYo 的 Kling 4.0 API 使用统一模型 ID kling-4.0，支持文生视频、首尾帧生成、参考素材生成和视频编辑。基本流程是提交请求、保存任务 ID，再查询到任务完成。本文参数核对日期为 2026 年 10 月 24 日，以 PoYo 当前接口为准。

可以先在 Kling 4.0 在线体验页验证输入，再参考 API 文档接入后端。不同平台的字段名称和支持范围可能不同，不能直接混用。

用 cURL 提交第一条视频

在终端环境变量中设置 POYO_API_KEY，然后提交下面的 5 秒请求。密钥应保存在服务端，不要打包进浏览器代码。

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-4.0",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

提交成功后，读取返回 JSON 中的 data.task_id。提交成功只表示任务已受理，不代表视频已经生成。把真实任务 ID 填入下面的查询地址：

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

任务状态包括 not_started、running、finished 和 failed。完成后检查 data.files，视频文件的 file_url 就是结果地址；失败时检查 error_message，并保留任务 ID 排查。查询旧任务不需要再次提交生成请求。

Python：有限等待，避免重复提交

安装 requests 后，可在服务端运行以下代码。它同时检查 HTTP 错误与业务错误，遇到失败会终止，最长等待 30 分钟。超时后应继续查询已保存的任务，而不是自动提交第二个付费任务。

import os
import time
import requests

base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    task = checked(session.get(
        base + "/api/generate/status/" + task_id, timeout=60))
    if task["status"] == "failed":
        raise RuntimeError(task.get("error_message") or "Generation failed")
    if task["status"] == "finished":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

按目标选择输入模式

只要提供 video_url，接口就优先进入编辑模式。image_urls 中第一张图控制开头，第二张图控制结尾；reference_image_urls 用来引导人物、商品或视觉风格，不等同于时间轴边界。

提交前检查这些限制

生成时长为 3–30 秒整数，分辨率为 720p 或 1080p。PoYo 当前普通提示词上限是 26,000 字符。使用 multi_prompt 时，每个镜头提示词最多 512 字符，省略镜头时长按 5 秒处理；镜头时长总和必须在 3–30 秒内，显式传入的顶层 duration 必须与总和一致。

参考模式最多支持 10 张图片、5 段视频、7 个主体，合计不超过 15 项。首帧也占图片数和总素材数。每段参考或主体视频的真实时长须为 3–30 秒，所有参考与主体视频加起来最多 30 秒。不能把超限素材的秒数向下取整后提交。

第一笔费用怎么估算

当前标价下，不带视频输入的 5 秒 720p 请求为 142.5 credits，约 $0.7125。加入视频输入后，单价和计费时长都会变化，参考视频与编辑任务请先阅读计费示例。

官方创作端宣传的多关键帧等能力，不能直接当作 PoYo API 字段。这里公开的是至多两张首尾帧和分镜提示词；不要向接口加入并不存在的 keyframes、seed、negative_prompt 或 generate_audio。接下来可以阅读提示词指南和全能参考教程。

常见问题

模型 ID 是 kling-4-0 吗？ 不是。网页路径使用连字符，API 请求使用 kling-4.0。

这里能请求 4K 吗？ 当前 PoYo 接口只接受 720p 和 1080p，应以实际接入平台的 schema 为准。

可以使用回调吗？ 提交请求支持顶层 callback_url。本文示例使用轮询，回调的接收方式请查看最新文档。

推荐从哪里开始？ 先跑通短时长文生视频，保存请求、任务 ID 和结果，再逐项增加图片或视频输入。