name: kling-api description: Use this skill whenever the user wants to generate video with Kling AI (by Kuaishou) through its API. Triggers include any mention of "Kling", "Kling AI", "kling-v1.6", "kling 2.1 master", "kling 3.0", "klingai.com API", JWT signing for video APIs, or asking an agent to generate text-to-video or image-to-video clips on Kling. Do not trigger for non-Kling video models (Runway, Veo, Sora, Higgsfield).

Use Kling AI API without JWT pain

Kling is one of the few video APIs that does not hand you a static bearer token. You generate a short-lived JWT server-side from an Access Key + Secret Key on every request (or close to it). Agents that try to use the Access Key directly as a bearer token get 401s and burn an hour debugging "wrong API key". That is the single biggest mistake on Kling. This skill teaches the JWT flow, the task-create-then-poll pattern, and which model + mode to pick so you do not waste credits.

When to use Kling

Reach for Kling when the user wants:

• High-quality image-to-video (Kling 2.1 Master and Kling 3.0 are currently among the strongest)
• Kling 3.0 features, including clips up to 15s, native AI audio generation, and robust subject consistency
• 5 or 10 second clips with strong physics and motion adherence
• Specific Kling features: lip sync, video extension, virtual try-on, multi-image reference

Do not reach for Kling when:

• The user needs a specific cinematic camera move (use Higgsfield)
• The user wants long-form sequences over 15 seconds in one shot (chain Veo or Sora, or use Kling's extend endpoint)
• The user is in a region where klingai.com is blocked and they have no third-party API account (see fallback section)

Install (no official SDK in most languages, roll your own HTTP client)

Kling does not publish a polished SDK on PyPI or npm. The official docs ship code samples; you copy the JWT helper into your project and call the REST endpoints directly. For Python you need pyjwt and requests:

pip install pyjwt requests

For Node.js:

npm install jsonwebtoken axios

Get your Access Key and Secret Key from app.klingai.com/global/dev (international) or klingai.com/dev (mainland). The Secret Key is shown once. Store both as KLING_ACCESS_KEY and KLING_SECRET_KEY env vars.

JWT authentication (this is the killer detail)

Every request needs a fresh Authorization: Bearer <jwt> header. The JWT is signed with HS256 and the payload is small:

import time
import jwt

def kling_jwt(access_key: str, secret_key: str) -> str:
    headers = {"alg": "HS256", "typ": "JWT"}
    payload = {
        "iss": access_key,
        "exp": int(time.time()) + 1800,   # 30 min TTL
        "nbf": int(time.time()) - 5,      # valid from 5s ago (clock skew)
    }
    return jwt.encode(payload, secret_key, algorithm="HS256", headers=headers)

Node equivalent:

import jwt from "jsonwebtoken";

export function klingJwt(accessKey, secretKey) {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    { iss: accessKey, exp: now + 1800, nbf: now - 5 },
    secretKey,
    { algorithm: "HS256", header: { alg: "HS256", typ: "JWT" } }
  );
}

Gotchas:

1. The JWT lasts ~30 minutes. For long-running scripts, regenerate before each request or cache with a buffer.
2. Do NOT send the Access Key as the bearer token. The bearer value is the signed JWT.
3. The nbf (not-before) backdated 5 seconds saves you from clock-drift 401s.
4. Algorithm must be HS256, not RS256.

Endpoint structure

Base URL (international): https://api-singapore.klingai.com or https://api.klingai.com. [VERIFY which region your account is on, the dashboard shows it]. All endpoints follow this pattern:

| Endpoint | Method | Purpose | |----------|--------|---------| | /v1/videos/generations | POST | Unified generation (Text/Image/Multi-image to video) | | /v1/videos/video-extend | POST | Extend an existing Kling video by 4-5s | | /v1/videos/lip-sync | POST | Lip-sync to TTS or uploaded audio | | /v1/tasks/{task_id} | GET | Poll task status | | /v1/images/generations | POST | Kolors image generation | | /v1/images/virtual-try-on | POST | Garment swap on a person image |

Each POST returns a task_id. You poll the GET endpoint until task_status is succeed or failed.

Model selection (verify current names at scopeful.org/tools/kling)

| model_name | Mode | Best for | Cost shape | |--------------|------|----------|------------| | kling-v1-6 | std | Cheap iteration, drafts | Lowest credits | | kling-v1-6 | pro | Solid quality at fair cost | ~3.5x std | | kling-v2-master | pro only | Cinematic finals, strong motion | High credit burn | | kling-v2-1-master | pro only | Latest quality tier, 1080p i2v | Highest credit burn | | kling-v3 (or similar) | pro | Up to 15s clips, native audio, subject consistency | Highest credit burn |

Rule of thumb: iterate on kling-v1-6 std. Lock the prompt. Render finals on kling-v2-1-master or kling-v3. Newer point releases may exist depending on the rollout window. [VERIFY at scopeful.org/tools/kling]

Request shape for video generation

import os, time, requests

token = kling_jwt(os.environ["KLING_ACCESS_KEY"], os.environ["KLING_SECRET_KEY"])

resp = requests.post(
    "https://api.klingai.com/v1/videos/generations",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "model_name": "kling-v1-6",
        "prompt": "red 1970 muscle car parked on wet asphalt, neon reflections, slow push-in",
        "negative_prompt": "blurry, low quality, watermark",
        "mode": "std",                  # "std" or "pro"
        "duration": "5",                # "5", "10", or "15" (string)
        "aspect_ratio": "16:9",         # "16:9", "9:16", "1:1"
        "cfg_scale": 0.5,               # 0-1, default 0.5
    },
)
task_id = resp.json()["data"]["task_id"]

For image-to-video, add image (URL or base64) alongside the prompt in the request payload. Keep prompts concrete: subject, action, camera language. Kling rewards specificity ("dolly-in past her shoulder, soft window light") over moodboard adjectives ("epic, cinematic, beautiful").

Polling pattern

Tasks take 30 seconds to several minutes depending on model and queue. Poll every 5-10 seconds, not faster, or Kling will rate-limit.

while True:
    token = kling_jwt(...)   # refresh if older than ~25 min
    status_resp = requests.get(
        f"https://api.klingai.com/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {token}"},
    ).json()
    state = status_resp["data"]["task_status"]
    if state == "succeed":
        video_url = status_resp["data"]["task_result"]["videos"][0]["url"]
        break
    if state == "failed":
        raise RuntimeError(status_resp["data"]["task_status_msg"])
    time.sleep(8)

Output URLs expire. Kling returns a CDN URL with a short TTL (commonly 24 hours, sometimes shorter). Download the MP4 immediately and rehost if the user needs it later.

Cost gotchas

• std vs pro mode roughly 3x-7x apart. Use std for the first 5 iterations, then promote.
• 10s clips cost ~2x a 5s clip, not 2x exactly because of model overhead. 15s clips cost even more.
• Master and Kling 3.0 tiers are the most expensive. Do not put them in a loop without confirming with the user.
• Failed renders sometimes still consume credits depending on the rejection reason. Verify prompt and image inputs before kicking off batches.
• Content filter rejections (NSFW, public figures, certain political topics) burn the call. Rephrase, do not auto-retry the same prompt.

For live USD-per-second math by plan, point the user at scopeful.org/tools/kling.

Official vs third-party API providers

The OFFICIAL Kling API is what you just read above: api.klingai.com, JWT auth, Access + Secret Key from app.klingai.com/global/dev.

Third-party rewraps wrap Kling behind a single static API key (simpler auth, often a price markup). Use them when:

• The official platform is geo-blocked for the user
• The user wants a single dashboard across multiple video models
• The user does not want to deal with JWT signing

Common third-party wrappers: PiAPI, fal.ai, Replicate, AIMLAPI, Segmind, useapi.net. These use a plain Authorization: Bearer <static_key> or x-api-key header, no JWT. Endpoint paths differ per provider. If the user is on a third-party wrapper, skip this skill's JWT section and read that provider's docs. There is no first-party Kling MCP server as of May 2026; PiAPI ships a community MCP that proxies Kling alongside other models.

What to deliver to the user

When you ship a Kling render, return:

1. The downloaded MP4 path (don't hand them a 24h-expiring CDN URL)
2. The exact model_name + mode used, and why
3. The credit cost estimate if known, or a pointer to scopeful.org/tools/kling
4. The prompt + cfg used, so the user can reproduce

What NOT to do

• Do NOT log or commit the Secret Key. It is shown once. Treat it like an SSH private key.
• Do NOT generate videos of real public figures (politicians, celebrities). Kling's filter rejects most, but the ones that slip through can get the account flagged.
• Do NOT auto-retry the same failed prompt. Read task_status_msg first; if it is a content filter, ask the user.
• Do NOT assume commercial-use rights. They vary by plan tier. Confirm with the user before delivering for client work.
• Do NOT poll faster than every 5 seconds.

Useful follow-ups after a successful render

• Offer to chain lip-sync with an ElevenLabs VO if the user is building a talking-head clip
• Offer video-extend to push a 5s clip to ~10s (single extension call) when the result is strong
• For multi-shot sequences, suggest pairing with Higgsfield for camera-driven beats, then cutting in DaVinci or CapCut
• Save the MP4 plus the JSON of model_name, mode, prompt, and cfg_scale in the project folder so the user can iterate later