# Kling Image 4.0 Long — /images/generations

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

**端点:** `POST https://kovapi.com/v1/images/generations`

## 快速开始

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

**第 1 步：提交电商详情页任务（skill、length、resolution 和商品图）**

```
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）

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

**第 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-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：提交 → 等待 → 保存到本地）**

```
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"])
```

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求参数

`POST /v1/images/generations` 的请求体（JSON）：

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

## 价格

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

| 类型 | 1K · 积分 / 张 | 1K · 美元 / 张 | 2K · 积分 / 张 | 2K · 美元 / 张 |
| --- | --- | --- | --- | --- |
| 电商详情页 · 短 | 47 | $0.235 | 56 | $0.28 |
| 电商详情页 · 中 | 94 | $0.47 | 109 | $0.545 |
| 电商详情页 · 长 | 156 | $0.78 | 172 | $0.86 |
| 网页设计 | 109 | $0.545 | 119 | $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}` 返回的状态如下，每个字段的说明见 [异步任务](https://docs.kovapi.com/zh/guide/async-jobs#fields)。建议每 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，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见 [错误码](https://docs.kovapi.com/zh/guide/errors)。

### 提交时返回的错误

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` 没有 `prompt`。 | 补上 `prompt`。 |
| 400 | invalid_request | 参考图读不到（链接打不开、不是图片、超过 16MB 等，`message` 写明是第几张、什么原因），`/v1/images/edits` 没带参考图，或请求体不是 JSON 对象、`n` 不是整数。 | 按 `message` 修改后重新提交。 |
| 400 | unsupported_resolution | 这个模型不提供所选的分辨率档位（例如 Grok 生图没有 4K）。 | 换一个档位；各模型支持的档位见它的文档。 |
| 400 | model_not_found | 型号写错、没有传 `model`，或这个型号不能用在这个接口上（例如拿对话模型调生图接口）。 | 以 `GET /v1/models` 或 [API 手册](https://docs.kovapi.com/zh/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 | 型号维护中，暂停接单，期间不会改由其他模型作答。 | 维护结束后重试，进度见 [服务状态](https://kovapi.com/zh/status)。 |
| 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 文档 →](https://docs.kovapi.com/zh/webhooks)

```
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"}'
```
