Kuaishou's Kling Image 4.0 (Beta): text-to-image and image-to-image with up to 10 references, 2K / 4K in 8 ratios, delivered as the original PNG with its C2PA content credential. Photoreal texture and in-image text, Chinese included, are its strengths.
Try in Playground →Quick start
Three steps: submit a job, poll it, take the image link. Replace YOUR_API_KEY with your key and the commands below run as they are.
Step 1 · Submit (returns a job id at once, 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": "A Mid-Autumn sale poster, big headline “Full Moon Reunion” in the centre, small line “20% off everything” below, warm gold tones, full moon and osmanthus", "size": "16:9", "resolution": "2K"}'Response (HTTP 202)
{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "queued",
"created": 1791281400,
"model": "kling-image-4.0"
}Step 2 · Poll every 2–3 seconds until status is succeeded or failed
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \ -H "Authorization: Bearer YOUR_API_KEY"
Response when it succeeds
{
"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"}
}Step 3: download data[0].url, Kling's original PNG (with its C2PA content credential); 4K is about 30 MB, kept for 7 days.
Complete example (Python: submit, wait, save to disk)
import time
import requests
BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. submit
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
"model": "kling-image-4.0",
"prompt": "A Mid-Autumn sale poster, big headline “Full Moon Reunion” in the centre, small line “20% off everything” below, warm gold tones, full moon and osmanthus",
"size": "16:9",
"resolution": "2K",
}).json()
if "error" in job:
raise SystemExit(job["error"]["message"])
# 2. poll every 3 seconds until it finishes
while job["status"] not in ("succeeded", "failed"):
time.sleep(3)
job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
# 3. download the image
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"])Authentication
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
Create an API Key in the console to start.
Request parameters
The JSON body of POST /v1/images/generations:
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | The model id: kling-image-4.0. |
| prompt | string | Yes | What to draw. For image-to-image, say what to change. |
| size | string | No | Aspect ratio: 1:1 (default), 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9. A pixel size (e.g. 2720x1536) is matched to one of these 8 by its ratio; any other ratio returns 400 at submit and nothing is charged. |
| resolution | string | No | Tier: 2K (default) or 4K; there is no 1K or 8K (1K returns 400 at submit, nothing charged). |
| image / images | string / array | No | References: one in image, several in images, up to 10, as an image URL, a data: URI or base64; jpg / png, at least 300 px on each side, aspect ratio between 2:5 and 5:2. Refer to them in order as @image1, @image2 in the prompt and say what each one is for. Each reference image costs $0.003 more. |
| n | integer | No | One image per request: n must be 1. Submit several jobs for several images. |
| callback_url | string | No | Where to push the result when the job ends; see Webhooks below. |
Other OpenAI parameters (quality, style, background, response_format and so on) have no effect. Each request makes one original PNG; each reference image costs $0.003 more, held together with the image at submit.
Price
Billed per image by tier only: aspect ratio, text-to-image or image-to-image make no difference. The tier price is held when you submit and refunded in full if the job fails. 1 credit = $0.005.
| Tier | Credits per image | USD per image |
|---|---|---|
| 2K | 12 | $0.06 |
| 4K | 18 | $0.09 |
Aspect ratio, resolution and output size
Each ratio and tier has one fixed native size (measured 11-20); you get the original, never cropped or resized. 4K is twice 2K on each side.
| Aspect ratio | 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 |
- Only these 8 ratios; any other (9:21, 1:2 and so on) returns 400 at submit and nothing is charged.
- size also takes a pixel size (e.g.
5440x3072): it is matched to the table by ratio, and a longest side over 3200 px means 4K, otherwise 2K; resolution, when given, decides.
Image-to-image and reference images
- Send
image(one picture) orimages(several, up to 8; any beyond 8 are not used) and the job runs image-to-image; say in the prompt what to change.POST /v1/images/editstakes the same parameters. - Both endpoints take a JSON body only, not a multipart file upload, so the OpenAI SDK's
images.edit()cannot be used as is: pass links or base64 as in the example below. - Each reference can be a public image URL (http or https), a data: URI or plain base64, up to 16MB each, in a common format such as JPEG, PNG or WebP.
- A URL has to download the image itself: not a web page, and not behind a login or hotlink protection. A reference we cannot read is refused at submit with a 400 that says which one and why; no job is created and nothing is charged.
- Up to 10 references (jpg / png, at least 300 px a side, aspect ratio 2:5-5:2); refer to them in order as @image1, @image2 and say what each is for; references you do not mention still count. Each reference image costs $0.003 more.
- We host the references for you and keep them for 7 days.
Image-to-image with two references
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": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'Job status and fields
GET /v1/images/jobs/{id} reports these statuses; every field is described in Async jobs. Poll every 2–3 seconds, or use a webhook.
| Status | Meaning |
|---|---|
| queued | Waiting in line. Carries queue_position (jobs ahead of yours) and eta_seconds (expected wait). |
| processing | Rendering. |
| succeeded | Done. The result is in data[0].url, the billing detail in usage. |
| failed | Failed. The reason is in error; the credits held for the job are refunded in full. |
One account runs up to 50 jobs at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days and image links for 7 days.
How long it takes
Measured on 11-20: 2K in 33-52 s, 4K in 57-74 s, 2K with two references about 70 s; peaks can be slower.
Errors and refunds
An error at submit comes back at once as HTTP 4xx / 5xx: no job is created and nothing is charged. A failure after the job was accepted is reported by the job endpoint, and the hold is refunded in full. Every code is listed under Error codes.
Errors at submit
| HTTP | code | Cause | What to do |
|---|---|---|---|
| 400 | missing_prompt | /v1/images/generations has no prompt. | Add a prompt. |
| 400 | invalid_request | A reference image cannot be read (dead link, not an image, over 16MB...; message says which one and why), /v1/images/edits has no reference image, the body is not a JSON object, or n is not an integer. | Fix what message says and submit again. |
| 400 | model_not_found | The model id is misspelled, model is missing, or the model cannot be used on this endpoint (a chat model on the image endpoint, for example). | Use a model id from GET /v1/models or the API reference. |
| 401 | invalid_api_key | The key does not exist, was deleted or is disabled, or the account is disabled. | Check the key on the API Keys page of the console. |
| 402 | insufficient_quota | Not enough balance to hold this request. The gateway holds the highest possible cost of the request first, so a burst of concurrent calls can trigger it too. | After a burst, wait a few seconds and retry; otherwise top up. |
| 429 | rate_limit_exceeded | Over the requests-per-minute limit set on this key (counted over the last 60 seconds). No Retry-After header. | Wait a few seconds and retry, or raise the key's limit in the console. |
| 503 | model_maintenance | The model is under maintenance and takes no requests; no other model answers in its place meanwhile. | Retry when maintenance ends; see Status. |
| 503 | service_unavailable | A temporary failure on our side, such as storing a reference file; /v1/responses also answers 503, with Retry-After, when it cannot take requests for a moment. | Retry shortly. |
Failed jobs (status failed)
| code | When you see it | What to do |
|---|---|---|
| moderation_blocked | Image: the model provider's safety system refused the prompt or a reference image (the code may also be content_policy_violation). | Rewrite the prompt or replace the reference; resubmitting it unchanged is usually refused again. |
| upstream_error | Any other failure: the automatic retries did not help, the job waited 15 minutes without starting, the upstream refused without a reason, and so on; message says which. | Submitting again usually works. |
Webhooks instead of polling
Add callback_url when you submit and the moment the job ends, success or failure, the gateway pushes exactly what the poll endpoint returns to that URL, signed and retried on failure. You can also set an account-wide address under Settings → Webhook in the console. Webhook docs →
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": "A Mid-Autumn sale poster, big headline “Full Moon Reunion” in the centre, small line “20% off everything” below, warm gold tones, full moon and osmanthus", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'