Kling 3.0 API 가이드: 마이그레이션, Motion Control, 코드 예제

Kling 2.6에서 Kling 3.0으로 옮길 때 모델 문자열 하나만 바꾸는 방식은 안전하지 않습니다. Kling 3.0은 정식 제공 중이지만 V3, Turbo, Omni, Motion Control은 저마다 지원 기능과 요청 스키마가 다릅니다. 먼저 필요한 라우트를 정한 뒤 오디오, 멀티샷, 레퍼런스 제어를 하나씩 추가하는 편이 가장 안전합니다.

코드보다 먼저 고를 것: 사용할 엔드포인트

Kling의 공식 VIDEO 3.0 가이드에 따르면 3.0은 VIDEO 2.6과 VIDEO O1의 후속 모델군입니다. VIDEO 2.6은 VIDEO 3.0으로, VIDEO O1은 VIDEO 3.0 Omni로 이어집니다. 개발자 API는 모델별 작업을 분리해 제공하므로, ‘Kling 3.0 API’는 하나의 범용 요청 본문이 아니라 여러 접근 경로를 묶는 이름에 가깝습니다.

통합 과정에서 가장 흔한 실수는 제공업체의 편의용 스키마와 Kling의 직접 스키마를 혼동하는 것입니다. Krea의 호스팅 요청은 동작하는 예시일 뿐, 동일한 URL이나 필드가 공식 Kling 개발자 문서에도 적용된다는 뜻은 아닙니다.

라우트 전반을 살펴보고 싶다면 Kling API 통합 가이드를 참고하세요. 이 글에서는 Kling 3.0 마이그레이션과 엔드포인트 동작 방식에 집중합니다.

Kling 2.6에서 3.0으로 바뀌는 핵심

Kling의 공식 모델 가이드는 이번 업그레이드의 핵심을 단순한 해상도 프리셋 상향이 아닌 제어력, 장면 연속성, 시청각 연출로 설명합니다. 아래 표는 Kling이 해당 모델군에 부여한 기능을 기준으로 정리했습니다.

실무적으로는 짧은 프롬프트 하나를 중심으로 설계한 2.6 통합이, 3.0에서는 연출된 시퀀스로 확장될 수 있다는 차이가 큽니다. Kling 가이드는 카메라 움직임 중에도 캐릭터, 오브젝트, 장면 디테일을 더 잘 유지한다고 설명하지만, 독립적인 일관성 벤치마크를 공개하지는 않았습니다. 이 주장은 애플리케이션에서 직접 검증할 수 있는 결과와 구분해 다루는 것이 좋습니다.

가장 작은 비동기 Krea 호스팅 통합 만들기

영상 생성은 비동기 작업입니다. 애플리케이션은 작업을 제출하고, 태스크 식별자를 보관한 뒤, 폴링 또는 콜백으로 상태를 확인해 완료 결과를 저장해야 합니다. 모델 렌더링이 끝날 때까지 원래 HTTP 요청을 열린 상태로 유지하지 마세요.

아래 예제는 공개된 Kling 3.0 API 가이드에서 요청 및 작업 필드를 확인할 수 있는 Krea의 Kling 3.0 엔드포인트를 사용합니다. 사용할 공식 Kling 스키마를 확인한 뒤에만 제공업체별 URL과 필드명을 교체하세요.

생성 작업 제출하기

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

Krea 문서의 응답에는 job_id와 scheduled 같은 초기 상태가 포함됩니다. 제공업체 예제는 상태 확인에 별도의 작업 조회 엔드포인트를 사용합니다. 폴링을 시작하기 전에 데이터베이스에 작업 ID와 자체 주문 ID를 함께 저장해야 합니다.

타임아웃을 두고 폴링한 뒤 결과 저장하기

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

Krea의 예제에서는 51초와 2분 3초가 걸렸습니다. 따라서 Kling 생성 시간을 고정값으로 약속하기보다 큐 상황을 고려한 타임아웃을 설정해야 합니다.

프로덕션에서는 웹훅으로 반복 폴링을 줄일 수 있습니다. 작업 ID가 시스템에서 생성한 작업과 일치하는지 검증하고, 핸들러는 멱등적으로 구현하세요. 서명되지 않은 콜백만으로 신원을 증명했다고 판단해서도 안 됩니다.

3.0 제어 기능은 하나씩 추가하자

파라미터 이름은 직접 Kling API와 호스팅 제공업체마다 달라질 수 있습니다. 제공업체별 JSON이 애플리케이션 전체로 퍼지지 않도록 작은 호환성 계층을 두는 편이 좋습니다.

공식 가이드는 네이티브 오디오, 요소 레퍼런스, 멀티샷 내러티브, 5개 지정 대화 언어를 지원한다고 설명합니다. 다만 선택한 API 엔드포인트가 이 모델군 전체 기능 중 일부만 노출할 수 있습니다.

멀티샷 커스텀 페이로드 예시

Krea의 문서화된 스키마는 시간 단위의 multi_prompt 비트를 사용합니다. 호스팅 통합에서 참고할 만한 패턴입니다.

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

최상위 길이가 각 비트 길이의 합과 같은지 검증하세요. Krea는 3개 비트, 12초 테스트에서 12.04초 결과를 보고했으므로, 파일 길이가 밀리초 단위까지 수학적으로 정확할 것이라 가정해서는 안 됩니다.

Krea에서는 각 비트가 512자로 제한되고, 전체 연출 시퀀스는 최대 15초입니다. 긴 장면 설명문 대신 피사체, 변화, 카메라를 담은 샷 지시문으로 각 비트를 작성하세요. 직접 Kling 라우트가 공식 샷 문법을 쓴다면 같은 타임라인 모델은 유지하되, 어댑터 경계에서 페이로드를 변환하면 됩니다.

오디오와 언어 관련 제약

공식 가이드는 중국어, 영어, 일본어, 한국어, 스페인어를 지원 대화 언어로 나열하며 방언, 억양, 캐릭터별 대사, 혼합 언어 장면도 설명합니다. 지원하지 않는 대화 입력은 영어로 번역된다고 명시하므로, 다국어 애플리케이션이라면 모든 원문 언어가 그대로 유지된다고 가정하면 안 됩니다.

오디오는 비용 측면에서도 판단이 필요합니다. Krea의 공개 요금은 오디오 미포함 std가 초당 $0.1764, 오디오 포함 시 $0.2646입니다. pro는 오디오 미포함 $0.2352, 포함 시 $0.3528입니다. 4K 표기 요금은 오디오 유무와 관계없이 초당 $0.441입니다. 이는 Krea 요금이며, 범용 Kling API 요금표가 아닙니다.

합리적인 반복 작업 방식은 먼저 무음 시안을 렌더링하고, 최종 std 또는 pro 후보에만 오디오를 활성화하는 것입니다.

프로덕션 운영의 경계: 비용, 속도, 실패 처리

Kling의 공식 소비자 가이드는 VIDEO 3.0의 크레딧을 네이티브 오디오 미포함 기준 720p 초당 6크레딧, 1080p 초당 8크레딧으로 안내합니다. 오디오 포함 시에는 720p 초당 9크레딧, 1080p 초당 12크레딧이며, Voice Control은 초당 2크레딧이 추가됩니다. 이 수치는 해당 가이드 내 상대 비용을 이해하는 데 유용하지만, 실시간 개발자 가격 페이지를 확인하지 않고 개발자 API의 달러 가격으로 환산해서는 안 됩니다.

선택 기준은 단순히 ‘가장 저렴한 모델이 무엇인가’가 아닙니다. 과금과 운영을 함께 고려해야 합니다.

실패는 유형별로 처리하세요.

1. 일시적인 제공업체 오류는 상한을 둔 지수 백오프로 재시도합니다.
2. 잘못된 파라미터는 어댑터에서 페이로드를 수정하기 전까지 재시도하지 않습니다.
3. 네트워크 타임아웃이 눈치채지 못한 중복 작업을 만들지 않도록 클라이언트 측 멱등성 키 또는 주문 ID를 유지합니다.
4. 배치 생성에는 엄격한 달러 또는 크레딧 상한을 둡니다.
5. 제공업체의 임시 URL이 만료되기 전에 결과를 다운로드하거나 영구 스토리지로 복사합니다.
6. 모델 변형, 길이, 오디오 설정, 해상도 티어, 제공업체를 함께 기록합니다. 비용 집계에서 ‘Kling 3.0’만으로는 충분하지 않습니다.

Kling 2.6 → 3.0 마이그레이션 체크리스트

1. 현재 2.6 호출을 목록화합니다. 모델 ID, 이미지 입력, 시작/종료 프레임, 길이, 오디오, 콜백 동작을 기록합니다.
2. 3.0 모델군 라우트를 선택합니다. 프롬프트 중심 시네마틱 생성에는 V3, 더 빠른 경로에는 Turbo, O1 스타일 멀티모달 경로에는 Omni, 모션 레퍼런스 작업에는 Motion Control을 사용합니다.
3. 제공업체 어댑터를 만듭니다. 직접 Kling, Krea, 기타 호스팅 제공업체 스키마는 각각 별도 변환기 뒤에 둡니다.
4. 가장 작은 요청부터 마이그레이션합니다. 오디오나 멀티샷 제어를 넣기 전에 5초, 무음, 16:9 생성을 테스트합니다.
5. 테스트마다 제어 항목 하나만 추가합니다. 길이, 오디오, 샷 연출, 레퍼런스 순으로 검증합니다. 문제가 있는 필드를 더 쉽게 분리할 수 있습니다.
6. 종료 상태를 테스트합니다. 성공, 실패, 취소, 타임아웃, 중복 콜백, 만료된 출력 URL 상황을 모두 다룹니다.
7. 비용을 포함한 섀도 론칭을 진행합니다. 동일한 길이와 출력 티어에서 고정 프롬프트 세트를 2.6과 3.0으로 비교한 뒤, 품질 또는 제어력 향상이 새 라우트를 정당화하는지 판단합니다.

비즈니스 로직, 과금 제어, 결과 처리 방식을 바꾸지 않고 모델 ID만 되돌릴 수 있을 때 마이그레이션이 완료된 것입니다.

Kling 3.0 API FAQ

공식 Kling 3.0 API가 있나요?

있습니다. Kling의 공식 개발자 문서는 3.0 모델별 API 페이지를 제공하며, Kling의 공식 가이드는 VIDEO 3.0을 VIDEO 2.6의 후속 모델로 문서화합니다. 일부 페이지는 클라이언트 렌더링 방식이므로 정확한 엔드포인트 스키마는 실시간 개발자 콘솔에서 확인해야 합니다.

Motion Control은 Kling 3.0 파라미터인가요?

그렇다고 가정하면 안 됩니다. Motion Control은 Kling 생태계에서 자체 모델 페이지를 가진 특화 기능입니다. 검증되지 않은 motion_control 필드를 표준 텍스트-투-비디오 요청에 추가하지 말고, 선택한 제공업체가 문서화한 작업 및 입력 스키마를 사용하세요.

Kling VIDEO 3.0은 얼마나 긴 영상을 만들 수 있나요?

Kling의 공식 모델 가이드는 VIDEO 3.0이 3초부터 15초까지 유연한 출력을 지원한다고 설명합니다. 특정 호스팅 또는 Turbo 라우트는 더 좁은 제한을 둘 수 있으므로 선택한 엔드포인트에서 검증해야 합니다.

Kling 3.0은 네이티브 오디오를 지원하나요?

공식 VIDEO 3.0 가이드는 지원한다고 밝히며, 캐릭터별 대사, 다국어, 방언, 억양을 설명합니다. 오디오가 선택 사항인지와 과금 방식은 엔드포인트 또는 제공업체 스키마에 따라 달라집니다.

Kling 3.0 Omni는 일반 Kling 3.0과 같은 모델인가요?

아닙니다. Kling은 VIDEO 3.0을 2.6의 후속 모델로, VIDEO 3.0 Omni를 O1의 후속 모델로 포지셔닝합니다. 제공업체 페이지에서는 서로 다른 모델 ID와 레퍼런스 또는 음성 제어 기능으로 노출될 수 있습니다.

Kling 웹 구독으로 API 호출 비용을 낼 수 있나요?

실시간 계정 문서에서 달리 안내하기 전까지 소비자 구독과 개발자 API 과금은 별개로 취급하세요. API 라우트에는 일반적으로 별도의 개발자 계정, 키, 과금 설정이 필요합니다.

실용적인 마이그레이션 경계는 간단합니다. 2.6 통합의 작업 수명 주기는 유지하고, 모델별 어댑터만 교체한 뒤 새 3.0 제어 항목을 실제로 해당 기능을 제공하는 라우트에서 각각 검증하세요. 이렇게 하면 제출은 성공했지만 잘못된 변형, 오디오 모드, 과금 티어를 조용히 사용해 버리는 가장 비싼 유형의 실패를 피할 수 있습니다.