KovAPIKovAPI
kling-image-4.0-long

Kling Image 4.0 Long · API

POST https://kovapi.com/v1/images/generations

可灵 Kling Image 4.0 的长图模式(Beta):一次生成一整页电商详情页或网页设计长图。1K / 2K,交付带 C2PA 内容凭证的 PNG 原图,按类型、篇幅和分辨率计费。

在 Playground 试用 →

快速开始

和其他图片接口一样是异步任务:提交得到任务 id,轮询拿结果。电商详情页必须带 1–3 张商品图;网页设计可以只写文字。

第 1 步:提交电商详情页任务(skill、length、resolution 和商品图)

curl
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "为第 1 张图里的保温杯做电商详情页:主视觉、三个卖点、使用场景,中文文案;只使用图里能看到的商品信息,不编造参数", "skill": "ecommerce", "length": "medium", "resolution": "1K", "images": ["https://example.com/mug.jpg"]}'

返回(HTTP 202)

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "kling-image-4.0-long"
}

第 2 步 · 每 2–3 秒查询一次,直到 status 变成 succeeded 或 failed

curl
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

成功时的返回

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "kling-image-4.0-long",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "kling-image-4.0-long"}
}

第 3 步:下载 data[0].url,这是可灵交付的 PNG 长图原图(宽 1024 / 2048 像素,高度随内容),保留 7 天。

完整示例(Python:提交 → 等待 → 保存到本地)

Python
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 网页设计:不带图也可以
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "kling-image-4.0-long",
    "prompt": "为精品咖啡店「北行咖啡」设计官网首页:顶部大图和标题、三款招牌豆、品牌故事、页脚,中文文案,温暖极简风格",
    "skill": "webpage",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-image-4.0-long.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

认证

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在控制台创建 API Key 后即可调用。

请求参数

POST /v1/images/generations 的请求体(JSON):

参数类型必填说明
modelstring是模型 id:kling-image-4.0-long。
promptstring是画面描述。图生图时写清楚要怎么改。
skillstring否长图类型:ecommerce(电商详情页,images 里要有 1–3 张商品图)或 webpage(网页设计)。不写时:带图按 ecommerce,不带图按 webpage。
lengthstring否电商详情页篇幅:short(约 2–5 个模块)、medium(默认,约 6–10 个)、long(约 11–18 个);网页设计不用写。
resolutionstring否1K(默认,宽 1024 像素)或 2K(宽 2048 像素);没有 4K。
image / imagesstring / array否电商详情页:1–3 张商品图(必填)。网页设计:最多 2 张,默认第 1 张是主体参考、第 2 张是风格参考。jpg / png,每边至少 300 像素,宽高比 2:5–5:2;每张另收 $0.003。
image_rolesarray否只用于网页设计:和 images 一一对应,每项 subject 或 style,各最多一张,如 ["style", "subject"]。
ninteger否每次只出 1 张长图:n 只能是 1。
callback_urlstring否任务结束时把结果推送到这个地址,见下文的 Webhook。

价格

按张计费,价格看类型、篇幅和分辨率;每张参考图另收 $0.003。提交时预扣,失败全额退回。

类型1K · 积分 / 张1K · 美元 / 张2K · 积分 / 张2K · 美元 / 张
电商详情页 · 短47$0.23556$0.28
电商详情页 · 中94$0.47109$0.545
电商详情页 · 长156$0.78172$0.86
网页设计109$0.545119$0.595

尺寸与格式

  • 宽度固定:1K 为 1024 像素,2K 为 2048 像素;高度随内容(11-20 实测 4,257–16,270 像素)。
  • PNG 原图,带 C2PA 内容凭证,不裁切、不缩放;2K 长图可能有几十 MB。
  • 每次只返回一张完整长图,不返回 HTML 或可编辑的设计文件。

写提示词

  • 写清页面用途、语言、模块顺序、卖点和文案。想要哪种语言的文案,提示词就用那种语言写,并写明「中文文案」。
  • 只写真实的商品信息,并写明「只使用提供的商品信息,不编造参数」:模型会照写,也可能自己补充。
  • 提示词里可以用 @image1、@image2 指代第 1、2 张图。

任务状态与返回字段

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):1K 约 1.5–2.5 分钟,2K 约 2.5 分钟;篇幅越长越慢,高峰时可能更久。

错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx,不建任务、不扣费;提交成功后的失败写在查询结果里,预扣的积分全额退回。全部错误码见 错误码。

提交时返回的错误

HTTPcode原因怎么办
400missing_prompt/v1/images/generations 没有 prompt。补上 prompt。
400invalid_request参考图读不到(链接打不开、不是图片、超过 16MB 等,message 写明是第几张、什么原因),/v1/images/edits 没带参考图,或请求体不是 JSON 对象、n 不是整数。按 message 修改后重新提交。
400unsupported_resolution这个模型不提供所选的分辨率档位(例如 Grok 生图没有 4K)。换一个档位;各模型支持的档位见它的文档。
400model_not_found型号写错、没有传 model,或这个型号不能用在这个接口上(例如拿对话模型调生图接口)。以 GET /v1/models 或 API 手册 里的模型 id 为准。
401invalid_api_keyKey 不存在、已删除或已停用,或者账号已停用。到控制台「API Keys」页面检查这把 Key。
402insufficient_quota余额不够预扣这一单。网关先按这一单可能的最高费用预扣,同时发很多请求时也可能出现。如果是并发突发,稍等几秒重试;否则充值。
429rate_limit_exceeded超过了这把 Key 设置的每分钟请求数(按最近 60 秒计)。不带 Retry-After。等几秒再试,或在控制台调高这把 Key 的上限。
503model_maintenance型号维护中,暂停接单,期间不会改由其他模型作答。维护结束后重试,进度见 服务状态。
503service_unavailable我们这边临时出错,例如保存参考素材失败;/v1/responses 暂时无法处理时也返回 503,并带 Retry-After。稍后重试。

任务失败(status 为 failed)

code什么时候出现怎么办
moderation_blocked图片:模型方的安全审核拒绝了提示词或参考图(也可能是 content_policy_violation)。改写提示词或更换参考图;原样重交通常还会被拒。
upstream_error其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。通常重新提交就能成功。

用 Webhook 代替轮询

提交时加上 callback_url,任务一结束(成功或失败),网关就把和查询接口完全一样的结果推送到这个地址,带签名,失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 Webhook 文档 →

curl · callback_url
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "为精品咖啡店「北行咖啡」设计官网首页:顶部大图和标题、三款招牌豆、品牌故事、页脚,中文文案,温暖极简风格", "skill": "webpage", "callback_url": "https://your-domain.com/webhook"}'