klingai-known-pitfalls

name	klingai-known-pitfalls
description	Avoid common mistakes when using Kling AI API. Use when troubleshooting or learning best practices. Trigger with phrases like 'klingai pitfalls', 'kling ai mistakes', 'klingai gotchas', 'klingai best practices'.
allowed-tools	Read, Write, Edit, Bash(npm:*), Grep
version	1.18.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","kling-ai","troubleshooting","best-practices"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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.