how-tos

Kling Image 4.0 API 指南:用 cURL 和 Python 发出第一个请求

Poyo.ai Team
5 min read
Share:

Kling Image 4.0 API 指南:用 cURL 和 Python 发出第一个请求

这篇 Kling Image 4.0 API 指南带你从拿到 API 密钥一路走到得到成品图像:一次 cURL 调用、一个有超时上限的 Python 轮询循环,以及 kling-4.0-image 和 kling-4.0-long-image 每种输入模式下可直接使用的 JSON 请求体。每种模式都可以先在 Kling Image 4.0 在线试用中尝试;下面所有请求体都遵循 PoYo 文档。

用 cURL 发出第一个 Kling Image 4.0 API 请求

在 PoYo 控制台创建一个密钥,以 POYO_API_KEY 的形式保存在你的服务器上。然后提交一个 2K 文生图任务:

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-image",
    "input": {
      "prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
      "size": "16:9",
      "resolution": "2K"
    }
  }'

响应包含 code: 200 和 data.task_id,status: "not_started"。任务提交成功不等于图像已生成。用下面的命令查询:

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。为 finished 时,data.files 中每张图像对应一项,包含 file_url 和 file_type: "image",data.credits_amount 显示该任务的费用。为 failed 时,读取 data.error_message。

有超时上限的 Python 轮询循环

下面的代码在你的后端使用 requests 运行。它同时检查 HTTP 状态码和响应体中的 code 字段(校验错误可能以 HTTP 200 加 code: 400 的形式返回),遇到 failed 即停止,等待 20 分钟后放弃,且不会重新提交,因为第二次提交就是第二笔费用。

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(resp):
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
    return body["data"]

def run(payload, max_wait=1200, every=10):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    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":
            return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
        time.sleep(every)
    raise TimeoutError("still running, poll task " + task_id + " again later")

urls = run({
    "model": "kling-4.0-image",
    "input": {
        "prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
        "size": "1:1",
        "resolution": "2K",
    },
})
print(urls)

对于耗时较长的任务,可以改为在请求体顶层加上 "callback_url": "https://your-domain.com/poyo-hook"。任务完成或失败时,PoYo 会 POST 同样的任务数据(不带 code/data 包装),并在 X-Webhook-Signature 中附上 HMAC-SHA256 签名;验签方法见 webhook 文档。

用 image_urls 做图生图

在 image_urls 中传入 1 到 10 个公开的 HTTP(S) URL。按数组顺序,第一张是 @Image1,第二张是 @Image2。在提示词中为每张图指定作用,并说明哪些内容必须保持不变。

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "resolution": "2K"
  }
}

即使只有一张图,image_urls 也必须是数组。每张图片最大 30 MB,宽和高至少 300 px,宽高比在 0.4 到 2.5 之间。

用 kling_elements 保持主体一致

一个元素(element)是从 2 到 4 个角度展示的一个角色或物体,正面视图在前。使用元素时至少要有一个 image_urls 项,最多可传 7 个元素;图片加元素上限为 10。

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "kling_elements": [
      {
        "element_input_urls": [
          "https://example.com/character-front.png",
          "https://example.com/character-side.png",
          "https://example.com/character-back.png"
        ]
      }
    ],
    "resolution": "2K"
  }
}

这个请求的费用是 2K 图像 13 积分,加参考图 1 积分和元素 1 积分:共 15 积分($0.075)。

用 enable_sequential 生成组图

设置 enable_sequential: true 时,n 取值 2 到 10(默认 4),模型会把这些图像作为一组来规划,主体和风格一致,并按顺序返回。关闭时,n 取 1 到 9,返回彼此独立的图像。

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
    "size": "3:2",
    "enable_sequential": true,
    "n": 4
  }
}

在我们发布当天的测试中(PoYo 生产 API,2026 年 11 月 19 日),一组 16:9、2K、n: 4 的组图返回了四张 2720×1536 图像,骑手、车和服装在黎明、正午、日落和夜晚中保持一致。费用为 52 积分,从提交到出结果约 4.9 分钟。

网页与电商长图

把模型 ID 换成 kling-4.0-long-image 并选择一个 skill。下面是一个网页设计,可选择参照一张风格参考图:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
    "skill": "webpage",
    "style_image_url": "https://example.com/style-reference.png",
    "resolution": "2K"
  }
}

基于一张商品图生成电商详情页:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
    "skill": "ecommerce",
    "image_urls": ["https://example.com/water-bottle.png"],
    "length": "medium",
    "resolution": "1K"
  }
}

提示:写明页面语言。 在我们的测试中,一条英文网页提示词没有说明文案应使用哪种语言,返回的页面上是中文。在提示词中加上 "All text on the page is in English." 后问题解决,这也是上面两个请求体都以这句话结尾的原因。我们的 1K 网页测试返回一张 1024×4257 图像,费用 110 积分,耗时约 1.7–2.2 分钟。

image_urls 和 length 属于 ecommerce;style_image_url 和 subject_image_url 属于 webpage。页面长度和 8K 输出的更多内容见 用 Kling Image 4.0 API 生成 8K 与长图。

保存结果

每个 files[].file_url 指向一张 PNG。请把它复制到你自己的存储中,而不是在应用里直接外链。发布当天的测试中有三点需要提前规划:

  • 体积。 一张 16:9 8K 图像是 10880×6144 的 PNG,约 128 MB。请以流式方式写入磁盘,不要整个读进内存,并调大客户端的读取超时。
  • Alpha 通道。 即使是不透明图像,下载到的也是 RGBA PNG。如果你的流程、CDN 或印刷工作流需要 RGB 或 JPEG,请在下载后转换。
  • 顺序。 组图按顺序返回,因此 files 中的索引就是分镜或幻灯片的帧序号。

提交前值得检查的校验规则

规则模型
prompt 1–50,000 个字符,不能只有空白两者
image_urls 1–10 项;每张 30 MB、≥300 px、宽高比 0.4–2.5kling-4.0-image
kling_elements ≤ 7,每个 2–4 个 URL,仅可与 image_urls 一起使用;图片 + 元素 ≤ 10kling-4.0-image
非组图时 n 为 1–9,enable_sequential: true 时为 2–10kling-4.0-image
resolution 为 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" 需要 1–3 个 image_urls;resolution 为 1K / 2Kkling-4.0-long-image
不允许多余字段(output_format、seed、negative_prompt 会被拒绝)两者

需要处理的错误

code含义处理方式
400参数无效修正请求体;不要原样重试
401API 密钥缺失或无效检查请求头
402积分不足充值后重新提交
429触发限流退避,稍后重试
500 / 502 / 503服务器或上游错误带退避重新提交

failed 的任务不扣费,因此失败后重新提交是安全的。但你这边超时后重新提交则不安全:应先继续轮询同一个 task_id。

第一笔账单如何计算

kling-4.0-image 的费用为单张价格乘以图像数量,再加上每个 image_urls 项和每个元素各 1 积分,每次请求计一次。按 1 积分 = $0.005 计算:

请求积分美元
上面第一个 cURL 调用(2K,一张)13$0.065
同一提示词,8K32$0.16
上面的元素编辑(2K,1 张图 + 1 个元素)15$0.075
四张 2K 组图52$0.26
1K 网页,无参考图110$0.55
1K medium 电商页面,1 张商品图95$0.475

完整价格表和更多示例见 Kling Image 4.0 API 价格。两个模型 ID 的概览见 Kling Image 4.0 是什么。

常见问题

如何用 Python 调用 Kling Image 4.0 API? 用 requests 把 JSON 请求体 POST 到 https://api.poyo.ai/api/generate/submit,读取 data.task_id,然后轮询 /api/generate/status/{task_id} 直到 finished,再读取 files[].file_url。上面的循环实现了这一流程,并带有截止时间和错误检查。

Kling Image 4.0 API 的模型 ID 是什么? 文生图、编辑和组图用 kling-4.0-image,网页和电商长图用 kling-4.0-long-image。kling-4-0-image 只是页面 slug。

Kling Image 4.0 API 支持 webhook 吗? 支持。在请求顶层加上 callback_url。任务完成或失败时,PoYo 会发送一个带签名的 POST。

Kling Image 4.0 API 能输出 JPEG 吗? 没有输出格式字段,结果为 PNG。我们下载到的即使是不透明图像也是 RGBA PNG,如需 JPEG 请自行转换。

为什么我的 Kling Image 4.0 长网页返回了另一种语言? 如果提示词没有指定页面文案的语言,模型可能自行选择。请写明语言,例如 "All text on the page is in English."

Share: