Kling Image 4.0
用提示词生成 1–4 张 2k、4k 或 8k 的图片,可以带参考图,按张计费。
Kling Image 4.0(产品 kling_image)用提示词生成 2k、4k 或 8k 的图片,可以带最多 10 张参考图。一个任务生成 1–4 张,按张计费。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口,model 传 "kling-image-4.0"。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>,见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串,建议用 UUID(1–255 个字符),见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | kling-image-4.0 |
prompt | string | 是 | 描述要生成的图片,最长 8000 字符。引用参考图写 @Image1、@Image2…,见在提示词里引用图片 |
image_urls | string[] | 否 | 参考图,最多 10 张;不传时仅根据提示词生成。见素材 |
resolution | string | 是 | 2k、4k 或 8k,决定价格 |
aspect_ratio | string | 是 | auto、1:1、16:9、9:16、4:3、3:4、3:2、2:3 或 21:9。auto 跟随参考图的比例,没有参考图时为 1:1 |
num_outputs | integer | 是 | 生成张数,1–4。按该张数冻结,仅按实际生成的张数扣费,见价格 |
webhook_url | string | 否 | 任务成功或失败时通知该地址:https,最长 2048 字符,不能指向内网、回环或保留地址。见回调 |
传了其他参数(例如其他模型的 seed、quality)属于请求错误。
用一张参考照片生成 1 张 2k 的图:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-image-4.0",
"prompt": "Turn the photo @Image1 into a watercolor painting",
"image_urls": ["https://example.com/photo.jpg"],
"resolution": "2k",
"aspect_ratio": "auto",
"num_outputs": 1
}'响应:200 OK,返回新建的任务(字段说明)。保存 data.id,用它获取结果;任务创建后仍可能失败,见错误。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jbn7d2k9w4x6z8c1v3b5m7q9",
"model": "kling-image-4.0",
"status": "queued",
"error": null,
"created_at": "2026-11-18T08:30:00Z"
}
}获取结果
耗时仅供参考(开始生成到出图,不含排队,另加几秒转存;上游忙时会更慢):2k 约 1.5 分钟。同一个任务的多张图并行生成,生成多张的总耗时与单张相近。传了 webhook_url 时通过回调获取结果,否则轮询 GET /v1/tasks/{task_id},间隔不少于 15 秒,直到 status 为 succeeded 或 failed(多个任务用列出任务的 ids 一次查询)。
上面的请求成功后(省略了其他字段,完整字段见任务对象):
{
"status": "succeeded",
"input": {
"prompt": "Turn the photo @Image1 into a watercolor painting",
"image_urls": ["https://example.com/photo.jpg"],
"resolution": "2k",
"aspect_ratio": "auto"
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "image",
"url": "https://cdn.nanoapi.ai/h/tk_01jbn7d2k9w4x6z8c1v3b5m7q9_1_1794990690.png",
"preview_url": "https://cdn.nanoapi.ai/h/tk_01jbn7d2k9w4x6z8c1v3b5m7q9_1_1794990690_compressed.jpg"
}
],
"billing": {
"currency": "USD",
"frozen": "…", // 1 × 2k 的每张单价
"charged": "…", // 相同
"refunded": "0.00",
"billed_seconds": null
}
}| 字段 | Kling Image 4.0 |
|---|---|
outputs | 每张生成出来的图片一项,最多 num_outputs 项 |
outputs[].type | image |
outputs[].url | PNG 原图,用于下载或查看大图。文件很大,8k 原图尤其大,不要在列表里加载 |
outputs[].preview_url | JPEG 预览图,长边不超过 1024 像素,用于列表和缩略图,见结果 |
billing.billed_seconds | 始终为 null:图片按张计费 |
input | 传入的参数;可选的 image_urls 仅在传入时返回 |
出图尺寸由 resolution 和 aspect_ratio 决定(auto 时跟随参考图):photo.jpg 是 4:3 时,上面的结果是 2336×1760。
张数比请求的少
每张图单独生成。有几张没生成出来(例如被内容审核拦下)时,任务仍是 succeeded,outputs 里只有生成出来的那几张,比 num_outputs 少。只按这几张扣费,冻结金额的其余部分退回(billing.refunded)。一张都没生成出来时任务才是 failed,冻结金额全额退回:其中只要有 1 张是被内容审核拦下的,失败原因就是 content_policy(不一定每张都被拦,其余几张可能是别的原因),否则一般是 generation_failed。outputs[].index 按生成出来的那几张从 0 连续编号,张数比请求的少时不对应请求里的第几张,不要用它与请求中的图片对应。
素材
参考图放在 image_urls 里,以公开、可直接下载的 http(s) 链接传入:最长 4096 字符,不能指向 localhost 或内网、回环、保留地址,任务结束前必须保持可访问(有有效期的签名链接也一样)。不提供上传接口。
参考图(image_urls) | |
|---|---|
| 数量 | 0–10 张(GET /v1/products 的 limits.max_reference_images) |
| 格式 | JPEG、PNG、WebP、AVIF、GIF(取第一帧)、BMP、TIFF。不支持 HEIC / HEIF:iPhone 照片默认是 HEIC,请先转成 JPEG |
| 透明背景 | 透明背景的 PNG 会铺成白底再使用 |
| 有问题时 | 生成时才读取,此时费用已冻结:无法下载或格式不支持时任务失败(invalid_media),全额退回 |
在提示词里引用图片
prompt 里写 | 指代 |
|---|---|
@Image1、@Image2… | image_urls 里的图片,按顺序编号 |
- 引用超出了传入的张数(例如只传了 1 张却写了
@Image2,或者没传image_urls却写了@Image)属于请求错误,param为prompt。 @前面是字母、数字或点的不算引用,所以提示词里写邮箱(例如bob@image2go.com)没有问题。
价格
冻结 = 所选分辨率的每张单价 × num_outputs
扣费 = 所选分辨率的每张单价 × 生成出来的张数正在读取当前价格…
- 只有
resolution影响价格;aspect_ratio和参考图都不影响。 - 未生成的图片的费用退回,见张数比请求的少。
当前单价见 GET /v1/products(prices 里每个分辨率一行,可以在提交前算出费用),以任务的 billing.frozen 为准;冻结和扣费规则见计费。
错误
请求错误
请求出错时返回 HTTP 错误,不会创建任务:
{
"code": 400,
"message": "Field required",
"error": {
"type": "invalid_request",
"param": "resolution",
"details": null
},
"request_id": "rq_01jb8z9x2c4v6b8n0m1q3w5e7r"
}| HTTP 状态码 | error.type | 说明 |
|---|---|---|
| 400 | invalid_request | 缺少必填参数、取值不符合参数表的要求,或传了不支持的参数;param 指出是哪个参数 |
| 401 | invalid_api_key | API Key 无效、已删除或已重置 |
| 402 | insufficient_balance | 可用余额为 0 |
| 402 | spend_limit_exceeded | API Key 的消费限额已用满 |
| 403 | account_suspended | 账号已停用 |
| 409 | idempotency_key_reused | 同一个 Idempotency-Key 用在了请求体不同的请求上 |
| 429 | rate_limited | 请求过于频繁 |
| 500 | internal_error | 服务端错误,任务可能已创建 |
details 字段和处理方式见创建任务 → 错误。
任务失败
任务创建后仍可能失败:status 变为 failed,原因在 error 中,没有 HTTP 状态码。失败的任务不扣费,已冻结的金额全额退回。
{
"status": "failed",
"error": {
"type": "invalid_media",
"message": "A reference image could not be read. It may be corrupted or in an unsupported format."
}
}error.type | 说明 |
|---|---|
invalid_media | 参考图无法下载或无法读取(例如 HEIC 照片、文件损坏) |
content_policy | 提示词或参考图不符合内容政策(不适宜内容、受保护的肖像或版权内容):所有张都没生成出来且至少一张被审核拦下;只有部分被拦时任务仍成功,见张数比请求的少 |
insufficient_balance | 可用余额不足以支付本次费用 |
spend_limit_exceeded | 本次费用会超出 API Key 的消费限额 |
generation_failed | 生成失败 |
queue_timeout | 排队超过 30 分钟未开始 |
internal_error | 内部错误 |
程序判断请用 error.type;message 是面向开发者的英文说明,措辞可能调整。各原因的出现阶段、是否冻结过费用和 message 原文见失败原因。