Kling AI 프로바이더

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/klingai에서 기본 프로바이더 인스턴스 klingai를 불러올 수 있어요:

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

커스터마이즈가 필요하다면 @ai-sdk/klingai에서 createKlingAI를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

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

const klingai = createKlingAI({
  apiKey: ***
});

Kling AI 프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• apiKey string

  Kling AI API 키. 기본값은 KLINGAI_API_KEY 환경 변수예요. Kling AI 개발자 콘솔에서 만드세요.

• accessKey string

  Kling AI access key. 기본값은 KLINGAI_ACCESS_KEY 환경 변수예요. 레거시 인증 — apiKey를 선호하세요.

• secretKey string

  Kling AI secret key. 기본값은 KLINGAI_SECRET_KEY 환경 변수예요. 레거시 인증 — apiKey를 선호하세요.

• baseURL string

  API 호출에 다른 URL 접두사를 사용해요. 예를 들어 프록시 서버를 쓸 때 유용해요. 기본 접두사는 https://api-singapore.klingai.com이에요.

• headers Record<string,string>

  요청에 포함할 커스텀 헤더예요.

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

  커스텀 fetch 구현이에요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

인증 (Authentication)

Kling AI는 두 가지 인증 방식을 지원해요:

• API 키 (권장). 단일 키를 bearer 토큰으로 보내요. Kling AI 개발자 콘솔에서 만들고 KLINGAI_API_KEY로 설정하거나 apiKey 설정으로 전달하세요.
• Access key / secret key (레거시). 프로바이더가 각 요청에 대해 단기 JWT에 서명하는 데 사용하는 키 쌍이에요. KLINGAI_ACCESS_KEY와 KLINGAI_SECRET_KEY를 설정하거나 accessKey와 secretKey 설정을 전달하세요.

자격 증명은 다음 순서로 해석되며, 명시적 설정이 환경 변수보다 우선해요:

1. apiKey 설정
2. accessKey와 secretKey 설정
3. KLINGAI_API_KEY 환경 변수
4. KLINGAI_ACCESS_KEY와 KLINGAI_SECRET_KEY 환경 변수

비디오 모델 (Video Models)

.video() 팩토리 메서드로 Kling AI 비디오 모델을 만들 수 있어요. AI SDK에서 비디오 생성에 대해 더 알고 싶다면 generateVideo()를 참고하세요.

이 프로바이더는 현재 네 가지 비디오 생성 모드를 지원해요: 텍스트-영상, 이미지-영상, 참조-영상(다중 이미지), 모션 컨트롤.

텍스트-영상 (Text-to-Video)

텍스트 프롬프트로 비디오를 생성해요:

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)

시작 프레임 이미지와 선택적 텍스트 프롬프트로 비디오를 생성해요. 인기 있는 시작+끝 프레임 기능은 imageTail 옵션으로 사용할 수 있어요:

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)

각각 자체 프롬프트와 지속 시간을 가진 여러 스토리보드 샷으로 비디오를 생성해요 (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,
  },
});

멀티샷은 시작 프레임 이미지와 샷별 프롬프트를 결합해 이미지-영상에서도 동작해요.

참조-영상 (다중 이미지) (Reference-to-Video)

최상위 inputReferences 옵션을 사용해 참조 이미지를 결합하는 비디오를 생성해요.

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)

참조 비디오의 모션을 캐릭터 이미지로 전달해 비디오를 생성해요:

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)

텍스트-영상, 이미지-영상, 다중 이미지-영상, 모션 컨트롤의 경우 experimental_startVideo({ model, prompt, webhookUrl })를 사용해 애플리케이션 소유 콜백 수신기를 등록해요. SDK는 webhookUrl을 callback_url로 전달하며, 이는 providerOptions.klingai.callback_url보다 우선해요. webhookUrl을 생략하면 원래 callback_url이 변경 없이 전달돼요.

KlingAI는 진행 알림(task_status: 'submitted' 또는 'processing')과 종료 알림('succeed' 또는 'failed')을 보내요. 수신기는 진행 알림을 필터링하고 콜백을 작업과 연관시켜야 해요. experimental_startVideo가 반환한 작업과 함께 experimental_getVideoStatus(model, { operation })를 사용해 상태를 확인하고 종료 알림 후 결과를 검색하세요.

이 모델들은 콜백 프로토콜에 진행 인식 수신기가 필요하므로 의도적으로 handleWebhookOption을 노출하지 않아요. Core generateVideo({ webhook })는 웹훅 팩토리를 호출하지 않고 폴링으로 폴백해요. 일반 generateVideo()도 폴링해요. Workflow의 기존 네이티브 웹훅 기능 확인은 이 직접 프로바이더 모델을 웹훅 기반 생성에 거부해요. 호출자 관리 콜백에는 명시적 start/status 흐름을 사용하세요.

비디오 프로바이더 옵션 (Video Provider Options)

providerOptions.klingai를 통해 다음 프로바이더 옵션을 사용할 수 있어요. 옵션은 모드에 따라 다르며, 모델별 지원은 KlingAI Capability Map을 참고하세요.

공통 옵션 (Common Options)

• mode 'std' | 'pro'

  비디오 생성 모드예요. 'std'는 비용 효율적이에요. 'pro'는 더 높은 품질을 생성하지만 더 오래 걸려요.

• pollIntervalMs number

  작업 상태 확인을 위한 폴링 간격(밀리초)이에요. 기본값은 5000.

• pollTimeoutMs number

  비디오 생성을 위한 최대 대기 시간(밀리초)이에요. 기본값은 600000(10분).

• watermarkEnabled boolean

  워터마크가 있는 결과를 동시에 생성할지 여부예요.

텍스트-영상 및 이미지-영상 옵션 (Text-to-Video and Image-to-Video Options)

• negativePrompt string

  생성된 비디오에서 피하고 싶은 내용에 대한 설명 (최대 2500자).

• sound 'on' | 'off'

  오디오를 동시에 생성할지 여부예요. V2.6 이상 모델만 지원하며 mode: 'pro'가 필요해요.

• cfgScale number

  비디오 생성의 유연성이에요. 값이 높을수록 프롬프트 준수가 강해져요. 범위: [0, 1]. V2.x 모델에서는 지원되지 않아요.

• cameraControl object

  type 프리셋('simple', 'down_back', 'forward_up', 'right_turn_forward', 'left_turn_forward')과 선택적 config(범위: [-10, 10]인 horizontal, vertical, pan, tilt, roll, zoom 값 포함)가 있는 카메라 움직임 제어.

• multiShot boolean

  멀티샷 비디오 생성을 활성화해요 (Kling v3.0+). true면 비디오가 개별 프롬프트와 지속 시간을 가진 최대 6개의 스토리보드 샷으로 분할돼요.

• shotType 'customize' | 'intelligence'

  멀티샷 생성의 스토리보드 방법이에요. 'customize'는 사용자 정의 샷에 multiPrompt를 사용해요. 'intelligence'는 주 프롬프트를 기반으로 모델이 자동 분할하게 해요. multiShot이 true일 때 필수.

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

  멀티샷 생성을 위한 샷별 세부 정보예요. 각 샷에는 index(number), prompt(string, 최대 512자), duration(string, 초)이 있어요. 샷 지속 시간의 합은 총 지속 시간과 같아야 해요. multiShot이 true이고 shotType이 'customize'일 때 필수.

• voiceList Array<{voice_id: string}>

  음성 제어를 위한 음성 참조 (Kling v3.0+). 최대 2개의 음성. 프롬프트에서 <<<voice_1>>> 템플릿 문법으로 참조하세요. sound: 'on'이 필요해요. I2V 엔드포인트에서 elementList와 함께 쓸 수 없어요.

이미지-영상 전용 옵션 (Image-to-Video Only Options)

• imageTail string

  시작+끝 프레임 제어를 위한 끝 프레임 이미지. 이미지 URL 또는 원시 base64 인코딩 데이터를 받아요. 대부분의 모델에서 mode: 'pro'가 필요해요.

• staticMask string

  모션 브러시용 정적 브러시 마스크 이미지. 이미지 URL 또는 원시 base64 인코딩 데이터를 받아요.

• dynamicMasks Array

  모션 브러시용 동적 브러시 구성. 최대 6개 그룹, 각각 mask(이미지 URL 또는 base64)와 trajectories({x, y} 좌표 배열)를 가짐.

이미지-영상 및 모션 컨트롤 옵션 (Image-to-Video and Motion Control Options)

• elementList Array<{element_id: number}>

  요소 제어를 위한 참조 요소 (Kling v3.0+). 비디오 캐릭터 요소와 다중 이미지 요소를 지원해요. I2V는 최대 3개 요소(voiceList와 함께 쓸 수 없음). 모션 컨트롤은 최대 1개 요소.

모션 컨트롤 전용 옵션 (Motion Control Only Options)

• videoUrl string (필수)

  참조 모션 비디오의 URL. .mp4/.mov 지원, 최대 100MB, 지속 시간 3–30초.

• characterOrientation 'image' | 'video' (필수)

  생성된 비디오에서 캐릭터의 방향이에요. 'image'는 참조 이미지 방향과 일치 (최대 10초 비디오). 'video'는 참조 비디오 방향과 일치 (최대 30초 비디오).

• keepOriginalSound 'yes' | 'no'

  참조 비디오의 원래 사운드를 유지할지 여부예요. 기본값은 'yes'.

비디오 모델 기능 (Video Model Capabilities)

텍스트-영상 (Text-to-Video)

이미지-영상 (Image-to-Video)

모션 컨트롤 (Motion Control)

더 알아보기 (Learn more)

• AI Gateway
• xAI Grok
• OpenAI
• Azure OpenAI
• Anthropic
• Open Responses
• Claude Platform on AWS
• Amazon Bedrock
• Groq
• Fal
• AssemblyAI
• GMI Cloud
• TypeSafe
• DeepInfra
• Deepgram
• Black Forest Labs
• Gladia
• Google
• Hume
• Google Vertex AI
• Rev.ai
• Baseten
• Hugging Face
• QuiverAI
• Fish Audio
• Mistral AI
• Z.AI
• Together.ai
• Cohere
• Fireworks
• Voyage AI
• DeepSeek
• Moonshot AI
• Alibaba
• MiniMax
• Cerebras
• Replicate
• Prodia
• Perplexity
• Luma
• ByteDance
• Kling AI
• ElevenLabs
• Cartesia

전체 사이트맵