Kling Image 4.0
Generate 1–4 images at 2k, 4k or 8k from a prompt, optionally guided by reference images, billed per image.
Kling Image 4.0 (product kling_image) generates images at 2k, 4k or 8k from a prompt, optionally guided by up to 10 reference images. One task makes 1–4 images, billed per image.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "kling-image-4.0".
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <API key>, see Authentication. |
Content-Type | Yes | application/json |
Idempotency-Key | No | A unique string for every new task, ideally a UUID (1–255 characters). See Preventing duplicate tasks. |
Body
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | kling-image-4.0 |
prompt | string | Yes | What to generate, at most 8000 characters. Refer to the reference images as @Image1, @Image2…, see Referring to images. |
image_urls | string[] | No | Up to 10 reference images; leave it out to generate from the prompt alone. See Media. |
resolution | string | Yes | 2k, 4k or 8k. Sets the price. |
aspect_ratio | string | Yes | auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 or 21:9. auto follows the reference images, and gives 1:1 without them. |
num_outputs | integer | Yes | How many images, 1–4. All of them are frozen; only the ones generated are charged, see Pricing. |
webhook_url | string | No | Notified when the task succeeds or fails: https, up to 2048 characters, not a private, loopback or reserved address. See Webhooks. |
Any other parameter, such as another model's seed or quality, is a request error.
One 2k image from a reference photo:
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
}'Response: 200 OK, the new task (fields). Keep data.id to get the result; the task can still fail, see Errors.
{
"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"
}
}Get the result
As a rough guide (generation only, not counting the queue, plus a few seconds to store the files; slower when the provider is busy): about 1.5 minutes at 2k. The images of a task are generated in parallel, so several take about as long as one. Get the result through the webhook if you sent webhook_url, or poll GET /v1/tasks/{task_id} at most once every 15 seconds until status is succeeded or failed (several tasks at once: ids in List tasks).
The request above once it has succeeded (other fields omitted; all fields: The task object):
{
"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 × the 2k price per image
"charged": "…", // the same
"refunded": "0.00",
"billed_seconds": null
}
}| Field | Kling Image 4.0 |
|---|---|
outputs | One item per generated image, at most num_outputs. |
outputs[].type | image |
outputs[].url | The original image, a PNG, for downloading or full-size display. The files are large, an 8k original most of all: don't load it in lists. |
outputs[].preview_url | A JPEG preview, at most 1024 pixels on the long side, for lists and thumbnails, see Outputs. |
billing.billed_seconds | Always null: images are billed per image. |
input | The parameters you sent; the optional image_urls only if you sent it. |
The image size follows resolution and aspect_ratio (with auto, the reference images): with a 4:3 photo.jpg, the result above is 2336×1760.
Fewer images than requested
Each image is generated on its own. If some can't be made (for example because moderation blocked them), the task still succeeded: outputs only has the images that were generated, fewer than num_outputs. Only those are charged and the rest of the frozen amount is returned (billing.refunded). The task fails only when no image could be generated, and then everything frozen is returned: if at least one of them was blocked by moderation, the reason is content_policy (not every image has to be blocked, the others may have failed for other reasons), otherwise usually generation_failed. outputs[].index numbers the generated images from 0 without gaps, so when there are fewer it doesn't match the position in your request: don't use it to pair images with anything.
Media
Reference images go in image_urls as public http(s) URLs that download directly: at most 4096 characters, not localhost or a private, loopback or reserved address, and valid until the task finishes (including signed URLs that expire). There's no upload endpoint.
Reference images (image_urls) | |
|---|---|
| Count | 0–10 (limits.max_reference_images in GET /v1/products) |
| Formats | JPEG, PNG, WebP, AVIF, GIF (the first frame), BMP and TIFF. HEIC / HEIF aren't supported: iPhone photos are HEIC by default, so convert them to JPEG first. |
| Transparency | A transparent PNG is flattened onto white before it's used. |
| If there's a problem | Read only when generation runs, after freezing: an image that can't be downloaded or isn't in a supported format fails the task with invalid_media, refunded in full. |
Referring to images in the prompt
In prompt | Refers to |
|---|---|
@Image1, @Image2, … | The images in image_urls, in order. |
- A reference beyond the images you sent (for example
@Image2with one image, or any@Imagewithoutimage_urls) is a request error withparamprompt. - An
@right after a letter, digit or dot isn't a reference, so an email address such asbob@image2go.comin the prompt is fine.
Pricing
frozen = price per image of the resolution × num_outputs
charged = price per image of the resolution × images generatedLoading the current prices…
- Only
resolutionchanges the price.aspect_ratioand reference images don't. - The cost of images that aren't generated is returned, see Fewer images than requested.
Current prices, to show the cost before submitting: GET /v1/products (one prices row per resolution). The task's billing.frozen is the amount that counts; freezing and charging: Billing.
Errors
Request errors
A request that fails returns an HTTP error, and no task is created:
{
"code": 400,
"message": "Field required",
"error": {
"type": "invalid_request",
"param": "resolution",
"details": null
},
"request_id": "rq_01jb8z9x2c4v6b8n0m1q3w5e7r"
}| HTTP status | error.type | Description |
|---|---|---|
| 400 | invalid_request | A required parameter is missing, a value breaks the rules in the parameter table, or a parameter isn't accepted; param names it |
| 401 | invalid_api_key | The API key is invalid, deleted or has been reset |
| 402 | insufficient_balance | Your available balance is 0 |
| 402 | spend_limit_exceeded | One of the API key's spend limits is used up |
| 403 | account_suspended | Your account has been suspended |
| 409 | idempotency_key_reused | The Idempotency-Key was already used with a different request body |
| 429 | rate_limited | Too many requests |
| 500 | internal_error | A server error; the task may have been created |
details and how to handle each error: Create a task → Errors.
Task failures
A created task can still fail: its status turns failed and the reason is in error, with no HTTP status. A failed task is never charged; anything frozen is returned in full.
{
"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 | Description |
|---|---|
invalid_media | A reference image can't be downloaded or read (for example a HEIC photo or a corrupt file) |
content_policy | The prompt or a reference image breaks the content policy (adult content, a protected likeness or copyrighted material): no image was generated and at least one was blocked; when only some are blocked the task still succeeds, see Fewer images than requested |
insufficient_balance | Your available balance can't cover this task |
spend_limit_exceeded | This task would go over one of the API key's spend limits |
generation_failed | Generation failed |
queue_timeout | Not started within 30 minutes of being queued |
internal_error | An internal error |
Branch on error.type; message is an English explanation for developers and may change. When each reason can happen, whether anything was frozen, and the message texts: Failure reasons.