Kling AI Known Pitfalls
Overview
Documented mistakes, gotchas, and anti-patterns from real Kling AI integrations. Each pitfall includes the symptom, root cause, and tested fix.
Pitfall 1: Duration as Integer
Symptom: 400 Bad Request on valid-looking requests.
{"duration": 5}
{"duration": "5"}
The API requires duration as a string "5" or "10", not an integer.
Pitfall 2: JWT Without Explicit Headers
Symptom: 401 Unauthorized even with correct AK/SK.
token = jwt.encode(payload, sk, algorithm="HS256")
token = jwt.encode(payload, sk, algorithm="HS256",
headers={"alg": "HS256", "typ": "JWT"})
Some JWT libraries don't include typ: "JWT" by default. Kling requires it.
Pitfall 3: Token Generated Once at Import Time
Symptom: Works for 30 minutes, then all requests fail with 401.
TOKEN = generate_token()
headers = {"Authorization": f"Bearer {TOKEN}"}
def get_headers():
return {"Authorization": f"Bearer {generate_token()}"}
JWT tokens expire after 30 minutes. Always implement auto-refresh.
Pitfall 4: Polling Without Timeout
Symptom: Script hangs forever on a failed task.
while True:
result = check_status(task_id)
if result["status"] == "succeed":
break
time.sleep(10)
start = time.monotonic()
while time.monotonic() - start < 600:
result = check_status(task_id)
if result["status"] == "succeed":
break
elif result["status"] == "failed":
raise RuntimeError(result["error"])
time.sleep(10)
else:
raise TimeoutError("Generation timed out")
Pitfall 5: Not Downloading Videos Promptly
Symptom: Video URLs return 404 or 403 after a day.
Kling CDN URLs are temporary (24-72 hours). Always download and store on your own infrastructure immediately after generation completes.
db.save(video_url=kling_cdn_url)
local_path = download_video(kling_cdn_url)
permanent_url = upload_to_s3(local_path, bucket)
db.save(video_url=permanent_url)
Pitfall 6: Mixing Mutually Exclusive Features (I2V)
Symptom: 400 Bad Request on image-to-video with multiple features.
These are mutually exclusive for image-to-video:
camera_controldynamic_masks / static_maskimage_tail
You can only use ONE group per request.
Pitfall 7: Wrong Model for Text-to-Video
Symptom: 400 or unexpected behavior.
{"model_name": "kling-v2-1", "prompt": "A sunset..."}
{"model_name": "kling-v2-master", "prompt": "A sunset..."}
{"model_name": "kling-v2-5-turbo", "prompt": "A sunset..."}
Check the model catalog: kling-v1-5 and kling-v2-1 support image-to-video only.
Pitfall 8: No Error Handling on Task Status
Symptom: Silent failures, missing videos.
if result["task_status"] == "succeed":
process(result)
if result["task_status"] == "succeed":
process(result)
elif result["task_status"] == "failed":
log_failure(result["task_status_msg"])
retry_or_alert(task_id)
Pitfall 9: Ignoring Credit Costs with Audio
Symptom: Credits depleted 5x faster than expected.
Native audio (v2.6, motion_has_audio: true) multiplies credit cost by 5x:
- 5s standard without audio: 10 credits
- 5s standard WITH audio: 50 credits
Always check motion_has_audio in cost estimates.
Pitfall 10: Vague Prompts
Symptom: Low-quality, incoherent video output.
"A nice video of nature"
"Close-up of a monarch butterfly landing on a lavender flower, "
"soft bokeh background, golden hour lighting, macro lens, 4K"
Good prompts: specific subject, clear action, lighting, camera angle, style.
Quick Reference
| Pitfall | Fix |
|---|
| Duration as int | Use string: "5" |
| JWT headers missing | Add headers={"alg":"HS256","typ":"JWT"} |
| Token not refreshed | Auto-refresh with 5-min buffer |
| No poll timeout | Max 600s with failure check |
| Kling URLs as permanent | Download and rehost immediately |
| Mixed I2V features | One feature group per request |
| Wrong model for T2V | Check model supports text-to-video |
| No failure handling | Check for "failed" status |
| Audio cost surprise | 5x multiplier with motion_has_audio |
| Vague prompts | Specific subject, action, style, lighting |
Resources
