Kling API 연동 가이드: 공식 API와 애그리게이터 비교 (2026)

Kling 영상 생성은 단 하나의 범용 API 호출로 끝나지 않습니다. Kuaishou의 영상 생성 모델인 Kling은 공식 Open Platform뿐 아니라 WaveSpeedAI, KIE, fal 같은 애그리게이터를 통해서도 제공됩니다. 인증 정보, 모델 ID, 요청 형식, 과금 방식은 모두 다르지만, 공통적인 운영 흐름은 같습니다. 작업을 제출하고, 작업 ID를 저장한 뒤, 최종 상태가 될 때까지 기다리고, 무분별한 재시도 없이 결과를 가져오는 비동기 방식입니다.

SDK보다 먼저 접근 경로부터 정하자

Kling은 공식 Open Platform을 운영하지만, “Kling API”를 검색하면 독립 게이트웨이도 함께 나옵니다. 모델 이름만 보고 고르기보다 공급사 접근성, 연동 속도, 과금 통제 방식을 기준으로 경로를 선택하는 편이 낫습니다.

경로	인증 방식	작업 흐름	추천 상황	주요 고려 사항
Kling Open Platform	Kling의 최신 개발자 문서에 나온 인증 정보와 스키마 사용	공식 태스크 흐름 따르기	Kuaishou와 직접 계약하거나 퍼스트파티 접근이 필요한 경우	온보딩, 가격, 동시성 규칙은 공식 계정에서 확인해야 함
WaveSpeedAI	`Authorization: Bearer <key>`	`POST`로 예측 요청 후 `GET`으로 결과 조회	여러 모델을 하나의 단순한 REST 방식으로 연동하려는 경우	WaveSpeed의 엔드포인트 ID, 가격, 제한이 적용됨
KIE	`Authorization: Bearer <token>`	`createTask` 호출 후 콜백 또는 작업 조회	Kling 3.0 멀티샷과 이름 있는 엘리먼트가 필요한 경우	KIE의 작업 요청 형식은 WaveSpeed나 fal과 호환되지 않음
fal	`Authorization: Key $FAL_KEY` 또는 fal SDK	큐 제출 및 결과 조회	큐 헬퍼와 모델별 스키마를 원하는 SDK 사용자	엔드포인트 ID와 큐 동작은 fal 전용임

해상도별 가격은 기존 Kling 3 API 가격 가이드를 참고하세요. 이 글에서는 가격, 오디오 배수, 동시성, 실패 작업 과금을 공급사별 설정값으로 다룹니다.

공식 Kling API를 쓰는 흐름

조달 절차상 Kuaishou와 직접 관계를 맺어야 하거나 퍼스트파티 모델 접근이 필요하다면 공식 Open Platform을 사용하세요. 현재 공식 문서는 인증 정보 설정, 작업 생성, 콜백, 동시성 규칙, 오류 코드를 구분해 설명합니다. 애그리게이터용 페이로드를 억지로 변형하기보다 공식 문서의 흐름을 그대로 따르는 것이 맞습니다.

인증 가이드에서 공식 인증 정보를 생성하거나 조회하고, 토큰은 서버 측에서만 관리합니다.
공식 레퍼런스에 나온 모델별 엔드포인트와 요청 필드를 사용해 비동기 영상 작업을 제출합니다.
상태 푸시가 필요하면 callback_url을 추가합니다. 문서에 나온 콜백 상태는 submitted, processing, succeed, failed이며, 실패 시에는 task_status_msg를 저장하세요.
계정에 현재 배정된 동시성 한도를 애플리케이션에서 직접 지켜야 합니다. 공식 동시성 가이드는 과부하를 HTTP 429, 비즈니스 코드 1303으로 설명하며, Kling이 반드시 작업을 대신 큐잉해 준다는 뜻은 아닙니다.
공식 오류 코드 레퍼런스를 사용해 잘못된 인증 정보, 유효하지 않은 파라미터, 리소스 부족, 정책 차단, 재시도 가능한 서버 오류를 구분합니다.

공식 인증 페이지는 접근 가능한 문서 버전에서 클라이언트 렌더링으로 제공됩니다. 따라서 이 글에서는 검증되지 않은 토큰 생성 예시를 재현하지 않습니다. WaveSpeed, KIE, fal의 헤더가 그대로 작동한다고 가정하지 말고, 해당 페이지에서 최신 인증 형식을 확인해 사용하세요.

정확한 페이로드를 추측하지 않고도 공식 API의 작업 생명주기는 다음처럼 추상화할 수 있습니다.

official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)

이는 복사해 바로 쓸 수 있는 엔드포인트 예제가 아니라 생명주기 개요입니다. 정확한 토큰, 경로, 요청 필드, 응답 형식은 링크한 공식 레퍼런스에서 확인하세요.

애그리게이터가 더 잘 맞는 경우

사용량 기반으로 빠르게 프로토타입을 만들거나, 하나의 계정으로 여러 모델을 쓰거나, 공급사 SDK를 활용하려면 애그리게이터가 더 편할 수 있습니다. 다만 키, 스키마, 큐, 출력 URL, 경우에 따라 보존 기간까지 공급사가 관리합니다. 재시도하기 전에 어느 계층에서 실패했는지부터 분류해야 합니다.

공통 인터페이스로 묶을 수 있는 Kling API 계약

프로덕션 클라이언트는 공급사별 차이를 내부 함수 하나 뒤로 감추는 구조가 좋습니다. 어떤 경로를 선택하든 애플리케이션은 다음 단계를 수행해야 합니다.

크레딧을 쓰기 전에 프롬프트와 미디어 URL을 검증합니다.
공급사별 모델 ID로 영상 생성 작업을 제출합니다.
반환된 작업 ID 또는 예측 ID를 즉시 영속 저장합니다.
콜백을 수신하거나 결과 엔드포인트를 폴링해 작업이 최종 상태에 도달할 때까지 확인합니다.
출력 URL, 공급사, 모델, 파라미터, 비용 메타데이터를 저장합니다.
공급사가 실패, 취소, 타임아웃, 삭제 상태를 보고하면 재시도를 멈춥니다.

추상화 계층은 예를 들어 다음과 같은 자체 표준 객체를 반환할 수 있습니다.

{
  "provider": "wavespeed",
  "job_id": "provider-job-id",
  "status": "queued",
  "output_url": null,
  "error": null
}

공급사가 달라도 비교적 통하는 파라미터

개념	Kling에서의 일반적 용도	값 예시
프롬프트	피사체, 동작, 카메라, 조명, 분위기 설명	`A slow dolly toward a rain-soaked neon street`
길이	클립 길이 선택	엔드포인트에 따라 `3`, `5`, `10`, `15`초
화면비	배포 플랫폼에 맞추기	`16:9`, `9:16`, `1:1`
오디오 또는 사운드	지원되는 경로에서 네이티브 사운드 활성화	`true` / `false` 또는 `sound`
시작 이미지	제공한 첫 프레임을 기반으로 애니메이션 생성	공개 이미지 URL
마지막 이미지	지원되는 경우 마지막 프레임 유도	공개 이미지 URL
네거티브 프롬프트	흐림, 왜곡, 원치 않는 오브젝트 제외	공급사별 문자열 필드
멀티샷 프롬프트	긴 아이디어를 여러 장면으로 분할	프롬프트와 길이 객체의 배열
모드 또는 티어	반복 생성 비용과 품질 간 균형 조절	`std`, `pro` 또는 공급사별 티어

개념은 비슷해도 필드명은 다릅니다. generate_audio, sound, generate_audio: true는 서비스마다 유사한 기능을 가리킬 수 있습니다. 공급사별 스키마는 각각 별도 어댑터로 다루세요.

공급사마다 절대 섞으면 안 되는 값

가장 먼저 걸리는 함정은 모델 ID입니다. kling-3.0, kling-3.0/video, fal-ai/kling-video/v3/standard/text-to-video, kwaivgi/kling-v3.0-std/text-to-video는 서로 바꿔 쓸 수 있는 값이 아니라 서로 다른 API 경로를 식별합니다.

인증 헤더, 콜백 이름, 결과 URL, 작업 상태값, 파일 업로드 규칙도 마찬가지입니다. 예를 들어 한 공급사의 completed 상태 문자열을 하드코딩하면, 다른 공급사의 succeeded 또는 failed 응답을 잘못 분류할 수 있습니다.

실제 요청 형식 3가지

아래 공급사별 예시는 왜 범용 Kling 엔드포인트가 존재하지 않는지 잘 보여 줍니다.

WaveSpeedAI: 예측 ID를 받고 결과를 폴링하는 방식

WaveSpeedAI는 Kling 3.0 Standard 텍스트-투-비디오 엔드포인트를 다음과 같이 문서화합니다.

POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video

요청에는 Bearer 토큰을 사용합니다. 엔드포인트는 prediction ID를 반환하며, 결과는 다음 주소에서 조회합니다.

GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

최소한의 cURL 흐름은 다음과 같습니다.

export WAVESPEED_API_KEY="replace_me"

submit=$(curl --fail-with-body -s \
  -X POST \
  "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic sunrise over a futuristic cityscape",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }')

prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')

curl -s \
  "https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

WaveSpeedAI 모델 문서에는 3~15초 길이, 16:9·9:16·1:1 화면비, 기본값 0.5의 cfg_scale이 안내되어 있습니다. Standard 가격표상 사운드 없는 5초 클립은 $0.42, 사운드 포함 시 $0.63입니다. 이는 모든 Kling API에 적용되는 가격이 아니라 해당 공급사 기준의 스냅샷으로 봐야 합니다.

프로덕션에서는 촘촘한 루프로 요청하지 말고 백오프를 적용해 결과 엔드포인트를 폴링하세요. 이 엔드포인트에서 문서화한 최종 상태인 completed, failed, cancelled, timeout, deleted가 나오면 폴링을 중단합니다.

KIE: `createTask`와 콜백 또는 작업 조회

KIE는 공용 작업 생성 엔드포인트를 사용합니다.

POST https://api.kie.ai/api/v1/jobs/createTask

Kling 3.0 모델 식별자는 kling-3.0/video이며, 인증에는 Bearer 토큰을 사용합니다. 간결한 싱글샷 페이로드는 다음과 같습니다.

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://example.com/webhooks/kie",
  "input": {
    "prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "sound": false,
    "multi_shots": false
  }
}

KIE 문서는 3~15초 영상, 16:9·9:16·1:1 출력 화면비, 멀티샷 모드에서 최대 5개 샷을 안내합니다. 멀티샷 항목마다 1~12초를 지정할 수 있습니다. 이미지 엘리먼트는 JPG 또는 PNG URL 2~4개를 사용하며 이미지당 문서상 최대 크기는 10 MB입니다. 비디오 엘리먼트는 최대 50 MB의 MP4 또는 MOV URL 1개를 사용합니다.

콜백은 선택 사항이지만 KIE는 프로덕션 환경에서 사용하기를 권장합니다. 웹훅은 가능한 경우 서명을 검증하고, 빠르게 확인 응답을 보낸 뒤 작업 결과를 큐에 넣어야 합니다. 콜백을 놓쳤을 때를 대비해 작업 조회 폴링도 복구 경로로 유지하세요.

KIE는 흔한 실패에 대해 별도의 응답 코드를 문서화합니다. 잘못된 인증 정보는 401, 크레딧 부족은 402, 유효성 검증 오류는 422, 속도 제한은 429입니다. 코드와 메시지를 함께 기록하세요. 단순히 “Kling 실패”라고만 남겨서는 안전하게 재시도할 수 있는지 판단하기 어렵습니다.

fal: 모델 엔드포인트와 큐 클라이언트

fal은 모델별 엔드포인트 ID로 Kling 3.0을 제공합니다. Standard 텍스트-투-비디오의 문서화된 ID는 다음과 같습니다.

fal-ai/kling-video/v3/standard/text-to-video

Raw API는 Authorization: Key $FAL_KEY 헤더를 사용합니다. Python과 JavaScript 예제는 fal의 큐 인식 클라이언트를 사용하며, 직접 폴링 루프를 작성하는 것보다 대체로 간편합니다.

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const result = await fal.subscribe(
  "fal-ai/kling-video/v3/standard/text-to-video",
  {
    input: {
      prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
      duration: 5,
      aspect_ratio: "16:9",
      generate_audio: false,
      negative_prompt: "blur, distort, low quality",
      cfg_scale: 0.5
    },
    logs: true
  }
);

console.log(result.data.video.url);

fal 문서는 3~15초 길이, 텍스트-투-비디오용 화면비 3종, 기본값 0.5이며 범위가 0~1인 cfg_scale을 안내합니다. Standard 스키마에서 prompt와 multi_prompt는 대체 관계입니다. 둘 다가 아니라 하나만 제공해야 합니다. 문서상 generate_audio의 기본값은 true이므로, 예산이나 후반 작업 파이프라인이 무음 출력을 전제로 한다면 명시적으로 설정하세요.

fal은 이미지-투-비디오와 모션 컨트롤용 ID도 별도로 제공합니다. 현재 모델 레퍼런스를 확인하지 않은 채 문자열의 text-to-video만 바꿔 해당 ID를 추측하지 마세요.

할당량, 대기열 시간, 크레딧을 안전하게 관리하는 법

공식 플랫폼, WaveSpeedAI, KIE, fal에 공통으로 적용되는 단일 공개 Kling 할당량은 없습니다. 동시성, 속도 제한, 크레딧 잔액, 실패 작업 과금, 결과 보존 기간은 선택한 경로에 따라 달라집니다. 이를 KLING_LIMIT 같은 상수가 아니라 공급사별 설정으로 저장하세요.

실제 사용자가 운영상 위험을 일반적인 재시도 권고보다 더 정확하게 요약했습니다.

“Kling은 실제 큐 대기 시간이 있는 세대별 과금 방식입니다. 가장 먼저 연결할 것은 비용·동시성 제한입니다. 그렇지 않으면 잘못된 프레임에서 재시도하는 에이전트가 밤새 크레딧을 조용히 태울 수 있습니다.” — @ukrroot on X

예산과 동시성 보호 장치

에이전트나 배치 워커가 Kling을 호출하도록 허용하기 전에 다음 제어 장치를 구현하세요.

진행 중인 작업 수 제한: 프롬프트마다 작업을 하나씩 시작하지 말고, 공급사별 상한을 설정합니다.
작업별 예산: 제출 전 길이, 티어, 오디오, 출력 수를 기준으로 비용을 추정합니다.
재시도 예산: 전송 실패만 선별적으로 재시도하고, 유효성 검증·인증·크레딧 부족 오류는 재시도하지 않습니다.
작업 원장: 후속 요청 전에 공급사 작업 ID를 기록해 워커가 재시작돼도 중복 생성을 막습니다.
최종 상태 정책: 공급사가 안전하게 재제출할 수 있다고 명시하지 않는 한, 실패·취소·타임아웃·삭제 작업은 종료 처리합니다.
크레딧 알림: 잔액 또는 예상 지출이 임계값을 넘으면 큐를 중지합니다.
키와 출력물 보호: 키는 서버에만 보관하고, 노출된 키는 즉시 교체하며, 완성된 영상은 내구성 있는 스토리지로 복사합니다.

5초 Standard 테스트는 15초 Pro 또는 오디오 활성화 작업보다 저렴할 수 있지만, “저렴하다”는 기준 자체가 공급사마다 다릅니다. 기본 티어를 결정하기 전에 실시간 모델 페이지를 확인하세요.

프로덕션 전 반드시 측정할 항목

모든 요청에 대해 다음 필드를 추적하세요.

지표	중요한 이유
큐 대기 시간	공급사 적체와 모델 추론 시간을 구분할 수 있음
추론 시간	현실적인 클라이언트 타임아웃 설정에 도움
최종 상태	실패율과 취소율을 보여 줌
HTTP 상태	`401`, `402`, `422`, `429`, 서버 오류를 구분
실질 비용	재시도, 오디오, 중단된 작업까지 포함
출력 보존 기간	언제 영상을 자체 스토리지에 복사해야 하는지 결정
진행 중인 작업 수	공급사 한도에 가까워지는지 확인

지연 시간과 할당량은 엔드포인트별로 다뤄야 합니다. 공개 자료에는 공급사를 아우르는 단일 SLA가 없습니다.

Kling API FAQ

Kling에는 공식 API가 있나요?

있습니다. Kling은 공식 Open Platform 개발자 문서 영역을 운영합니다. 공식 경로와 서드파티 게이트웨이는 별도 서비스이므로, 최신 인증 정보, 할당량, 가격은 Kling Open Platform 문서에서 확인하세요.

모든 곳에서 쓸 수 있는 Kling API 엔드포인트가 있나요?

없습니다. 공식 플랫폼, WaveSpeedAI, KIE, fal은 엔드포인트 경로, 모델 ID, 인증 헤더, 응답 형식이 모두 다릅니다. kling-3.0이 어디서나 유효하다고 가정하지 말고 공급사 어댑터를 구축하세요.

폴링과 웹훅 중 무엇을 써야 하나요?

공급사가 지원한다면 프로덕션에서는 콜백 또는 웹훅을 사용하되, 로컬 테스트와 콜백 누락 복구를 위해 폴링도 유지하세요. 지수 백오프, 총 대기 시간 제한, 멱등성 처리를 더해 늦게 도착한 콜백이 중복 레코드를 만들지 않도록 해야 합니다.

지원되는 길이와 화면비는 어떻게 되나요?

현재 여러 Kling 3.0 애그리게이터 문서는 3~15초 클립과 16:9, 9:16, 1:1 화면비를 안내합니다. 개별 엔드포인트는 다를 수 있으므로, 이를 퍼스트파티 공통 규격으로 보지 말고 선택한 모델 페이지에서 검증하세요.

오디오를 켜면 비용이 달라지나요?

대체로 달라질 수 있습니다. WaveSpeedAI는 Kling 3.0 Standard 엔드포인트에 사운드 1.5배 배수를 문서화하고 있으며, fal과 KIE는 오디오 또는 사운드를 요청 파라미터로 제공합니다. 선택한 엔드포인트의 최신 과금 페이지를 확인하고 플래그를 명시적으로 설정하세요.

재시도했는데 왜 추가 비용이 발생했나요?

첫 작업이 아직 큐에 있는 상태에서도 재시도는 두 번째 생성을 만들 수 있습니다. 작업 ID를 저장하고, 동시성 제한을 적용하며, 일시적 오류만 재시도하세요. 상태가 불분명한 요청을 다시 제출하기 전에는 공급사 과금 내역도 대조해야 합니다.

첫 프로덕션 수준의 테스트에서는 5초 무음 Standard 작업 하나만 실행하고 전체 생명주기를 기록하세요. 그 뒤 중복 워커 처리가 정상적으로 동작하는 것을 확인한 후에만 Pro, 오디오, 멀티샷, 동시성을 추가하는 편이 안전합니다.

SDK보다 먼저 접근 경로부터 정하자

공식 Kling API를 쓰는 흐름

애그리게이터가 더 잘 맞는 경우

공통 인터페이스로 묶을 수 있는 Kling API 계약

공급사가 달라도 비교적 통하는 파라미터

공급사마다 절대 섞으면 안 되는 값

실제 요청 형식 3가지

WaveSpeedAI: 예측 ID를 받고 결과를 폴링하는 방식

KIE: `createTask`와 콜백 또는 작업 조회

fal: 모델 엔드포인트와 큐 클라이언트

할당량, 대기열 시간, 크레딧을 안전하게 관리하는 법

예산과 동시성 보호 장치

프로덕션 전 반드시 측정할 항목

Kling API FAQ

Kling에는 공식 API가 있나요?

모든 곳에서 쓸 수 있는 Kling API 엔드포인트가 있나요?

폴링과 웹훅 중 무엇을 써야 하나요?

지원되는 길이와 화면비는 어떻게 되나요?

오디오를 켜면 비용이 달라지나요?

재시도했는데 왜 추가 비용이 발생했나요?

Kling v3 Omni

Kling 3.0

Kling 3.0 Turbo

Seedance 2.0 Mini

Seedance 2.0

Kling API 연동 가이드: 공식 API와 애그리게이터 비교 (2026)

SDK보다 먼저 접근 경로부터 정하자

공식 Kling API를 쓰는 흐름

애그리게이터가 더 잘 맞는 경우

공통 인터페이스로 묶을 수 있는 Kling API 계약

공급사가 달라도 비교적 통하는 파라미터

공급사마다 절대 섞으면 안 되는 값

실제 요청 형식 3가지

WaveSpeedAI: 예측 ID를 받고 결과를 폴링하는 방식

KIE: createTask와 콜백 또는 작업 조회

fal: 모델 엔드포인트와 큐 클라이언트

할당량, 대기열 시간, 크레딧을 안전하게 관리하는 법

예산과 동시성 보호 장치

프로덕션 전 반드시 측정할 항목

Kling API FAQ

Kling에는 공식 API가 있나요?

모든 곳에서 쓸 수 있는 Kling API 엔드포인트가 있나요?

폴링과 웹훅 중 무엇을 써야 하나요?

지원되는 길이와 화면비는 어떻게 되나요?

오디오를 켜면 비용이 달라지나요?

재시도했는데 왜 추가 비용이 발생했나요?

KIE: `createTask`와 콜백 또는 작업 조회