Kling 4.0
Generate a video from a prompt, images or an existing video, billed by the output length.
Kling 4.0 (product kling) generates a video from a prompt, images or a video you already have. Each mode has its own page with its parameters, price and request examples:
mode | What it does | Docs |
|---|---|---|
text_to_video | Text to video: generated from a prompt alone. | Text to Video |
image_to_video | Image to video: from a first frame, optionally with keyframes and a last frame. | Image to Video |
reference_to_video | Reference to video: the people, objects or scenes in your reference images appear in a new video, optionally guided by reference videos. | Reference to Video |
video_edit | Video edit: an existing video changed as your prompt says. | Video Edit |
This page has the rules every mode shares.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "kling-4.0" and one of the modes above. Parameters every mode takes:
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | kling-4.0. |
mode | string | Yes | text_to_video, image_to_video, reference_to_video or video_edit. |
aspect_ratio | string | Yes | auto, 21:9, 16:9, 9:16 or 1:1. What auto does depends on the mode, see its page. |
resolution | string | Yes | 720p or 1080p. |
duration | integer | Yes, except video_edit | Output length in seconds, 3–30. It's what you pay for, see Pricing. Only video_edit can leave it out: the output then follows the video you edit, see Video Edit. |
webhook_url | string | No | Notified when the task succeeds or fails. See Webhooks. |
- Required parameters: every mode needs
aspect_ratioandresolution, and every mode exceptvideo_editneedsduration; there are no defaults. Whetherprompt,image_urls,video_urlandvideo_urlsare required, optional or not accepted depends on the mode: see its page. - Parameter checks: a parameter that breaks the mode's rules (for example
image_urlswithtext_to_video,video_urlswithimage_to_video, orvideo_editwithoutvideo_url) returns400 invalid_requestwithparamset to that parameter, and no task is created. - Response:
200 OK, the same short task as for every model (see Create a task: Response), withdata.modelkling-4.0. Keepdata.idto get the result. - The endpoint usually responds in under 1 second, and the cost is frozen within a few seconds.
Get the result
A video usually takes 1–5 minutes, occasionally around 10. Once the task has finished (succeeded or failed), get the result either way:
- Webhook (recommended in production): if you passed
webhook_url, the full task is pushed to it once when the task finishes. See Webhooks. - Polling: call
GET /v1/tasks/{task_id}withdata.idat most once every 15 seconds untilstatusissucceededorfailed. Check several tasks at once withidsin List tasks.
| Field | Kling 4.0 |
|---|---|
outputs[0].url | The generated video. |
outputs[0].preview_url | A silent, compressed copy for previews, see Outputs. |
billing.billed_seconds | The duration you asked for; for a video_edit without duration, the actual output length. |
input | What you sent, including aspect_ratio and duration (a video_edit sent without duration has none). prompt, image_urls, video_url and video_urls only appear if you sent them. |
On failure the frozen amount is returned in full and the reason is in data.error.type, see Errors. Every field is described in The task object.
Media
All media is passed as public http(s) URLs. There's no upload endpoint: host the files yourself. URLs are at most 4096 characters, must download directly and can't point to localhost or private, loopback or reserved addresses.
| Parameter | What it is | Modes |
|---|---|---|
image_urls | Images: frames or reference images, up to 10. | image_to_video, reference_to_video, video_edit |
video_url | The video to edit. | video_edit |
video_urls | Reference videos. | reference_to_video (up to 5), video_edit (up to 4) |
Which ones a mode requires is on its page. Every video (video_url and each video_urls entry) must meet these requirements:
| Video requirement | Otherwise the task fails with |
|---|---|
| Each video 3–30 seconds | video_too_short / video_too_long |
All of a task's videos together at most 30 seconds (so a 30-second video_url can't carry reference videos) | video_too_long |
| 720p or higher (at least 720 pixels on the short side) | invalid_media |
| Aspect ratio at most 2.5:1 (pure black bars don't count) | invalid_media |
An image or video that can't be downloaded or read (corrupt, unsupported format) fails the task with invalid_media.
Kling 4.0 reads every file only after the task is submitted for generation, a few seconds after creation, once the cost has been frozen: none of the above is checked when the task is created. If a file can't be used, the frozen amount is returned in full. Keep every link reachable until the task finishes, including links that expire.
Referring to files in the prompt
In prompt | Refers to |
|---|---|
@Image1 … @Image10 | The images in image_urls, in order. |
@Video1, @Video2, … | reference_to_video: the video_urls entries, in order. video_edit: @Video1 is video_url (the video to edit), @Video2 on are the video_urls entries. |
Pricing
cost = duration × price per second of the mode and resolutionLoading the current prices…
Billed seconds are the duration you ask for (3–30). They don't depend on your images, or on how long your videos are.
reference_to_videowith reference videos (video_urls) is billed at thevideo_editprice per second, see Reference to Video → Pricing.video_editwithoutduration: 30 × the price per second is frozen first; when the task succeeds, the actual output length is charged and the difference returned. See Video Edit → Pricing.
Example: text_to_video at 720p for 10 seconds freezes 10 × its 720p price per second and is charged the same when it succeeds; if it fails, all of it is returned. How freezing and charging work in general: Billing.
Except for a video_edit without duration, the price is known from the request alone, so you can show it before submitting: read the current prices from GET /v1/products, one prices row per mode and resolution (the row's mode; there's no separate row for reference_to_video with reference videos, it uses the video_edit row). Prices change, so don't hard-code them. billing.frozen on the retrieved task is what counts.
Errors
Errors and failure reasons specific to Kling 4.0. Every error of the create endpoint: Create a task → Errors; every failure reason: Failure reasons.
Create request errors: the request fails with an HTTP error and no task is created.
| Status | error.type | When | What to do |
|---|---|---|---|
400 | invalid_request | A parameter breaks the mode's rules: a required one is missing (every mode needs aspect_ratio and resolution, every mode except video_edit also duration), one the mode doesn't take was sent, there are too many images or videos, or aspect_ratio, resolution or duration isn't an allowed value. param names the parameter and message says what's wrong, for example duration is required for mode text_to_video or video_urls is not allowed for mode image_to_video. Each mode's rules are on its page. | Fix the parameter param names and send the request again. |
Task failures: the create request succeeded (200) and the task later turned failed. There's no HTTP status: the reason is the task's error.type, from retrieving the task or the webhook.
error.type | When | What to do |
|---|---|---|
insufficient_balance | Your available balance can't cover duration × the price per second (for a video_edit without duration, 30 seconds of it). Within a few seconds of creating the task, nothing frozen. | Top up, then create the task again. |
spend_limit_exceeded | This task's cost would go over one of the key's spend limits. Within a few seconds of creating the task, nothing frozen. | Raise the limit in Console → API keys, or wait for it to reset, then create the task again. |
invalid_media | An image or a video can't be downloaded or read (corrupt or an unsupported format), or a video is below 720p or its aspect ratio is beyond 2.5:1. Found when the files are downloaded, a few seconds after the task is submitted. | Replace the file error.message points to and create the task again. |
content_policy | The prompt or a file breaks the content policy: adult content, or a protected likeness or copyrighted material (for example a photo of a public figure). This includes files turned down by the model provider's moderation. Found when the task is submitted or while it's generated; the frozen amount is returned in full. | Resubmitting it as is fails again: change the prompt or the file. |
video_too_short | A video (video_url or a video_urls entry) is shorter than 3 seconds (The video duration must be between 3 and 30 seconds.). Found when the videos are downloaded, a few seconds after the task is submitted; started_at may be null. | Use videos of at least 3 seconds and create the task again. |
video_too_long | A video is longer than 30 seconds, or all of the task's videos together are (The total duration of the videos must be at most 30 seconds.). Found when the videos are downloaded, a few seconds after the task is submitted; started_at may be null. | Trim the videos (or send fewer) so each is 30 seconds or less and they add up to 30 or less, then create the task again. |
error.message states the requirement, not your file's length; the messages are listed under Messages. invalid_media, video_too_short and video_too_long happen after the cost is frozen: billing.frozen keeps the frozen amount, all of it is returned (refunded equals frozen) and billing.charged is "0.00".