Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/klingai-known-pitfalls/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill klingai-known-pitfalls. Copyright stays with the author (MIT).

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.

# 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.

Pitfall 2: JWT Without Explicit Headers

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.

Pitfall 3: Token Generated Once at Import Time

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.

Pitfall 4: Polling Without Timeout

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")

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.

# 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)

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_control
• dynamic_masks / static_mask
• image_tail

You can only use ONE group per request.

Pitfall 7: Wrong Model for Text-to-Video

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.

Pitfall 8: No Error Handling on Task Status

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)

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.

# 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.

Quick Reference

Prerequisites

• An approved sandbox brief, rights-cleared or synthetic inputs, secret references, content-policy review, credit cap, draft-only destination, and a removal owner.

Instructions

1. Reproduce pitfalls with a single watermarked sandbox draft; do not use private, unlicensed, or policy-restricted materials.
2. Check authentication, model/mode, duration, policy/rights status, credit use, destination, and retention before applying a workaround.
3. Stop and remove the draft if a workaround introduces policy, attribution, quality, budget, or retention drift.
4. Record the remediation as a redacted receipt and restore the known-good configuration before further testing.

Output

Produce a pitfall receipt with environment, failure category, synthetic/rights-cleared classification, remedial setting, aggregate task result, policy/rights/budget checks, draft-only status, cleanup proof, and rollback reference. Exclude prompts, assets, identities, and credentials.

Error Handling

Examples

env=sandbox; pitfall=timeout; fixture=synthetic; remedy=bounded-polling; policy=pass; destination=draft-only; cleanup=verified is valid evidence.

Resources

• API Reference
• Developer Portal