
这篇 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.5 | kling-4.0-image |
kling_elements ≤ 7,每个 2–4 个 URL,仅可与 image_urls 一起使用;图片 + 元素 ≤ 10 | kling-4.0-image |
非组图时 n 为 1–9,enable_sequential: true 时为 2–10 | kling-4.0-image |
resolution 为 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce" 需要 1–3 个 image_urls;resolution 为 1K / 2K | kling-4.0-long-image |
不允许多余字段(output_format、seed、negative_prompt 会被拒绝) | 两者 |
需要处理的错误
code | 含义 | 处理方式 |
|---|---|---|
| 400 | 参数无效 | 修正请求体;不要原样重试 |
| 401 | API 密钥缺失或无效 | 检查请求头 |
| 402 | 积分不足 | 充值后重新提交 |
| 429 | 触发限流 | 退避,稍后重试 |
| 500 / 502 / 503 | 服务器或上游错误 | 带退避重新提交 |
failed 的任务不扣费,因此失败后重新提交是安全的。但你这边超时后重新提交则不安全:应先继续轮询同一个 task_id。
第一笔账单如何计算
kling-4.0-image 的费用为单张价格乘以图像数量,再加上每个 image_urls 项和每个元素各 1 积分,每次请求计一次。按 1 积分 = $0.005 计算:
| 请求 | 积分 | 美元 |
|---|---|---|
| 上面第一个 cURL 调用(2K,一张) | 13 | $0.065 |
| 同一提示词,8K | 32 | $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."