Manage avoid common mistakes when using Kling AI. Use when troubleshooting issues or learning best practices to prevent problems. Trigger with phrases like 'klingai pitfalls', 'kling ai mistakes', 'klingai gotchas', 'klingai best practices'.
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill klingai-known-pitfallsLoading…
Documented mistakes, gotchas, and anti-patterns from real Kling AI integrations. Each pitfall includes the symptom, root cause, and tested fix.
Symptom: 400 Bad Request on valid-looking requests.
# WRONG -- duration as integer
{"duration": 5}
# CORRECT -- duration as string
{"duration": "5"}
The API requires duration as a string "5" or "10", not an integer.
Symptom: 401 Unauthorized even with correct AK/SK.
# WRONG -- missing headers parameter
token = jwt.encode(payload, sk, algorithm="HS256")
# CORRECT -- explicit JWT headers
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.
Symptom: Works for 30 minutes, then all requests fail with 401.
# WRONG -- token generated once
TOKEN = generate_token() # at module import
headers = {"Authorization": f"Bearer {TOKEN}"}
# CORRECT -- generate fresh token per request (or auto-refresh)
def get_headers():
return {"Authorization": f"Bearer {generate_token()}"}
JWT tokens expire after 30 minutes. Always implement auto-refresh.
Symptom: Script hangs forever on a failed task.
# WRONG -- infinite loop
while True:
result = check_status(task_id)
if result["status"] == "succeed":
break
time.sleep(10)
# CORRECT -- with timeout and failure check
start = time.monotonic()
while time.monotonic() - start < 600: # 10 min max
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")
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.
# WRONG -- storing only the Kling URL
db.save(video_url=kling_cdn_url) # will expire
# CORRECT -- download and rehost
local_path = download_video(kling_cdn_url)
permanent_url = upload_to_s3(local_path, bucket)
db.save(video_url=permanent_url)
Symptom: 400 Bad Request on image-to-video with multiple features.
These are mutually exclusive for image-to-video:
camera_controldynamic_masks / static_maskimage_tailYou can only use ONE group per request.
Symptom: 400 or unexpected behavior.
# WRONG -- kling-v2-1 is I2V-only
{"model_name": "kling-v2-1", "prompt": "A sunset..."} # fails
# CORRECT -- use models that support T2V
{"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.
Symptom: Silent failures, missing videos.
# WRONG -- only check for success
if result["task_status"] == "succeed":
process(result)
# silently ignores failures
# CORRECT -- handle all terminal states
if result["task_status"] == "succeed":
process(result)
elif result["task_status"] == "failed":
log_failure(result["task_status_msg"])
retry_or_alert(task_id)
Symptom: Credits depleted 5x faster than expected.
Native audio (v2.6, motion_has_audio: true) multiplies credit cost by 5x:
Always check motion_has_audio in cost estimates.
Symptom: Low-quality, incoherent video output.
# WEAK -- too vague
"A nice video of nature"
# STRONG -- specific and descriptive
"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.
| 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 |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).