kling-video

Kling AI Video Generation API

Generate videos via the Kling AI API: text-to-video, image-to-video, AI avatars, motion control, multi-shot narrative.

Installation

npm install @runapi.ai/kling

Requires Node 18+, environment variable RUNAPI_API_KEY。

Initialization

import { KlingClient } from "@runapi.ai/kling";
const client = new KlingClient({ apiKey: process.env.RUNAPI_API_KEY });

Text-to-Video

const result = await client.textToVideo.run({
  model: "kling-3.0",
  prompt: "一只白猫在雪地里奔跑，阳光透过树枝洒落",
  duration: "5"
});
// auto-polling: 每 2s 轮询，最长 15min

For production environments, separate calls are recommended:

const task = await client.textToVideo.create({ model: "kling-3.0", prompt: "..." });
const result = await client.textToVideo.get(task.id);

Image-to-Video

const result = await client.imageToVideo.create({
  model: "kling-3.0",
  image_urls: ["https://example.com/image.jpg"],
  prompt: "让画面中的人物自然微笑并挥手"
});

Multi-Shot

Kling 3.0 supports generating up to 6 consecutive shots at once:

const result = await client.textToVideo.create({
  model: "kling-3.0",
  prompt: "[Character A: 白猫] 走过雪地...",
  multi_shots: true,
  multi_prompt: [
    "镜头1: 白猫从远处走来，广角",
    "镜头2: 白猫跳跃，特写慢动作",
    "镜头3: 白猫消失在雪景中，拉远"
  ]
});
// 多镜头自动启用配音和唇形同步

AI Avatar

const result = await client.aiAvatar.run({
  model: "ai-avatar-pro",
  image: "https://example.com/portrait.jpg",
  audio_url: "https://example.com/speech.mp3",
  prompt: "自然微笑，眼神交流"
});

Motion Control

Use a reference video to drive the motion of a static image:

const result = await client.motionControl.run({
  input_urls: ["https://example.com/static.jpg"],
  video_urls: ["https://example.com/motion_ref.mp4"],
  character_orientation: "front",
  background_source: "original"
});

Model Selection

Model	Model ID	Features
Kling 3.0	`kling-3.0`	Multi-shot, native dubbing, lip sync, voice control
Kling 2.6 Pro	`kling-2.6-pro`	Element Binding, Motion Brush, character consistency
V2.5 Turbo T2V	`kling-v2.5-turbo-text-to-video-pro`	Fast text-to-video
V2.5 Turbo I2V	`kling-v2.5-turbo-image-to-video-pro`	Fast image-to-video
AI Avatar Pro	`ai-avatar-pro`	High-quality AI avatar
AI Avatar Standard	`ai-avatar-standard`	Standard AI avatar

Using Motion Brush in Kling 2.6 Pro

const result = await client.textToVideo.create({
  model: "kling-2.6-pro",
  prompt: "...",
  motion_brush: [
    { element: "白猫", motion: "前进移动" },
    { element: "背景树", motion: "轻微摇摆" }
  ]
});

Webhooks

HMAC-SHA256 signature verification, must return 2xx within 10s:

const crypto = require("crypto");
function verifySignature(payload, signature, secret) {
  const expected = crypto.createHmac("sha256", Buffer.from(secret, "base64"))
    .update(payload).digest("base64");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Error Handling

Type	HTTP	Handling
`AuthenticationError`	401	Check API Key
`InsufficientCreditsError`	402	Top up
`ValidationError`	422	Check request parameters
`RateLimitError`	429	Wait and retry
`ServiceUnavailableError`	503	Retry later
`TaskFailedError`	-	Check input/retry
`TaskTimeoutError`	-	Increase timeout

Notes

model parameter is always required
Multi-shot requires enabling multi_shots: true
In multi-shot, image_urls at most 1
The motion control array has length and format requirements
duration is in string format (e.g., "5"）
The callback URL must be a publicly accessible address

About this skill