Kling AI

The Kling AI provider contains support for Kling AI's video generation models, including text-to-video, image-to-video, motion control, and multi-shot video generation.

Setup

The Kling AI provider is available in the @ai-sdk/klingai module. You can install it with

$ pnpm add @ai-sdk/klingai

$ npm install @ai-sdk/klingai

$ yarn add @ai-sdk/klingai

$ bun add @ai-sdk/klingai

Provider Instance

You can import the default provider instance klingai from @ai-sdk/klingai:

import { klingai } from '@ai-sdk/klingai';

If you need a customized setup, you can import createKlingAI from @ai-sdk/klingai and create a provider instance with your settings:

import { createKlingAI } from '@ai-sdk/klingai';

const klingai = createKlingAI({
  apiKey: 'your-api-key',
});

You can use the following optional settings to customize the Kling AI provider instance:

• apiKey string

  Kling AI API key. Defaults to the KLINGAI_API_KEY environment variable. Create one in the Kling AI developer console.

• accessKey string

  Kling AI access key. Defaults to the KLINGAI_ACCESS_KEY environment variable. Legacy authentication — prefer apiKey.

• secretKey string

  Kling AI secret key. Defaults to the KLINGAI_SECRET_KEY environment variable. Legacy authentication — prefer apiKey.

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api-singapore.klingai.com.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Authentication

Kling AI supports two authentication schemes:

• API key (recommended). A single key that is sent as a bearer token. Create one in the Kling AI developer console and set it as KLINGAI_API_KEY, or pass it via the apiKey setting.
• Access key / secret key (legacy). A key pair that the provider uses to sign a short-lived JWT for each request. Set KLINGAI_ACCESS_KEY and KLINGAI_SECRET_KEY, or pass the accessKey and secretKey settings.

Credentials are resolved in this order, with explicit settings taking precedence over environment variables:

1. The apiKey setting
2. The accessKey and secretKey settings
3. The KLINGAI_API_KEY environment variable
4. The KLINGAI_ACCESS_KEY and KLINGAI_SECRET_KEY environment variables

Video Models

You can create Kling AI video models using the .video() factory method. For more on video generation with the AI SDK see generateVideo().

This provider currently supports four video generation modes: text-to-video, image-to-video, reference-to-video (multi-image), and motion control.

Text-to-Video

Generate videos from text prompts:

import { klingai, type KlingAIVideoModelOptions } from '@ai-sdk/klingai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { videos } = await generateVideo({
  model: klingai.video('kling-v3.0-t2v'),
  prompt: 'A chicken flying into the sunset in the style of 90s anime.',
  aspectRatio: '16:9',
  duration: 5,
  providerOptions: {
    klingai: {
      mode: 'std',
    } satisfies KlingAIVideoModelOptions,
  },
});

Image-to-Video

Generate videos from a start frame image with an optional text prompt. The popular start+end frame feature is available via the imageTail option:

import { klingai, type KlingAIVideoModelOptions } from '@ai-sdk/klingai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { videos } = await generateVideo({
  model: klingai.video('kling-v3.0-i2v'),
  prompt: {
    image: 'https://example.com/start-frame.png',
    text: 'The cat slowly turns its head and blinks',
  },
  duration: 5,
  providerOptions: {
    klingai: {
      // Pro mode required for start+end frame control
      mode: 'pro',
      // Optional: end frame image
      imageTail: 'https://example.com/end-frame.png',
    } satisfies KlingAIVideoModelOptions,
  },
});

Multi-Shot Video Generation

Generate videos with multiple storyboard shots, each with its own prompt and duration (Kling v3.0+):

import { klingai, type KlingAIVideoModelOptions } from '@ai-sdk/klingai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { videos } = await generateVideo({
  model: klingai.video('kling-v3.0-t2v'),
  prompt: '',
  aspectRatio: '16:9',
  duration: 10,
  providerOptions: {
    klingai: {
      mode: 'pro',
      multiShot: true,
      shotType: 'customize',
      multiPrompt: [
        {
          index: 1,
          prompt: 'A sunrise over a calm ocean, warm golden light.',
          duration: '4',
        },
        {
          index: 2,
          prompt: 'A flock of seagulls take flight from the beach.',
          duration: '3',
        },
        {
          index: 3,
          prompt: 'Waves crash against rocky cliffs at sunset.',
          duration: '3',
        },
      ],
      sound: 'on',
    } satisfies KlingAIVideoModelOptions,
  },
});

Multi-shot also works with image-to-video by combining a start frame image with per-shot prompts.

Reference-to-Video (Multi-Image)

Generate a video that combines reference images using the top-level inputReferences option.

import { klingai, type KlingAIVideoModelOptions } from '@ai-sdk/klingai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { videos } = await generateVideo({
  model: klingai.video('kling-v1.6-i2v'),
  prompt: 'The two characters meet and walk together through a sunny park',
  inputReferences: [
    'https://example.com/character-1.png',
    'https://example.com/character-2.png',
  ],
  aspectRatio: '16:9',
  duration: 5,
  providerOptions: {
    klingai: {
      mode: 'std',
    } satisfies KlingAIVideoModelOptions,
  },
});

Motion Control

Generate video by transferring motion from a reference video to a character image:

import { klingai, type KlingAIVideoModelOptions } from '@ai-sdk/klingai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { videos } = await generateVideo({
  model: klingai.video('kling-v3.0-motion-control'),
  prompt: {
    image: 'https://example.com/character.png',
    text: 'The character performs a smooth dance move',
  },
  providerOptions: {
    klingai: {
      videoUrl: 'https://example.com/reference-motion.mp4',
      characterOrientation: 'image',
      mode: 'std',
      // Optional: reference element from element library (v3.0+, max 1)
      elementList: [{ element_id: 829836802793406551 }],
    } satisfies KlingAIVideoModelOptions,
  },
});

Caller-Managed Callbacks

For text-to-video, image-to-video, multi-image-to-video, and motion control, use experimental_startVideo({ model, prompt, webhookUrl }) to register an application-owned callback receiver. The SDK forwards webhookUrl as callback_url, taking precedence over providerOptions.klingai.callback_url. When webhookUrl is omitted, a raw callback_url is passed through unchanged.

KlingAI sends progress notifications (task_status: 'submitted' or 'processing') as well as terminal notifications ('succeed' or 'failed'). Your receiver must filter progress notifications and correlate callbacks with the task. Use experimental_getVideoStatus(model, { operation }) with the operation returned by experimental_startVideo to check status and retrieve the result after a terminal notification.

These models deliberately do not expose handleWebhookOption because their callback protocol requires a progress-aware receiver. Core generateVideo({ webhook }) falls back to polling without calling the webhook factory. Plain generateVideo() also polls. Workflow's existing native webhook capability check rejects these direct provider models for webhook-based generation; use the explicit start/status flow for caller-managed callbacks.

Video Provider Options

The following provider options are available via providerOptions.klingai. Options vary by mode — see the KlingAI Capability Map for per-model support.

Common Options

• mode 'std' | 'pro'

  Video generation mode. 'std' is cost-effective. 'pro' produces higher quality but takes longer.

• pollIntervalMs number

  Polling interval in milliseconds for checking task status. Defaults to 5000.

• pollTimeoutMs number

  Maximum wait time in milliseconds for video generation. Defaults to 600000 (10 minutes).

• watermarkEnabled boolean

  Whether to generate watermarked results simultaneously.

Text-to-Video and Image-to-Video Options

• negativePrompt string

  A description of what to avoid in the generated video (max 2500 characters).

• sound 'on' | 'off'

  Whether to generate audio simultaneously. Only V2.6 and subsequent models support this, and requires mode: 'pro'.

• cfgScale number

  Flexibility in video generation. Higher values mean stronger prompt adherence. Range: [0, 1]. Not supported by V2.x models.

• cameraControl object

  Camera movement control with a type preset ('simple', 'down_back', 'forward_up', 'right_turn_forward', 'left_turn_forward') and optional config with horizontal, vertical, pan, tilt, roll, zoom values (range: [-10, 10]).

• multiShot boolean

  Enable multi-shot video generation (Kling v3.0+). When true, the video is split into up to 6 storyboard shots with individual prompts and durations.

• shotType 'customize' | 'intelligence'

  Storyboard method for multi-shot generation. 'customize' uses multiPrompt for user-defined shots. 'intelligence' lets the model auto-segment based on the main prompt. Required when multiShot is true.

• multiPrompt Array<{index, prompt, duration}>

  Per-shot details for multi-shot generation. Each shot has an index (number), prompt (string, max 512 characters), and duration (string, in seconds). Shot durations must sum to the total duration. Required when multiShot is true and shotType is 'customize'.

• voiceList Array<{voice_id: string}>

  Voice references for voice control (Kling v3.0+). Up to 2 voices. Reference via <<<voice_1>>> template syntax in the prompt. Requires sound: 'on'. Cannot coexist with elementList on the I2V endpoint.

Image-to-Video Only Options

• imageTail string

  End frame image for start+end frame control. Accepts an image URL or raw base64-encoded data. Requires mode: 'pro' for most models.

• staticMask string

  Static brush mask image for motion brush. Accepts an image URL or raw base64-encoded data.

• dynamicMasks Array

  Dynamic brush configurations for motion brush. Up to 6 groups, each with a mask (image URL or base64) and trajectories (array of {x, y} coordinates).

Image-to-Video and Motion Control Options

• elementList Array<{element_id: number}>

  Reference elements for element control (Kling v3.0+). Supports video character elements and multi-image elements. Up to 3 elements for I2V (cannot coexist with voiceList). Up to 1 element for motion control.

Motion Control Only Options

• videoUrl string (required)

  URL of the reference motion video. Supports .mp4/.mov, max 100MB, duration 3–30 seconds.

• characterOrientation 'image' | 'video' (required)

  Orientation of the characters in the generated video. 'image' matches the reference image orientation (max 10s video). 'video' matches the reference video orientation (max 30s video).

• keepOriginalSound 'yes' | 'no'

  Whether to keep the original sound from the reference video. Defaults to 'yes'.

Video Model Capabilities

Text-to-Video

Image-to-Video

Motion Control