Kling AI API wrapper - Video and image generation with JWT authentication for Node.js
A TypeScript SDK and CLI tool for the Kling AI API for video generation, image generation, image expansion, and avatar/talking head creation.
This service follows the data-collection architecture pattern with JWT authentication, organized data storage, automatic polling, retry logic with exponential backoff, and parameter validation.
import { KlingAPI } from 'kling-api';
const api = new KlingAPI({
accessKey: 'your-access-key',
secretKey: 'your-secret-key'
});
// Generate a video from text
const task = await api.textToVideo({
prompt: 'A cat playing piano in a cozy room',
model_name: 'kling-v2-master',
duration: '5'
});
// Wait for result with auto-polling
const result = await api.waitForVideoResult(task.data.task_id);
console.log('Video URL:', result.data.task_result.videos[0].url);
# Install globally
npm install -g kling-api
# Generate a video from text
kling video text2video --prompt "A cat playing piano" --model kling-v2-master --wait
# Generate from image
kling video image2video --image ./photo.jpg --prompt "Make it come alive" --wait
# See all commands
kling --help
TypeScript support with exported types for all parameters and responses.
For detailed Kling AI API documentation including all endpoints, parameters, error codes, and model capabilities, see the comprehensive API reference:
The reference covers:
The Kling AI API provides access to video and image generation models. This Node.js wrapper implements:
# Install as a dependency in your project
npm install kling-api
# Or install globally for CLI usage
npm install -g kling-api
Requirements: Node.js >= 18.0.0
The kling CLI provides a command-line interface for video generation, image generation, avatar creation, and account management.
kling [options] [command]
Options:
-V, --version Output version number
--access-key <key> Kling API access key (overrides env var)
--secret-key <key> Kling API secret key (overrides env var)
--output-dir <dir> Output directory for generated files
--debug Enable debug logging
--examples Show usage examples
-h, --help Display help
kling video text2video [options]
# Alias: kling video t2v
Options:
-p, --prompt <text...> Text prompt(s) - can specify multiple
-m, --model <name> Model: kling-v1, kling-v1-6, kling-v2-master,
kling-v2-1-master, kling-v2-5-turbo, kling-v2-6
-n, --negative-prompt <text> Negative prompt
--mode <mode> Generation mode: std, pro (default: std)
-a, --aspect-ratio <ratio> Aspect ratio: 16:9, 9:16, 1:1
-d, --duration <seconds> Duration: 5, 10
--sound <on|off> Enable sound generation (v2.6 only)
--camera-type <type> Camera preset (v1.6 only)
--camera-horizontal <n> Camera horizontal movement (-10 to 10)
--camera-vertical <n> Camera vertical movement (-10 to 10)
--camera-pan <n> Camera pan (-10 to 10)
--camera-tilt <n> Camera tilt (-10 to 10)
--camera-roll <n> Camera roll (-10 to 10)
--camera-zoom <n> Camera zoom (-10 to 10)
-w, --wait Wait for generation to complete
--no-download Do not download the result
Examples:
# Basic text-to-video
kling video t2v --prompt "a cat playing piano" --wait
# With model and options
kling video t2v \
--prompt "cinematic landscape" \
--model kling-v2-master \
--aspect-ratio 16:9 \
--duration 10 \
--mode pro \
--wait
# With sound (v2.6 only)
kling video t2v \
--prompt "ocean waves crashing" \
--model kling-v2-6 \
--sound on \
--wait
# With camera control (v1.6)
kling video t2v \
--prompt "flying through clouds" \
--model kling-v1-6 \
--camera-type forward_up \
--wait
kling video image2video [options]
# Alias: kling video i2v
Options:
-i, --image <path> Input image path or URL
-p, --prompt <text...> Text prompt(s)
-m, --model <name> Model name
-n, --negative-prompt <text> Negative prompt
--mode <mode> Generation mode: std, pro
-d, --duration <seconds> Duration: 5, 10
--image-tail <path> End frame image (pro mode only)
--camera-* Camera control options (same as text2video)
-w, --wait Wait for generation to complete
Examples:
# Basic image-to-video
kling video i2v --image ./photo.jpg --prompt "make it come alive" --wait
# With end frame (pro mode)
kling video i2v \
--image ./start.jpg \
--image-tail ./end.jpg \
--mode pro \
--wait
kling video extend [options]
Options:
--video-id <id> Video ID to extend
-p, --prompt <text> Prompt for extension
-n, --negative-prompt <text> Negative prompt
--cfg-scale <number> CFG scale (0-1)
-w, --wait Wait for generation to complete
Example:
kling video extend --video-id abc123 --prompt "continue with more action" --wait
kling video multi-image [options]
# Alias: kling video mi2v
Options:
--images <paths...> Input image paths (2-4 images)
-p, --prompt <text> Text prompt
-m, --model <name> Model name (default: kling-v1-6)
--mode <mode> Generation mode: std, pro
-a, --aspect-ratio <ratio> Aspect ratio
-d, --duration <seconds> Duration: 5, 10
-w, --wait Wait for generation to complete
Example:
kling video mi2v \
--images ./img1.jpg --images ./img2.jpg \
--prompt "smooth transition between scenes" \
--wait
kling video omni [options]
Options:
-p, --prompt <text> Prompt with template syntax
(use <<<image_1>>>, <<<element_1>>> for refs)
--images <paths...> Reference images
--elements <ids...> Element IDs
-m, --model <name> Model (default: kling-video-o1)
-a, --aspect-ratio <ratio> Aspect ratio
-d, --duration <seconds> Duration: 5, 10
-w, --wait Wait for generation to complete
Example:
kling video omni \
--prompt "A video featuring <<<image_1>>>" \
--images ./reference.jpg \
--wait
Credentials can be provided in priority order:
# 1. CLI flags (highest priority)
kling video t2v --access-key YOUR_KEY --secret-key YOUR_SECRET --prompt "test"
# 2. Environment variables
export KLING_ACCESS_KEY=your_access_key
export KLING_SECRET_KEY=your_secret_key
kling video t2v --prompt "test"
# 3. Local .env file
echo "KLING_ACCESS_KEY=..." > .env
echo "KLING_SECRET_KEY=..." >> .env
# 4. Global config
mkdir -p ~/.kling
echo "KLING_ACCESS_KEY=..." > ~/.kling/.env
echo "KLING_SECRET_KEY=..." >> ~/.kling/.env
Process multiple prompts in a single command:
kling video t2v \
--prompt "a red car" \
--prompt "a blue car" \
--prompt "a green car" \
--wait
# Show all CLI examples
kling --examples
# Show video command examples
kling video examples
# Show image command examples
kling image examples
# Show avatar command examples
kling avatar examples
# Show account command examples
kling account examples
Generate images from text prompts with optional reference images.
kling image generate [options]
# Alias: kling image gen
Options:
-p, --prompt <text...> Text prompt(s) - can specify multiple
-m, --model <name> Model: kling-v1, kling-v1-5, kling-v2,
kling-v2-new, kling-v2-1 (default: kling-v1)
-n, --negative-prompt <text> Negative prompt
-i, --image <path> Reference image for style transfer
--image-reference <type> Reference type: subject, face (requires --image)
--image-fidelity <number> Image fidelity 0-1 (requires --image-reference)
--human-fidelity <number> Human face fidelity 0-1 (requires face reference)
-r, --resolution <res> Resolution: 1k, 2k (default: 1k)
-a, --aspect-ratio <ratio> Aspect ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9
-c, --count <number> Number of images to generate (1-9, default: 1)
-w, --wait Wait for generation to complete
--no-download Do not download the result
Examples:
# Basic image generation
kling image gen --prompt "a majestic lion in the savanna" --wait
# With reference image (style transfer)
kling image gen \
--prompt "portrait in the same style" \
--image ./reference.jpg \
--image-reference subject \
--image-fidelity 0.8 \
--wait
# Multiple high-res images
kling image gen \
--prompt "futuristic cityscape" \
--count 4 \
--resolution 2k \
--aspect-ratio 21:9 \
--wait
Expand image boundaries in any direction.
kling image expand [options]
Options:
-i, --image <path> Input image path or URL
--up <ratio> Upward expansion ratio (0-2)
--down <ratio> Downward expansion ratio (0-2)
--left <ratio> Left expansion ratio (0-2)
--right <ratio> Right expansion ratio (0-2)
-w, --wait Wait for generation to complete
--no-download Do not download the result
Note: Total expanded area cannot exceed 3x the original size.
Examples:
# Expand to landscape
kling image expand \
--image ./portrait.jpg \
--left 1 \
--right 1 \
--wait
# Expand upward
kling image expand \
--image ./photo.jpg \
--up 0.5 \
--wait
Generate images using the Omni model with template syntax for multi-modal inputs.
kling image omni [options]
Options:
-p, --prompt <text> Prompt with template syntax (use <<<image_1>>>)
--images <paths...> Reference images
--elements <ids...> Element IDs
-m, --model <name> Model (default: kling-image-o1)
-r, --resolution <res> Resolution: 1k, 2k
-a, --aspect-ratio <ratio> Aspect ratio (includes 'auto')
-c, --count <number> Number of images (1-9)
-w, --wait Wait for generation to complete
Examples:
kling image omni \
--prompt "A portrait in the style of <<<image_1>>>" \
--images ./art-reference.jpg \
--count 4 \
--wait
Combine multiple subject images with optional scene and style references.
kling image multi [options]
# Alias: kling image mi2i
Options:
--subject-images <paths...> Subject images (1-4 images, required)
--scene-image <path> Scene/background reference image
--style-image <path> Style reference image
-p, --prompt <text> Generation prompt
-m, --model <name> Model: kling-v2, kling-v2-1 (default: kling-v2)
-a, --aspect-ratio <ratio> Output aspect ratio
-c, --count <number> Number of images (1-9)
-w, --wait Wait for generation to complete
Examples:
kling image multi \
--subject-images ./person1.jpg ./person2.jpg \
--scene-image ./background.jpg \
--prompt "The subjects meeting in this scene" \
--count 4 \
--wait
Create talking head videos from portrait images with audio.
kling avatar create [options]
Options:
-i, --image <path> Portrait image path or URL
--audio-id <id> Pre-uploaded audio ID (mutually exclusive with --audio-file)
--audio-file <path> Audio file path or URL (mutually exclusive with --audio-id)
-p, --prompt <text> Expression/mood guidance prompt
--mode <mode> Generation mode: std, pro (default: std)
-w, --wait Wait for generation to complete
--no-download Do not download the result
Note: Provide either --audio-id OR --audio-file, not both.
Examples:
# With audio file
kling avatar create \
--image ./portrait.jpg \
--audio-file ./speech.mp3 \
--prompt "Professional, confident expression" \
--mode pro \
--wait
# With pre-uploaded audio ID
kling avatar create \
--image ./portrait.jpg \
--audio-id audio_12345 \
--wait
Display credit balance summary.
kling account credits [options]
Options:
-d, --days <number> Query period in days (default: 30)
Examples:
# Show current credit balance (last 30 days)
kling account credits
# Check usage for specific period
kling account credits --days 7
Display detailed account information including all resource packs.
kling account info [options]
Options:
-d, --days <number> Query period in days (default: 90)
Examples:
# Show all account info
kling account info
# Show info for shorter period
kling account info --days 30
You can provide credentials in multiple ways (listed in priority order):
const api = new KlingAPI({
accessKey: 'your-access-key',
secretKey: 'your-secret-key'
});
# Add to your ~/.bashrc, ~/.zshrc, or equivalent
export KLING_ACCESS_KEY=your_access_key_here
export KLING_SECRET_KEY=your_secret_key_here
# In your project directory
echo "KLING_ACCESS_KEY=your_access_key_here" > .env
echo "KLING_SECRET_KEY=your_secret_key_here" >> .env
# Create config directory
mkdir -p ~/.kling
# Add your credentials
echo "KLING_ACCESS_KEY=your_access_key_here" > ~/.kling/.env
echo "KLING_SECRET_KEY=your_secret_key_here" >> ~/.kling/.env
Security Note: Never commit .env files or expose your credentials publicly.
This package is written in TypeScript and includes type definitions.
import {
KlingAPI,
KlingAPIError,
// Parameter types
TextToVideoParams,
ImageToVideoParams,
ImageGenParams,
ImageExpandParams,
AvatarParams,
// Advanced feature parameter types
ExtendVideoParams,
MultiImageToVideoParams,
OmniVideoParams,
OmniImageParams,
MultiImageToImageParams,
// Response types
TaskResponse,
VideoTaskResult,
ImageTaskResult,
// Utility types
CameraControl,
CameraConfig,
VideoMode,
VideoDuration,
VideoAspectRatio,
ImageAspectRatio,
OmniImageAspectRatio,
} from 'kling-api';
For advanced use cases, you can import specific modules directly:
// Authentication module
import { KlingAuth, decodeToken, isTokenExpired } from 'kling-api/auth';
// Configuration and validation
import {
loadCredentials,
loadConfig,
validateTextToVideoParams,
validateImageToVideoParams,
ValidationError,
BASE_URL,
TEXT_TO_VIDEO_MODELS,
} from 'kling-api/config';
// Utility functions
import {
imageToBase64,
audioToBase64,
downloadVideo,
downloadImage,
validateUrl,
pollWithSpinner,
logger,
} from 'kling-api/utils';
// Type definitions only
import type {
TextToVideoParams,
VideoTaskResult,
CameraConfig,
} from 'kling-api/types';
// TypeScript will catch invalid parameters at compile time
const task = await api.textToVideo({
prompt: 'A beautiful landscape',
model_name: 'kling-v2-master', // Autocomplete available
mode: 'pro', // 'std' | 'pro'
duration: '5', // '5' | '10'
aspect_ratio: '16:9', // '16:9' | '9:16' | '1:1'
});
Generate videos from text prompts.
// Create a text-to-video task
const task = await api.textToVideo({
prompt: 'A serene mountain landscape at sunset',
model_name: 'kling-v2-master', // Optional, default: 'kling-v1'
negative_prompt: 'blurry, low quality',
mode: 'pro', // 'std' or 'pro'
duration: '5', // '5' or '10' seconds
aspect_ratio: '16:9', // '16:9', '9:16', '1:1'
camera_control: { // Optional camera movement
type: 'simple',
config: { zoom: 5 }
}
});
// Query task status
const status = await api.queryTextToVideoTask(task.data.task_id);
// Wait for completion with auto-polling
const result = await api.waitForVideoResult(task.data.task_id);
// Save video to disk
const paths = await api.saveVideoResult(result, './output', 'mountain sunset');
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description (max 2500 chars) |
model_name | TextToVideoModel | No | Model version (default: 'kling-v1') |
negative_prompt | string | No | What to avoid (max 2500 chars) |
sound | 'on' | 'off' | No | Generate audio (v2.6+ only) |
cfg_scale | number | No | CFG scale 0-1 (v1 models only) |
mode | 'std' | 'pro' | No | Quality mode |
camera_control | CameraControl | No | Camera movement settings |
aspect_ratio | VideoAspectRatio | No | Output aspect ratio |
duration | '5' | '10' | No | Video length in seconds |
callback_url | string | No | Webhook for status updates |
Animate still images with motion.
// Using a local file
const task = await api.imageToVideo({
image: './photo.jpg', // Local path or URL
prompt: 'The flowers gently sway in the wind',
model_name: 'kling-v1-6',
mode: 'pro',
duration: '5'
});
// Using start and end frames (pro mode)
const task = await api.imageToVideo({
image: './start.jpg',
image_tail: './end.jpg', // End frame for interpolation
prompt: 'Smooth transition',
model_name: 'kling-v2-1',
mode: 'pro'
});
// Wait for result
const result = await api.waitForVideoResult(
task.data.task_id,
api.queryImageToVideoTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
image | string | Yes | Start frame (file path or URL) |
image_tail | string | No | End frame for interpolation (pro mode) |
prompt | string | No | Motion description |
model_name | ImageToVideoModel | No | Model version |
negative_prompt | string | No | What to avoid |
voice_list | VoiceReference[] | No | Voice references (v2.6+ only) |
dynamic_masks | DynamicMask[] | No | Motion control masks |
static_mask | string | No | Static region mask |
camera_control | CameraControl | No | Camera movement |
mode | 'std' | 'pro' | No | Quality mode |
duration | '5' | '10' | No | Video length |
Generate images from text prompts.
// Basic image generation
const task = await api.generateImage({
prompt: 'A majestic lion in the savanna',
model_name: 'kling-v1-5',
n: 4, // Generate 4 images
aspect_ratio: '16:9',
resolution: '2k'
});
// With image reference
const task = await api.generateImage({
prompt: 'Portrait in the same style',
model_name: 'kling-v1-5',
image: './reference.jpg',
image_reference: 'subject', // 'subject' or 'face'
image_fidelity: 0.8 // 0-1, how closely to follow reference
});
// Wait for result
const result = await api.waitForImageResult(task.data.task_id);
// Save images to disk
const paths = await api.saveImageResult(result, './output', 'lion');
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Image description (max 2500 chars) |
model_name | ImageGenModel | No | Model version |
negative_prompt | string | No | What to avoid |
image | string | No | Reference image (required with image_reference) |
image_reference | 'subject' | 'face' | No | Reference type (v1.5+ only) |
image_fidelity | number | No | Reference strength 0-1 |
human_fidelity | number | No | Face preservation 0-1 |
n | number | No | Number of images 1-9 |
aspect_ratio | ImageAspectRatio | No | Output aspect ratio |
resolution | '1k' | '2k' | No | Output resolution |
Expand images beyond their original boundaries (outpainting).
const task = await api.expandImage({
image: './photo.jpg',
up_expansion_ratio: 0.5, // 0-2 (expand 50% upward)
down_expansion_ratio: 0.5,
left_expansion_ratio: 0.3,
right_expansion_ratio: 0.3
});
// Wait for result
const result = await api.waitForImageResult(
task.data.task_id,
api.queryImageExpandTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
image | string | Yes | Image to expand |
up_expansion_ratio | number | Yes | Upward expansion 0-2 |
down_expansion_ratio | number | Yes | Downward expansion 0-2 |
left_expansion_ratio | number | Yes | Left expansion 0-2 |
right_expansion_ratio | number | Yes | Right expansion 0-2 |
Note: Total expanded area cannot exceed 3x the original size.
Create talking head videos from portrait images with audio.
// Using audio file
const task = await api.createAvatar({
image: './portrait.jpg',
sound_file: './speech.mp3', // Local audio file
mode: 'pro'
});
// Using pre-uploaded audio ID
const task = await api.createAvatar({
image: './portrait.jpg',
audio_id: 'uploaded-audio-id',
prompt: 'Happy expression',
mode: 'std'
});
// Wait for result
const result = await api.waitForVideoResult(
task.data.task_id,
api.queryAvatarTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
image | string | Yes | Portrait image |
audio_id | string | One required | Pre-uploaded audio ID |
sound_file | string | One required | Audio file path or URL |
prompt | string | No | Expression/mood guidance |
mode | 'std' | 'pro' | No | Quality mode |
Note: Provide either audio_id OR sound_file, not both.
Check account information, credits, and API health.
// Get account information and resource packs
const now = Date.now();
const accountInfo = await api.getAccountInfo(
now - 86400000, // startTime: 24 hours ago
now // endTime: now
);
console.log('Resource packs:', accountInfo.data.resource_pack_subscribe_infos);
// Check API health (returns true if reachable)
const isHealthy = await api.healthCheck();
if (!isHealthy) {
throw new Error('Kling API is not reachable');
}
// Token management (for debugging)
const token = api.getToken(); // Get current JWT token
api.refreshToken(); // Force token refresh
Methods:
| Method | Returns | Description |
|---|---|---|
getAccountInfo(startTime, endTime) | AccountInfoResponse | Get resource pack subscription info |
healthCheck() | boolean | Check if API is reachable |
getToken() | string | null | Get current JWT token (debugging) |
refreshToken() | void | Force JWT token refresh |
Advanced features for sophisticated video and image generation workflows.
Extend existing generated videos with additional content.
// Extend a previously generated video
const task = await api.extendVideo({
video_id: 'original-video-id', // From text-to-video or image-to-video
prompt: 'Continue with the camera zooming out',
cfg_scale: 0.5 // 0-1, prompt relevance
});
// Query task status
const status = await api.queryExtendVideoTask(task.data.task_id);
// Wait for completion
const result = await api.waitForVideoResult(
task.data.task_id,
api.queryExtendVideoTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
video_id | string | Yes | Video ID from previous generation |
prompt | string | No | Extension prompt (max 2500 chars) |
negative_prompt | string | No | What to avoid (max 2500 chars) |
cfg_scale | number | No | CFG scale 0-1 (default: 0.5) |
callback_url | string | No | Webhook URL |
Generate videos from multiple reference images with smooth transitions.
const task = await api.multiImageToVideo({
image_list: [
{ image: './scene1.jpg' },
{ image: './scene2.jpg' },
{ image: './scene3.jpg' }
],
prompt: 'Smooth cinematic transition between scenes',
model_name: 'kling-v1-6',
mode: 'pro',
duration: '5',
aspect_ratio: '16:9'
});
// Wait for result
const result = await api.waitForVideoResult(
task.data.task_id,
api.queryMultiImageToVideoTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
image_list | MultiImageVideoItem[] | Yes | 1-4 reference images |
prompt | string | Yes | Motion/transition description |
model_name | 'kling-v1-6' | No | Model (only kling-v1-6 supported) |
negative_prompt | string | No | What to avoid |
mode | 'std' | 'pro' | No | Quality mode |
aspect_ratio | VideoAspectRatio | No | Output aspect ratio |
duration | '5' | '10' | No | Video length |
Advanced video generation with flexible multi-modal inputs using template syntax.
// Using first/end frame control
const task = await api.omniVideo({
prompt: 'A cat walking through <<<image_1>>> and ending at <<<image_2>>>',
image_list: [
{ image_url: './start.jpg', type: 'first_frame' },
{ image_url: './end.jpg', type: 'end_frame' }
],
model_name: 'kling-video-o1',
duration: '5',
aspect_ratio: '16:9'
});
// Wait for result
const result = await api.waitForVideoResult(
task.data.task_id,
api.queryOmniVideoTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Prompt with template syntax (max 2500 chars) |
model_name | OmniVideoModel | No | Model (default: kling-video-o1) |
image_list | OmniVideoImageItem[] | No | Images with optional frame type |
video_list | OmniVideoListItem[] | No | Reference videos |
element_list | OmniElementListItem[] | No | Element references by ID |
aspect_ratio | VideoAspectRatio | No | Output aspect ratio |
duration | '5' | '10' | No | Video length |
Template Syntax: Use <<<image_1>>>, <<<video_1>>>, <<<element_1>>> to reference items from their respective lists.
Advanced image generation with multi-modal inputs and template syntax.
// Using image reference in prompt
const task = await api.omniImage({
prompt: 'A portrait in the style of <<<image_1>>> featuring a mountain landscape',
image_list: [
{ image: './style-reference.jpg' }
],
model_name: 'kling-image-o1',
n: 4,
resolution: '2k',
aspect_ratio: '16:9'
});
// Wait for result
const result = await api.waitForImageResult(
task.data.task_id,
api.queryOmniImageTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Prompt with template syntax (max 2500 chars) |
model_name | OmniImageModel | No | Model (default: kling-image-o1) |
image_list | OmniImageListItem[] | No | Reference images |
element_list | OmniElementListItem[] | No | Element references by ID |
n | number | No | Number of images (1-9) |
resolution | '1k' | '2k' | No | Output resolution |
aspect_ratio | OmniImageAspectRatio | No | Aspect ratio (includes 'auto') |
Combine multiple subject images with optional scene and style references.
const task = await api.multiImageToImage({
subject_image_list: [
{ subject_image: './subject1.jpg' },
{ subject_image: './subject2.jpg' }
],
scene_image: './background.jpg',
style_image: './art-style.jpg',
prompt: 'The subjects meeting in this scene with artistic style',
model_name: 'kling-v2-1',
n: 4,
aspect_ratio: '16:9'
});
// Wait for result
const result = await api.waitForImageResult(
task.data.task_id,
api.queryMultiImageToImageTask.bind(api)
);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
subject_image_list | SubjectImageItem[] | Yes | 1-4 subject images |
prompt | string | No | Generation prompt (max 2500 chars) |
model_name | 'kling-v2' | 'kling-v2-1' | No | Model version |
scene_image | string | No | Scene/background reference |
style_image | string | No | Style reference image |
n | number | No | Number of images (1-9) |
aspect_ratio | ImageAspectRatio | No | Output aspect ratio |
Note: Subject images should be pre-cropped to focus on the subject.
| Model | CFG Scale | Sound | Camera Control | Description |
|---|---|---|---|---|
kling-v1 | Yes | No | No | Base model |
kling-v1-6 | Yes | No | Yes | Camera control support |
kling-v2-master | No | No | No | V2 master quality |
kling-v2-1-master | No | No | No | V2.1 master quality |
kling-v2-5-turbo | No | No | No | Fast generation |
kling-v2-6 | No | Yes | No | Sound generation support |
| Model | CFG Scale | Image Tail | Voice | Dynamic Masks | Camera |
|---|---|---|---|---|---|
kling-v1 | Yes | No | No | No | No |
kling-v1-5 | Yes | Yes (pro) | No | Yes | Yes |
kling-v1-6 | Yes | Yes | No | Yes | Yes |
kling-v2-master | No | No | No | No | No |
kling-v2-1 | No | Yes (pro) | No | No | No |
kling-v2-1-master | No | No | No | No | No |
kling-v2-5-turbo | No | Yes (pro) | No | No | No |
kling-v2-6 | No | Yes | Yes | No | No |
| Model | Image Reference | Max Images |
|---|---|---|
kling-v1 | No | 9 |
kling-v1-5 | Yes | 9 |
kling-v2 | No | 9 |
kling-v2-new | No | 9 |
kling-v2-1 | No | 9 |
Camera control is available for supported models (kling-v1-6 for text-to-video, kling-v1-5 and kling-v1-6 for image-to-video).
const task = await api.textToVideo({
prompt: 'A beautiful landscape',
model_name: 'kling-v1-6',
camera_control: {
type: 'down_back' // Preset camera movement
}
});
Available presets:
simple - No preset, use config for fine controldown_back - Move down and backforward_up - Move forward and upright_turn_forward - Turn right while moving forwardleft_turn_forward - Turn left while moving forwardconst task = await api.textToVideo({
prompt: 'A beautiful landscape',
model_name: 'kling-v1-6',
camera_control: {
type: 'simple',
config: {
horizontal: 5, // -10 to 10: Pan left/right
vertical: 0, // -10 to 10: Move up/down
pan: 0, // -10 to 10: Rotate left/right
tilt: 0, // -10 to 10: Tilt up/down
roll: 0, // -10 to 10: Roll camera
zoom: 3 // -10 to 10: Zoom in/out
}
}
});
Note: Only one non-zero config parameter is allowed per request.
import { KlingAPI } from 'kling-api';
const api = new KlingAPI();
async function generateVideo() {
// Create task
const task = await api.textToVideo({
prompt: 'A serene lake surrounded by mountains at golden hour',
model_name: 'kling-v2-master',
mode: 'pro',
duration: '5',
aspect_ratio: '16:9'
});
console.log('Task created:', task.data.task_id);
// Wait for completion with spinner
const result = await api.waitForVideoResult(task.data.task_id, undefined, {
showSpinner: true,
timeout: 300000 // 5 minutes
});
// Save to disk
const paths = await api.saveVideoResult(result, './videos', 'lake sunset');
console.log('Saved to:', paths);
}
generateVideo().catch(console.error);
const task = await api.imageToVideo({
image: './landscape.jpg',
prompt: 'Gentle camera push forward through the scene',
model_name: 'kling-v1-6',
mode: 'pro',
camera_control: {
type: 'simple',
config: { zoom: 5 }
}
});
const task = await api.generateImage({
prompt: 'A futuristic cityscape at night with neon lights',
model_name: 'kling-v2-1',
n: 9,
aspect_ratio: '21:9',
resolution: '2k'
});
const result = await api.waitForImageResult(task.data.task_id);
// result.data.task_result.images is an array of 9 images
for (const image of result.data.task_result.images) {
console.log(`Image ${image.index}: ${image.url}`);
}
const task = await api.createAvatar({
image: './portrait.jpg',
sound_file: './narration.mp3',
prompt: 'Professional, confident expression',
mode: 'pro'
});
const result = await api.waitForVideoResult(
task.data.task_id,
api.queryAvatarTask.bind(api)
);
// Expand a portrait to landscape format
const task = await api.expandImage({
image: './portrait.jpg',
up_expansion_ratio: 0,
down_expansion_ratio: 0,
left_expansion_ratio: 1, // Double width on left
right_expansion_ratio: 1 // Double width on right
});
Generated media and metadata are organized by feature and model:
datasets/
└── kling/
├── text-to-video/
│ ├── 2025-01-13_14-30-22_mountain_landscape.mp4
│ ├── 2025-01-13_14-30-22_mountain_landscape_metadata.json
│ └── ...
├── image-to-video/
│ └── ...
├── images/
│ └── ...
├── image-expand/
│ └── ...
└── avatar/
└── ...
Metadata Format:
{
"task_id": "abc123",
"video_id": "vid456",
"duration": 5,
"url": "https://...",
"created_at": 1705156222,
"prompt": "A serene mountain landscape"
}
NODE_ENV=production)All API errors are wrapped in KlingAPIError with useful properties:
try {
await api.textToVideo({ prompt: '' });
} catch (error) {
if (error instanceof KlingAPIError) {
console.log('Error code:', error.code);
console.log('HTTP status:', error.httpStatus);
console.log('Request ID:', error.requestId);
console.log('Retryable:', error.isRetryable());
}
}
Transient errors (502, 503, 504) are automatically retried with exponential backoff:
Parameter validation happens before API calls to save credits:
try {
await api.textToVideo({
prompt: 'x'.repeat(3000) // Exceeds 2500 char limit
});
} catch (error) {
// ValidationError: prompt: Prompt cannot exceed 2500 characters
}
Error: Kling API credentials not found. Provide accessKey and secretKey via:
1. Constructor parameters
2. Environment variables (KLING_ACCESS_KEY, KLING_SECRET_KEY)
3. Local .env file
4. Global ~/.kling/.env file
Solution: Configure your credentials using one of the methods above.
Error: Authentication failed (401)
Solution:
Error: Polling timeout exceeded
Solution:
{ timeout: 600000 } (10 minutes)Error: camera_control is not supported by kling-v1
Solution: Use a model that supports camera control:
kling-v1-6kling-v1-5 or kling-v1-6# Install dependencies
npm install
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Build TypeScript
npm run build
This package is part of the img-gen ecosystem:
bfl-api - Black Forest Labs FLUX modelsstability-ai-api - Stability AI Stable Diffusionideogram-api - Ideogram image generationgoogle-genai-api - Google ImagenMIT License - see LICENSE for details.
Disclaimer: This project is an independent community wrapper and is not affiliated with Kling AI or Kuaishou Technology.
FAQs
Kling AI API wrapper - Video and image generation with JWT authentication for Node.js
We found that kling-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.