What Kling’s API Actually Expects From You

Chapter 1

Six Models, One Login, and No Obvious Right Answer

A team building a short-form video feature opens Kling's documentation for the first time expecting one endpoint and finds six: Kling 3.0 Turbo, Kling 3.0 and 3.0 Omni, Kling O1, Kling 2.6, and Kling 2.5 Turbo, each with its own request shape and its own list of what it will and won't accept.

The instinct is to reach for whichever one is listed first, or whichever one sounds newest. Neither is a reliable guide. The newest model in this line-up, Kling O1, is built for editing footage that already exists – a base video handed in and reworked – not for the simplest case of turning one photo into a moving clip. The oldest model still supported, Kling 2.5 Turbo, does exactly that simple case and nothing more, which is precisely why some integrations keep using it: fewer parameters means fewer ways for a request to be rejected.

What actually separates the six is not quality so much as capability shape. Some accept a storyboard broken into shots. Some accept a stored character that can be reused across many generations. Some accept a spoken voice. None of them accept all three at once, and the documentation states this model by model rather than in one place – which is why the map above exists before anything else in this book: to answer 'which endpoint' before answering 'which parameters'.

One quiet fact worth sitting with before choosing: the API's own base address changed partway through this documentation's life, from api.klingai.com to api-singapore.klingai.com. An integration built against the old address still works, but every new example in the current documentation uses the new one – a small thing to check before debugging a request that looks otherwise correct.

What you can actually do here

Six models sit behind Kling's API, and none of them is simply 'better' than the others – each one trades away something the others keep. Before writing a single request, this is what decides which endpoint to call.

Choosing a model

Chapter 2

What Actually Has to Be in the Request

Every one of the six models shares the same underlying shape for a request, even though the field names differ slightly between the newer and legacy versions of the API. A request is built from a `contents` array – a list of typed entries, each one a prompt, an image, a video, or a reference to something stored earlier – followed by a `settings` object for output configuration and an `options` object for callbacks and watermarking.

The part that actually breaks requests is rarely the structure. It's the limits sitting inside the field descriptions rather than in a table anywhere. A reference image must be a `.jpg`, `.jpeg` or `.png`, no larger than 50MB in the current API generation (10MB in the legacy one), with both width and height at least 300 pixels and an aspect ratio between 1:2.5 and 2.5:1. A text prompt is capped at 2,500 characters on most endpoints, though Kling O1's Omni model will accept up to 3,072 while still recommending you stay under 2,500.

A reference video for motion control carries its own set of numbers entirely: 3 to 30 seconds long, no larger than 100MB, width and height between 340 and 3,850 pixels, in `.mp4` or `.mov`. Feed it a video outside those bounds and the system doesn't guess – it returns an error code and nothing generates.

None of these numbers are dramatic on their own. Together, they're the actual cause of most failed first requests: an image sized for a website banner that's far wider than 2.5:1, or a phone-recorded clip that runs 45 seconds when the model caps out at 30. Checking dimensions before the call, not after the rejection, is the difference between a working integration and a support ticket.

Chapter 3

Telling One Shot from the Next

Buried inside the plain `prompt` string is a small syntax that turns one generation into several connected scenes. Written as `shot 1, 4, a woman opens a door; shot 2, 3, she steps into sunlight;`, separated by semicolons, this tells the model to produce a sequence of shots rather than one continuous take – shot number, duration in seconds, then the description.

The rule that trips people up is simple once it's stated: every shot's duration must be at least one second, and the durations of all shots together must add up exactly to the total video duration set elsewhere in the request. Miss that arithmetic by even a second and the storyboard doesn't render the way it was written.

Newer models separate this out into a proper `multi_prompt` array instead of packing it into the text string – each entry naming its own index, prompt and duration – which is more structured but means the same discipline about the totals applies either way. Up to six shots are supported, and at least one is required; there's no version of this feature that accepts zero.

The reward for getting it right is a genuinely different kind of output: not a single AI-generated clip that drifts and reinterprets itself over its duration, but something closer to an edited sequence, each beat described on its own terms.

Chapter 4

A Face That Does Not Drift

Generate the same described character twice on most systems and two different faces come back. Kling's answer to this is the Element – a stored reference, created once through the element API and then called back into later generations by ID, so a character's appearance holds steady across many separate outputs rather than being reinvented each time.

Elements come in two forms with different rules attached: a video character element, drawn from footage, and a multi-image element, drawn from a set of stills. How many of each can be combined in one request depends on the model and on whether a reference video is also present – Kling O1 permits up to 7 combined images and elements when there's no reference video, dropping to 4 once one is added.

Reference happens directly inside the prompt text, using an @-symbol followed by the element's assigned name – `@Zhang`, for instance. The documentation is specific about two ways this quietly goes wrong: an element name that's a substring of another one in use (`@Zhang` and `@ZhangSan` in the same task), and an element name that happens to match ordinary text elsewhere in the prompt. Naming an element `@gmail` and later writing 'my email address is test@gmail.com' in the same prompt is enough to confuse which one the model was meant to read as a reference.

None of this is dangerous, exactly – it just produces a generation that quietly used the wrong material, with no error to flag it. Choosing element names that couldn't plausibly appear as ordinary words in a prompt is the cheapest insurance available here.

Chapter 5

Making a Photograph Move Like the Reference

Motion Control takes a still image and a separate reference video and produces output where the character in the photo performs the motion from the video – a mascot, an illustrated figure, or a real person's photo animated by someone else's recorded movement.

The image side has its own quiet requirements: the character's proportions should roughly match what's in the reference video, avoiding a half-body photo driven by full-body motion, and extreme orientations – lying flat, upside down – tend to produce worse results even though nothing stops the request from being submitted. The video side asks for a single continuous take with one visible person; if more than one appears, whichever person occupies the largest part of the frame is the one whose motion gets used.

There's a `character_orientation` setting that decides which side's framing wins, and it changes the video length ceiling: set to follow the image, the reference video is capped at 10 seconds; set to follow the video itself, that ceiling rises to 30 seconds. Fast or complex motion in the source video can also mean the generated output comes out shorter than what was uploaded, because only the continuous stretch of usable motion the model can extract gets used – and that's billed on the output length either way, not the length of what was submitted.

Chapter 6

Giving the Video a Voice

Kling 2.6 and the Omni models can generate native audio matched to the visuals, or attach a specific voice to speak specific lines – a considerable step past simply generating a silent clip and dropping music over it afterward.

Two constraints shape how this actually gets used. First, native audio and a lower resolution don't coexist: turning audio on forces 1080p output, so a 720p request with sound isn't a combination the API will produce. Second, a task can reference at most two voices, specified in the prompt using the same @-symbol syntax as elements – `<<<voice_1>>>` – with the voice list's order matching the order they're referenced.

Custom voices are created from an uploaded audio or video clip between 5 and 30 seconds long, containing one clean, noise-free voice. What isn't obvious from the feature name alone is that a custom voice doesn't require a fresh recording at all – it can be built directly from a video Kling itself already generated, as long as that earlier video was made with sound turned on, or through the Avatar or Lip-Sync APIs. A voice a user liked in one output becomes reusable material for the next one, without anyone needing to go back and record it separately.

Chapter 7

Waiting for an Answer Without Waiting

Video and image generation are asynchronous – a task is submitted, a task ID comes back, and the actual result arrives later, either by polling the tasks endpoint or by registering a `callback_url` that gets notified automatically when the task's status changes to succeeded or failed.

The callback payload carries the task's status, timestamps, and – once succeeded – a set of `outputs`, each one typed by content: video, image, audio, voice or element, with its own download URL. As of 7 August, Kling also added webhook signature verification, letting an integration confirm a callback genuinely came from Kling rather than from somewhere spoofing the request – opt-in, and existing integrations that never enable it keep working exactly as before.

The detail worth building a habit around sits in a code comment rather than in the running prose of the documentation: every generated result – video, image or audio – is cleared from Kling's servers 30 days after creation, for information-security reasons the docs state but don't dwell on. There's no extension, no warning email mentioned anywhere in the captured pages, and no way described to recover a result once that window closes. A callback firing on success is not the same as the file being safe; it's the signal to go get it.

Chapter 8

Three Hundred Effects Nobody Links To

Past the six generation models sits a single endpoint – `POST /v1/videos/effects` – that on its own exposes 307 named video effects, most of them single-image transformations: a photo goes in, a themed short animation comes out, no prompt writing required at all.

The effect names read like a changelog because that's largely what they are – new ones added in small batches roughly every week or two, tracked in the API's own updates page rather than promoted anywhere on the marketing site. On 10 August alone, one new effect shipped; on 24 July, nine arrived in a single release. A team that only reads Kling's feature pages would have no way of knowing this endpoint exists, let alone that it grows continuously.

Selecting one is a matter of setting `effect_scene` to the effect's name and supplying whatever `input` structure that particular scene expects – single-image effects, of which there are 292, use one shape; the remainder use another. For a product that wants stylised, shareable output without building its own prompt-engineering layer, this endpoint does in one call what several paragraphs of prompt-writing might attempt to approximate elsewhere in the API and not quite reach.

Chapter 9

What Every Generation Actually Costs

Kling bills in units deducted per second of generated output, not per request and not by a flat per-video price, and the rate is set by which model, resolution and settings were chosen rather than by any single number that applies everywhere.

The clearest documented example: Kling 3.0 Turbo deducts 0.8 units per second at 720p and 1.0 unit per second at 1080p. Kling 3.0 Omni, generating with a reference video as a feature source, deducts 3 units per second – a considerably steeper rate tied specifically to that combination of model and input type, not to Omni generation in general. A task billed 'with specified voice' is charged differently again, tied to whether the prompt actually referenced a voice ID from the voice list.

This is also the reason a solid grasp of Chapter 1's model choice matters financially as much as technically: choosing Kling O1 with a reference video for a job that Kling 3.0 Turbo could have handled without one isn't just more complex to integrate, it's billed at a different rate entirely. The API also now supports exporting detailed deduction records – filterable by time, API key or resource package – which is the tool to reach for once a monthly bill needs explaining rather than guessing at from the model list alone.

Chapter 10

Before This Goes Into Production

If the goal is the fastest reliable clip from a single photo or short prompt, Kling 3.0 Turbo is built for exactly that, and its narrower feature set is what keeps its request shape simple and its billing predictable.

If the goal is a longer piece with a consistent character across several shots, the model choice moves to 3.0 or 3.0 Omni, and the planning moves with it – deciding the storyboard's shot count and durations before writing the prompt, not after a rejected request forces a rewrite.

If the goal is giving a character a voice, 2.6 is where that lives, and the 1080p-with-audio pairing needs to be designed in from the start rather than discovered when a 720p request with sound gets bounced back unresolved.

If the goal is animating an existing photo with someone else's recorded motion, Motion Control is the tool, and the character-orientation setting decides both how long the reference video can be and how the final generation is framed.

Whichever door is used, one habit carries across every one of them: the moment a callback reports success, the download should happen immediately, because thirty days after that moment, the result stops existing anywhere Kling controls.

Questions readers actually ask

Contact / More useful information from RamthaMedia

Official source links:
Kling