快手可灵 Kling Image 4.0(Beta):文生图和参考图生图(最多 10 张),2K / 4K、8 种比例,交付带 C2PA 内容凭证的 PNG 原图。写实质感和图中文字(包括中文)是它的长处。
在 Playground 试用 →快速开始
三步跑通:提交任务 → 查询结果 → 拿到图片链接。把 YOUR_API_KEY 换成你的 Key,下面的命令可以直接运行。
第 1 步 · 提交任务(立刻返回任务号,HTTP 202)
curl https://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "kling-image-4.0", "prompt": "中秋促销海报,正中写大字「月满人团圆」,下方小字「全场八折」,暖金色调,圆月和桂花", "size": "16:9", "resolution": "2K"}'返回(HTTP 202)
{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "queued",
"created": 1791281400,
"model": "kling-image-4.0"
}第 2 步 · 每 2–3 秒查询一次,直到 status 变成 succeeded 或 failed
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \ -H "Authorization: Bearer YOUR_API_KEY"
成功时的返回
{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "succeeded",
"created": 1791281400,
"model": "kling-image-4.0",
"data": [
{"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
],
"usage": {"images": 1, "resolution": "2K", "model": "kling-image-4.0"}
}第 3 步:下载 data[0].url,这是可灵交付的 PNG 原图(带 C2PA 内容凭证),4K 约 30 MB,保留 7 天。
完整示例(Python:提交 → 等待 → 保存到本地)
import time
import requests
BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. 提交任务
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
"model": "kling-image-4.0",
"prompt": "中秋促销海报,正中写大字「月满人团圆」,下方小字「全场八折」,暖金色调,圆月和桂花",
"size": "16:9",
"resolution": "2K",
}).json()
if "error" in job:
raise SystemExit(job["error"]["message"])
# 2. 每 3 秒查询一次,直到结束
while job["status"] not in ("succeeded", "failed"):
time.sleep(3)
job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
# 3. 下载图片
if job["status"] == "succeeded":
url = job["data"][0]["url"]
with open("kling-image-4.0.png", "wb") as f:
f.write(requests.get(url).content)
print("saved", url)
else:
print("failed:", job["error"]["code"], job["error"]["message"])认证
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
在控制台创建 API Key 后即可调用。
请求参数
POST /v1/images/generations 的请求体(JSON):
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型 id:kling-image-4.0。 |
| prompt | string | 是 | 画面描述。图生图时写清楚要怎么改。 |
| size | string | 否 | 比例:1:1(默认)、16:9、9:16、4:3、3:4、3:2、2:3、21:9。也可以写像素尺寸(如 2720x1536),按比例对到上面 8 种之一;其他比例提交时返回 400,不扣费。 |
| resolution | string | 否 | 档位:2K(默认)或 4K,没有 1K 和 8K(写 1K 提交时返回 400,不扣费)。 |
| image / images | string / array | 否 | 参考图:image 传一张,images 传多张,最多 10 张,可以是图片链接、data: URI 或 base64;格式 jpg / png,每边至少 300 像素,宽高比在 2:5 到 5:2 之间。提示词里用 @image1、@image2 按顺序指代,并写清每张图的用途。每张参考图另收 $0.003。 |
| n | integer | 否 | 每次只出 1 张:n 只能是 1。要多张请同时提交多个任务。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址,见下文的 Webhook。 |
其他 OpenAI 参数(quality、style、background、response_format 等)不生效。每次出 1 张 PNG 原图;参考图每张另收 $0.003,在提交时一起预扣。
价格
按张计费,价格只看档位,跟比例、文生图还是图生图无关。提交时按档位预扣,任务失败全额退回。1 积分 = $0.005。
| 档位 | 积分 / 张 | 美元 / 张 |
|---|---|---|
| 2K | 12 | $0.06 |
| 4K | 18 | $0.09 |
比例、分辨率与输出尺寸
每种比例、每个档位都是固定的原生尺寸(11-20 实测),交付原图,不裁切、不缩放;4K 每边是 2K 的两倍。
| 比例 | 2K | 4K |
|---|---|---|
| 1:1 | 2048x2048 | 4096x4096 |
| 16:9 | 2720x1536 | 5440x3072 |
| 9:16 | 1536x2720 | 3072x5440 |
| 4:3 | 2336x1760 | 4672x3520 |
| 3:4 | 1760x2336 | 3520x4672 |
| 3:2 | 2496x1664 | 4992x3328 |
| 2:3 | 1664x2496 | 3328x4992 |
| 21:9 | 3136x1326 | 6272x2651 |
- 只出这 8 种比例;写其他比例(如 9:21、1:2)提交时返回 400,不扣费。
- size 也可以写像素尺寸(如
5440x3072):按比例对到上表,长边超过 3200 像素按 4K,否则按 2K;写了 resolution 时以 resolution 为准。
图生图与参考图
- 传
image(一张)或images(多张,最多 8 张,多出的不用)就是图生图,在提示词里写清楚要怎么改。也可以调用POST /v1/images/edits,参数相同。 - 两个接口都只收 JSON 请求体,不支持 multipart 上传文件,所以 OpenAI SDK 的
images.edit()不能直接用,请按下面的示例传链接或 base64。 - 每张参考图可以是公网图片链接(http / https)、data: URI 或纯 base64,单张不超过 16MB,JPEG、PNG、WebP 等常见格式都可以。
- 链接要能直接下载到图片本身,不能是网页、需要登录或有防盗链的地址。读不到的参考图会在提交时直接返回 400,写明是哪一张、什么原因,不建任务、不扣费。
- 参考图最多 10 张(jpg / png,每边至少 300 像素,宽高比 2:5–5:2),提示词里用 @image1、@image2 按顺序指代并写清用途;没提到的参考图也会参与生成。每张参考图另收 $0.003。
- 参考图由我们代为托管,保留 7 天。
两张参考图的图生图
curl https://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "kling-image-4.0", "prompt": "保留画面里的人物,把背景换成夜晚的海边,加上暖色的灯串", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'任务状态与返回字段
GET /v1/images/jobs/{id} 返回的状态如下,每个字段的说明见 异步任务。建议每 2–3 秒查一次,或者用 Webhook。
| 状态 | 含义 |
|---|---|
| queued | 排队中。返回里带 queue_position(前面还有几个任务)和 eta_seconds(预计等待秒数)。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 data[0].url,计费明细在 usage。 |
| failed | 失败。原因在 error,预扣的积分已全额退回。 |
同一个账号最多 50 个任务同时生成,更多的任务按提交顺序排队;排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天,图片链接保留 7 天。
出图时间
实测(11-20):2K 33–52 秒,4K 57–74 秒,带两张参考图的 2K 约 70 秒;高峰时可能更久。
错误与退款
提交时出错会直接返回 HTTP 4xx / 5xx,不建任务、不扣费;提交成功后的失败写在查询结果里,预扣的积分全额退回。全部错误码见 错误码。
提交时返回的错误
| HTTP | code | 原因 | 怎么办 |
|---|---|---|---|
| 400 | missing_prompt | /v1/images/generations 没有 prompt。 | 补上 prompt。 |
| 400 | invalid_request | 参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。 | 按 message 修改后重新提交。 |
| 400 | model_not_found | 型号写错、没有传 model,或这个型号不能用在这个接口上(例如拿对话模型调生图接口)。 | 以 GET /v1/models 或 API 手册 里的模型 id 为准。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用,或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣,同时发很多请求时也可能出现。 | 如果是并发突发,稍等几秒重试;否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数(按最近 60 秒计)。不带 Retry-After。 | 等几秒再试,或在控制台调高这把 Key 的上限。 |
| 503 | model_maintenance | 型号维护中,暂停接单,期间不会改由其他模型作答。 | 维护结束后重试,进度见 服务状态。 |
| 503 | service_unavailable | 我们这边临时出错,例如保存参考素材失败;/v1/responses 暂时无法处理时也返回 503,并带 Retry-After。 | 稍后重试。 |
任务失败(status 为 failed)
| code | 什么时候出现 | 怎么办 |
|---|---|---|
| moderation_blocked | 图片:模型方的安全审核拒绝了提示词或参考图(也可能是 content_policy_violation)。 | 改写提示词或更换参考图;原样重交通常还会被拒。 |
| upstream_error | 其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。 | 通常重新提交就能成功。 |
用 Webhook 代替轮询
提交时加上 callback_url,任务一结束(成功或失败),网关就把和查询接口完全一样的结果推送到这个地址,带签名,失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 Webhook 文档 →
curl https://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "kling-image-4.0", "prompt": "中秋促销海报,正中写大字「月满人团圆」,下方小字「全场八折」,暖金色调,圆月和桂花", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'