Python에서의 Kling AI 이미지-투-비디오 API

HiAPI의 비동기 작업 엔드포인트를 통해 Python에서 Kling AI 이미지-투-비디오 API를 사용하세요. 아래 빠른 시작은 현재 호출 가능한 kling-3.0-omni/image-to-video 모델 ID를 사용하여 작업이 종료 상태에 도달할 때까지 폴링하고 생성된 MP4를 다운로드합니다.

정확한 필드를 확인하려면 Kling 3.0 Omni 이미지-투-비디오 API 문서를 여세요. 현재 Omni 모델 페이지에서 모델과 Playground를 확인하고, 프로덕션 실행 전에 실시간 Kling API 가격을 확인하세요.

빠른 시작: Python에서 Kling 이미지-투-비디오 실행하기

python -m pip install requests로 requests를 설치하고, 환경에 HIAPI_API_KEY를 설정하며, IMAGE_URL을 공개 JPEG, PNG 또는 WebP URL로 바꾸세요. 전체 스크립트는 첫 번째 복사 가능한 코드 블록입니다:

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

생성 요청은 비디오 생성 완료를 기다리지 않고 taskId를 반환합니다. 스크립트는 GET /v1/tasks/{taskId}를 폴링하여 success 또는 fail에서 중지하고, 결과 URL이 만료되므로 첫 번째 출력을 가능한 한 빨리 다운로드합니다.

Kling Omni 모델을 열고 이 payload를 사용해 보세요.

현재 사용 가능한 Kling 이미지-투-비디오 모델 선택하기

모델 ID	적합한 사용 사례	입력 및 출력 규약
kling-3.0-omni/image-to-video	첫 프레임/마지막 프레임 제어, 선택적 네이티브 사운드 또는 4K가 필요할 때	공개 이미지 URL 1~2개; 3-15초; 720p, 1080p 또는 4K
kling-3.0-turbo/image-to-video	시작 프레임 하나만 필요하고 720p/1080p의 더 간단한 schema로 충분할 때	공개 이미지 URL 정확히 1개; prompt 필수; 3-15초; 720p 또는 1080p

Omni의 전체 필드 참조는 Omni I2V 문서를 참고하세요. Turbo에는 별도의 Turbo I2V schema 참조가 있습니다. 둘 다 동일한 /v1/tasks 생성 및 폴링 워크플로를 사용하므로, 실행기를 하나 유지하고 model과 input만 바꿀 수 있습니다.

모델 요구 사항에 맞는 요청 본문

첫 프레임과 마지막 프레임이 있는 Omni

첫 프레임을 나타내는 URL 하나를 보내거나, [first, last] 순서로 정렬된 URL 두 개를 보내세요:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

Omni는 하나 또는 두 개의 image_urls를 허용합니다. prompt는 선택 사항이고, duration은 3에서 15 사이의 정수이며, resolution은 720p, 1080p 또는 4K이고, sound는 선택 사항입니다.

시작 프레임 하나가 있는 Turbo

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

Turbo는 prompt 제공을 요구하며 image_urls에 정확히 하나의 항목이 있어야 합니다. Omni 전용 필드(예: sound)를 보내지 말고 텍스트-투-비디오 필드(예: aspect_ratio)도 추가하지 마세요. 화면은 소스 이미지에 의해 결정됩니다.

Kling AI 가격: 실시간 등급을 사용하고 가격을 그대로 옮기지 마세요

HiAPI의 Kling AI 가격은 사용량 기준으로 청구됩니다. 현재 두 이미지-투-비디오 모델 모두 생성된 초 단위로 청구되며, 구체적인 요율은 모델과 해상도에 따라 결정됩니다. Omni는 오디오 활성화 여부에 따라 다른 등급도 있습니다. 더 긴 클립, 더 높은 해상도 또는 네이티브 오디오는 모두 작업 비용을 변경합니다.

요율은 변경될 수 있으므로 이 가이드는 달러 가격표를 고정하지 않습니다. 예산을 책정하거나 대량 작업을 제출하기 전에 즉시 실시간 모델 가격표를 확인하세요.

Kling AI는 무료인가요?

아니요: HiAPI에서 Kling 이미지-투-비디오 API 생성은 무제한 무료 API가 아닙니다. 성공한 작업은 선택한 모델, 길이, 해상도 및 오디오 설정의 실시간 요율에 따라 잔액을 소모합니다. 계정 프로모션이나 신규 사용자 보상은 변경되거나 조건이 붙을 수 있으므로 보장된 Kling 무료 등급으로 간주하지 마세요. 작업을 제출하기 전에 계정에서 현재 혜택과 잔액을 확인하세요.

작업 실패나 중복을 방지하는 프로덕션 점검 사항

1. 직접 다운로드 가능한 HTTPS 이미지 URL을 사용하세요. localhost, 로그인이 필요한 페이지, HTML 공유 페이지 및 만료된 서명 URL은 작업 생성 후 실패할 수 있습니다.
2. worker를 재시도하기 전에 taskId를 저장하세요. 생성 호출을 재시도하면 두 번째 작업이 생성되어 청구될 수 있습니다.
3. success와 fail을 종료 상태로 간주하세요. 프로덕션에서는 최상위 callback.url을 사용하고 폴링은 대사(reconciliation)용 안전망으로 유지하세요.
4. output[].url을 즉시 다운로드하고 장기 보존할 결과를 제어 가능한 저장소에 복사하세요.
5. 전송 전에 선택한 모델의 schema를 검증하세요. 엄격한 모델 규약은 알 수 없는 필드를 거부합니다.

일반적인 오류

• HTTP 400: 요청이 schema와 일치하지 않습니다. 지적된 필드, 열거형 값, 배열 길이 및 JSON 타입을 확인하세요.
• HTTP 401: bearer key가 없거나 유효하지 않거나, 선택한 모델에 사용할 수 없습니다.
• 작업이 fail로 전환됨: 생성 요청은 검증을 통과했지만 렌더러가 입력을 가져오거나 생성을 완료할 수 없습니다. taskId와 반환된 오류를 생성 응답과 별도로 기록하세요.
• 출력 URL 만료: 렌더링은 성공했을 수 있지만 임시 가져오기 URL을 제때 다운로드하지 않았습니다.

자주 묻는 질문

Python에서 어떤 Kling 이미지-투-비디오 모델을 사용해야 하나요?

1~2개 프레임 제어, 선택적 네이티브 사운드 또는 4K가 필요하면 kling-3.0-omni/image-to-video를 사용하세요. 시작 프레임 하나와 720p/1080p 출력으로 충분하면 kling-3.0-turbo/image-to-video를 사용하세요. Python의 생성, 폴링 및 다운로드 코드는 동일하게 유지됩니다.

현재 Kling AI 이미지-투-비디오 모델 ID는 무엇인가요?

이 문서에서 다루는 현재 호출 가능한 ID는 kling-3.0-omni/image-to-video와 kling-3.0-turbo/image-to-video입니다. POST /v1/tasks의 최상위 model 필드에 둘 중 하나를 보내면 됩니다.

Kling 이미지-투-비디오는 몇 장의 이미지를 받을 수 있나요?

Omni는 첫 프레임으로 사용할 이미지 하나 또는 [first, last] 순서의 이미지 두 개를 받습니다. Turbo는 시작 프레임 이미지 정확히 하나를 받습니다.

Kling AI API 비용은 얼마인가요?

생성된 초 단위로 청구됩니다. 정확한 실시간 요율은 모델과 해상도에 따라 다르며, Omni는 오디오 설정에도 따라 달라집니다. 이 가이드의 고정 가격을 그대로 옮기지 말고 실시간 가격 페이지를 사용하세요.

API를 통한 Kling AI 사용은 무료인가요?

무제한 Kling API 무료 등급을 보장하지 않습니다. 생성은 실시간 작업 요율에 따라 계정 잔액을 소모합니다. 고정된 무료 할당량을 가정하지 말고 계정에 현재 조건이 붙은 starter 혜택이 있는지 확인하세요.

생성 요청이 성공했는데 작업이 실패하는 이유는 무엇인가요?

JSON이 초기 검증을 통과했지만 렌더러가 이미지를 가져오거나 생성을 완료하지 못할 수 있습니다. 이미지가 공개되어 있고 만료되지 않았는지 확인한 후 저장된 taskId로 종료 상태 오류를 확인하세요.

생성된 비디오는 어떻게 가져오나요?

생성 응답에서 data.taskId를 읽으세요. 로컬 스크립트는 GET /v1/tasks/{taskId}를 폴링할 수 있고, 프로덕션 환경에서는 callback.url을 사용할 수 있습니다. success일 때 data.output[0].url이 만료되기 전에 다운로드하세요.

다음으로 전체 Kling Omni API 참고 자료를 읽고, 테스트 요청을 준비할 때 현재 모델 페이지를 여세요.