Kling API Tutorial: Async Tasks, Callbacks and Parameters
Kling API tutorial from Kuaishou's docs: create a Kling 3.0 task, poll or use callback_url, every setting, error 1303, and how the flow maps to OceanToken.
By OceanToken Team

Editor's note: The hard part of a Kling integration is the plumbing, not the prompt: a callback that never arrives, a status string compared with the wrong spelling, or a result link nobody saved. Kuaishou's own docs answer most of this, but the answers are spread over several pages. This guide puts them in the order you will hit them, and treats callbacks as a bonus rather than the thing your app depends on.
Short answer: This Kling API tutorial follows Kuaishou's docs. Send POST /text-to-video/kling-3.0 with a Bearer key, store the returned task id, then poll GET /tasks or set options.callback_url. Wait for succeeded, download within 30 days, and back off on error 1303. Audio is off unless you set settings.audio to native.
How a Kling API job runs
Kling video generation is asynchronous. You never get a video back from the create call. You get a task, and the task moves through four statuses on the current API: submitted, processing, succeeded and failed, per the Kling 3.0 text-to-video reference .
The quick start covers the key. You create an API key in the Kling Developer Console, and it is shown only once, so put it in your secret store before you close the dialog. Each request sends it as Authorization: Bearer <key>. The example host in the docs is https://api-singapore.klingai.com.
The loop has three steps:
- Create.
POST /text-to-video/kling-3.0. The responsedatacarriesid,status,create_time,update_timeand yourexternal_idif you sent one. - Wait. Either poll
GET /taskswithtask_ids(orexternal_task_ids, never both in one call), or let Kling call yourcallback_url. - Download. When the status is
succeeded, read the videourlfromoutputs. Kling keeps generated results for 30 days, so copy the file to your own storage.
Setting options.external_task_id is worth the extra line. It must be unique within your account and does not replace Kling's task id, but it lets you look the task up by your own job key if your process dies between the create call and saving the response.
Create a Kling 3.0 task
Here is a create request built only from fields in the Kling 3.0 reference :
curl https://api-singapore.klingai.com/text-to-video/kling-3.0 \
-H "Authorization: Bearer $KLING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A cat walks past a bakery sign at dawn",
"settings": {"duration": 5, "aspect_ratio": "16:9", "resolution": "1080p", "audio": "off"},
"options": {"callback_url": "https://example.com/hooks/kling", "external_task_id": "job-1042"}
}'
Save the returned id against your own job record before you do anything else. If the request times out on your side, query by external_task_ids=job-1042 before you create the task again, so you do not pay for the same clip twice.
Kling 3.0 API parameters
These are the create-task fields on Kuaishou's Kling 3.0 text-to-video page, checked 2026-11-06:
| Field | Default | Allowed values and notes |
|---|---|---|
prompt |
required | Up to 3,072 characters, 2,500 or fewer recommended. Positive and negative wording both go here |
settings.duration |
5 |
Whole seconds from 3 to 15, sent as an integer |
settings.resolution |
720p |
720p, 1080p, 4k |
settings.aspect_ratio |
16:9 |
16:9, 9:16, 1:1 |
settings.audio |
off |
native adds audio generated to match the picture; off gives a silent clip |
settings.multi_shot |
true |
Shots are written inside prompt; false turns multi-shot output off |
options.callback_url |
none | Receives status-change notifications |
options.external_task_id |
none | Your own id, unique per account |
options.watermark_info.enabled |
false |
true also returns a watermarked file; custom watermarks are not supported |
Two defaults catch people. Resolution starts at 720p, so a request without settings.resolution will not give you 1080p. And audio starts off, so a dialogue scene comes back silent unless you ask for native. Multi-shot syntax has its own rules, covered in our Kling multi-shot guide.
Kling API callback: format and gaps
When you set callback_url, "the server will actively notify you when the task status changes," per the callback protocol . There are two payload formats, and which one you get depends on the model:
| New format (newer models) | Legacy format (3.0 Omni and earlier) | |
|---|---|---|
| Task id | id |
task_id |
| Status field | status |
task_status |
| Success value | succeeded |
succeed |
| Failure reason | message |
task_status_msg |
| Result | outputs |
task_result |
| Billing | billing |
final_unit_deduction, final_balance_deduction |
The success value is the trap. A handler that checks status == "succeeded" will never fire on a legacy payload, which says succeed. Normalize both into one internal status in a single function, and do it before any other logic.
The same page says webhook signatures need options.callback_url set at creation time. What it does not describe is retry behaviour for failed deliveries. So assume a missed callback is gone for good. Keep a worker that polls GET /tasks for any task still open after a few minutes, and make the handler safe to run twice for the same id.
Concurrency and error 1303
Kling limits how many tasks run at once, and the concurrency rules explain the counting. The quota is per account, per model version and per package type (video or image), and all your API keys share it. A task holds a slot from submitted until it ends, failures included. Query calls do not count, and the docs state there is no QPS limit.
Over the limit, task creation returns code 1303, "parallel task over resource pack limit." Kuaishou's advice is exponential backoff starting at one second or more, plus a task queue that only submits when a slot is free. For batch jobs this matters more than prompt tuning, because a loop that submits a whole batch at once starts getting 1303 the moment it passes your quota.
How to test this on your workload
- Create one 5-second task with
external_task_idset, and log the responseid. - Point
callback_urlat a request bin and record which payload format arrives for your model. - Run the same task again with your bin returning
500, and see whether a second delivery ever comes. - Submit more tasks than your package allows and confirm your client backs off on
1303. - Check that a request without
settings.resolutionreally returns 720p.
Our take: Build the poller first and add the callback second. The callback cuts latency, but the docs give no retry promise, two status spellings exist, and results expire after 30 days. A design where polling is the source of truth, callbacks only wake the worker early, and every finished file is copied to your own bucket survives all three.
Running it on OceanToken with one key
OceanToken serves Kling through an OpenAI-compatible base URL, https://api.oceantoken.ai/v1. The ids on /kling-api are kwaivgi/kling-v3.0-pro, kwaivgi/kling-v3.0-std, kwaivgi/kling-video-o1 and kwaivgi/kling-v3.0-omni. If you already use the OpenAI SDK, you change the base URL and key, and switching to another video or text model is a change of model id. See the current rate on /kling-api.
from openai import OpenAI
client = OpenAI(base_url="https://api.oceantoken.ai/v1", api_key="YOUR_API_KEY")
video = client.videos.create_and_poll(
model="kwaivgi/kling-v3.0-pro",
prompt="A cat walks past a bakery sign at dawn")
client.videos.download_content(video.id).write_to_file("video.mp4")
The same job on both routes, per Kuaishou's docs and OceanToken's video guide and API reference :
| Kuaishou Kling API | OceanToken | |
|---|---|---|
| Model choice | Endpoint path, e.g. /text-to-video/kling-3.0 |
model: "kwaivgi/kling-v3.0-pro" |
| Completion | Poll GET /tasks or callback_url |
Poll GET /v1/videos/{id}; no webhook documented |
| Status values | submitted, processing, succeeded, failed |
queued, in_progress, completed, failed |
| Duration | settings.duration, integer 3 to 15 |
seconds, number or string |
| Resolution | settings.resolution, default 720p |
v3.0 Pro is 1080p only; v3.0 Std is 720p only |
| Audio | settings.audio: native or off |
generate_audio true or false |
| Result link | Kept 30 days | content_url valid 24 hours |
On OceanToken a failed video job is not charged and its hold is released, per the video guide. Send an Idempotency-Key header so a retried create cannot start a second job. The 24-hour link is the one to plan around: download as soon as the status reads completed.
FAQ
Is the Kling API synchronous? No. The create call returns a task id, and you poll or wait for a callback until the status is succeeded or failed.
Why does my callback handler never see success? The callback docs say Kling 3.0 Omni and earlier use the legacy format, where success is succeed in task_status. Newer models send succeeded in status.
Does Kling retry a failed callback? The callback docs do not describe retries. Keep a polling fallback for any task that stays open.
What does error 1303 mean? You hit your concurrency limit for that model version and package type. Wait and retry with exponential backoff from at least one second.
How long can I download a Kling result? Kuaishou keeps results for 30 days. On OceanToken, content_url is valid for 24 hours.
Sources
- Kling API docs: Kling 3.0 text to video (checked 2026-11-06)
- Kling API docs: callback protocol (checked 2026-11-06)
- Kling API docs: concurrency rules (checked 2026-11-06)
- Kling API docs: quick start (checked 2026-11-06)
- OceanToken Kling API page (checked 2026-11-02)
- OceanToken docs: video guide (checked 2026-11-02)
- OceanToken docs: API reference (checked 2026-11-02)
Get your OceanToken API key
- Create an OceanToken account and an API key.
- Copy the snippet below, paste your key, and run it.
- Check the current rate on /kling-api.
curl https://api.oceantoken.ai/v1/videos \
-H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "kwaivgi/kling-v3.0-pro", "prompt": "A cat walks past a bakery sign at dawn", "seconds": 5}'
More from the blog
A Unified API for Chat, Image and Video
Building on a unified API for chat, image and video: sync vs async calls, billing units, retries, timeouts and storage, with three calls and a launch checklist.
Kimi K3 API International Access Guide
Use the Kimi K3 API internationally: sign up with email, pay by card, create one key and call moonshotai/kimi-k3 with an OpenAI SDK. Steps, code and checks.
Call Tencent Hy3 With the OpenAI SDK
Call Tencent Hy3 with the OpenAI SDK outside China: base URL, model id, streaming, tool calls, reasoning_effort values, Hy3 vs Hy3 preview, and token billing.