Skip to contentOceanToken

7 min read

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

Kling API Tutorial: Async Tasks, Callbacks and Parameters

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:

  1. Create. POST /text-to-video/kling-3.0. The response data carries id, status, create_time, update_time and your external_id if you sent one.
  2. Wait. Either poll GET /tasks with task_ids (or external_task_ids, never both in one call), or let Kling call your callback_url.
  3. Download. When the status is succeeded, read the video url from outputs. 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

  1. Create one 5-second task with external_task_id set, and log the response id.
  2. Point callback_url at a request bin and record which payload format arrives for your model.
  3. Run the same task again with your bin returning 500, and see whether a second delivery ever comes.
  4. Submit more tasks than your package allows and confirm your client backs off on 1303.
  5. Check that a request without settings.resolution really 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

  1. Kling API docs: Kling 3.0 text to video  (checked 2026-11-06)
  2. Kling API docs: callback protocol  (checked 2026-11-06)
  3. Kling API docs: concurrency rules  (checked 2026-11-06)
  4. Kling API docs: quick start  (checked 2026-11-06)
  5. OceanToken Kling API page (checked 2026-11-02)
  6. OceanToken docs: video guide  (checked 2026-11-02)
  7. OceanToken docs: API reference  (checked 2026-11-02)

Get your OceanToken API key

  1. Create an OceanToken account and an API key.
  2. Copy the snippet below, paste your key, and run it.
  3. 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}'

Get API Key 

  • Kling
  • AI video
  • Tutorial
  1. 7 min read

    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.

    • AI video
    • LLM API
    • Tutorial
  2. 7 min read

    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.

    • Kimi
    • LLM API
    • Tutorial
  3. 6 min read

    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.

    • Hunyuan
    • LLM API
    • Tutorial