Kling 2.5 Turbo API 사용법? 5분 만에 첫 영상 완성하기

TL;DR

• Kling 2.5 Turbo는 콰이쇼우 클링의 고속 버전 영상 모델이며, HiAPI에는 텍스트 투 비디오와 이미지 투 비디오 두 엔드포인트가 있습니다. 모델 페이지를 열면 바로 온라인에서 체험할 수 있고, 신규 사용자 가입 시 200 크레딧을 드립니다.
• 두 엔드포인트 모두 초당 $0.06: 5초 $0.30, 10초 $0.60.
• 호출 방식: POST /v1/tasks로 제출하고 taskId로 결과를 조회하며, 완성된 영상은 output[0].url에 있습니다.

Kling 2.5 Turbo로 할 수 있는 것

• 5초 또는 10초, 약 1080p: 해상도는 화면 비율을 따르며, 16:9는 1920×1080으로 출력되므로 별도로 설정할 필요가 없습니다.
• 텍스트 투 비디오는 사운드 포함: 모든 영상에 오디오 트랙이 있으며 끄는 옵션은 없습니다.
• 이미지 투 비디오는 끝 프레임 지원: 시작 프레임이 시작을, 끝 프레임이 끝을 정하고 모델이 중간 과정을 채웁니다.
• 이미지 투 비디오는 6가지 화면 비율: 가로·세로·정사각형 외에 4:3, 3:4, 21:9 와이드스크린도 있습니다.

Vertical cinematic shot of a ceramic artist in a sunlit studio. Her hands shape a small terracotta bowl on a spinning pottery wheel. The wet clay gradually rises as the wheel turns, a little water glints on the surface. The camera gently tracks upward from the bowl to her focused face. Warm morning light, linen apron, natural movement, one continuous shot, no text or logos.

이 프롬프트로 생성하기 →(10초, 9:16 선택)

kling-2.5-turbo/text-to-video, 9:16, 1080×1920, 10초, 오디오 트랙 포함, $0.60.

두 엔드포인트 선택법

모델 ID	입력	화면 비율	사운드	적합한 용도
kling-2.5-turbo/text-to-video	프롬프트	16:9, 9:16, 1:1	오디오 트랙 포함	소재 없이 텍스트에서 시작
kling-2.5-turbo/image-to-video	시작 프레임 필수, 끝 프레임 선택	6가지, 끝 프레임 추가 시 3가지	오디오 트랙 없음	상품 이미지, 사진, 일러스트를 움직이게

두 엔드포인트 가격은 동일하며 모두 초당 $0.06입니다.

두 가지 시작 방법

브라우저에서 체험하기 (3단계)

1. 텍스트 투 비디오 또는 이미지 투 비디오 모델 페이지를 열고 로그인합니다.
2. 프롬프트를 작성합니다. 이미지 투 비디오는 먼저 시작 프레임을 업로드하고, 필요하면 끝 프레임도 업로드합니다.
3. 5초와 화면 비율을 선택하고 실행을 누릅니다.

API로 호출하기 (3단계)

1. 콘솔의 API Key 페이지에서 키를 생성하고 환경 변수 HIAPI_KEY에 넣습니다.
2. POST https://api.hiapi.ai/v1/tasks로 제출하고 data.taskId를 받습니다.
3. GET /v1/tasks/{taskId}로 status가 success인지 확인하고 output[0].url을 다운로드합니다.

curl: 첫 영상

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/text-to-video",
    "input": {
      "prompt": "Hands pour glossy caramel over a stack of pancakes, steam rises, camera slowly pushes in, warm kitchen light",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

5초, 16:9, $0.30. 이미지 투 비디오는 model을 kling-2.5-turbo/image-to-video로 바꾸고 "image_urls": ["https://你的图床/frame.jpg"]를 추가합니다.

Python: 제출, 폴링, 다운로드

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, timeout_s=900, **inp):
    # 重试同一个任务时带同一个 Idempotency-Key，避免重复扣费
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# 首帧 + 尾帧：红车从左边开到右边，变成蓝车（5 秒，$0.30）
url = generate(
    "kling-2.5-turbo/image-to-video",
    prompt="A toy car moves smoothly from the left to the right and changes from red to blue. "
           "Keep the simple light grey background and beige ground. Continuous static camera shot.",
    image_urls=["https://你的图床/first.png", "https://你的图床/last.png"],
    duration=5, aspect_ratio="9:16",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

시작 프레임 + 끝 프레임: 원하는 장면에서 멈추게 하기

image_urls에 이미지 두 장을 전달합니다. 첫 번째가 시작 프레임, 두 번째가 끝 프레임입니다. 아래 예시는 시작 프레임이 왼쪽의 빨간 차, 끝 프레임이 오른쪽의 파란 차입니다:

시작 프레임	끝 프레임

A toy car moves smoothly from the left to the right and changes from red to blue. Keep the simple light grey background and beige ground. Continuous static camera shot.

이 프롬프트로 생성하기 →(시작 프레임과 끝 프레임을 업로드하고 5초, 9:16 선택)

kling-2.5-turbo/image-to-video, 9:16, 1080×1920, 5초, 시작 프레임 + 끝 프레임, $0.30.

차가 오른쪽으로 이동하는 동안 색이 빨강에서 보라를 거쳐 파랑으로 바뀌고, 마지막에는 끝 프레임 위치에 멈추며 배경은 처음부터 끝까지 그대로입니다. 두 이미지에서 바뀌어야 할 부분 외에는 모두 같으면 결과가 가장 안정적입니다. 끝 프레임을 추가하면 화면 비율은 16:9, 9:16, 1:1만 선택할 수 있습니다.

파라미터 표

필드	필수	값	설명
prompt	예	1–2500자	동작과 카메라를 작성, 이미지 투 비디오는 화면 묘사 불필요
duration	아니오	5(기본) / 10	초 단위 과금
aspect_ratio	아니오	텍스트: 16:9(기본) 9:16 1:1; 이미지에는 4:3 3:4 21:9 추가	끝 프레임 추가 시 16:9 9:16 1:1만
image_urls	이미지 투 비디오 필수	1–2장, jpeg/png/webp, 장당 ≤10MB	1번째는 시작 프레임, 2번째는 끝 프레임; 텍스트 투 비디오는 이 필드를 받지 않음
negative_prompt	아니오	텍스트 ≤2500, 이미지 ≤2496자	나타나지 않길 원하는 내용
cfg_scale	아니오	0–1, 기본 0.5	클수록 프롬프트에 더 충실

resolution, seed, 사운드 스위치는 없습니다.

마주치게 될 오류

제출 시 파라미터가 잘못되면 API가 바로 400을 반환하고, 작업도 생성하지 않으며 과금도 하지 않습니다:

• duration: value must be one of 5, 10: 길이는 5와 10만 가능합니다.
• aspect_ratio: value must be one of '16:9', '9:16', '1:1': 텍스트 투 비디오에 다른 화면 비율을 전달했거나, 이미지 투 비디오에 끝 프레임을 추가하고 4:3, 3:4, 21:9를 선택했습니다.
• image_urls: maxItems: got 3, want 2: 최대 두 장, 시작 프레임과 끝 프레임입니다.
• image_urls: missing required field "image_urls": 이미지 투 비디오에 시작 프레임을 전달하지 않았습니다.
• cfg_scale: maximum: got 5, want 1: cfg_scale은 0에서 1이며, 다른 모델에서 흔한 1–20이 아닙니다.
• additional properties 'seed', 'sound' not allowed: 이 두 필드는 존재하지 않습니다.

출시 전 유의 사항

• 폴링 대신 콜백 사용: 요청 최상위(input과 같은 레벨)에 "callback": {"url": "https://你的域名/hiapi/callback"}를 추가하고 taskId로 중복을 제거합니다.
• 즉시 저장: output[0].url은 약 7일 후 만료되므로 받자마자 자체 스토리지에 저장합니다.
• duration과 aspect_ratio 명시: 작성하지 않으면 5초, 16:9가 되므로 세로형 요구 사항에서 빠뜨리기 쉽습니다.
• 재시도 시 멱등 키 사용: 요청 헤더에 Idempotency-Key를 추가하면 같은 키로 한 번만 작업이 생성됩니다.

자주 묻는 질문

텍스트 투 비디오의 사운드를 끌 수 있나요?

아니요, 사운드 스위치가 없습니다. 사운드가 필요 없으면 편집 시 오디오 트랙을 제거하거나, 처음부터 오디오 트랙이 없는 이미지 투 비디오를 사용하세요.

이미지 투 비디오의 시작 프레임 비율과 화면 비율이 다르면 어떻게 되나요?

시작 프레임은 선택한 화면 비율에 맞춰 가운데를 기준으로 잘립니다. 16:9 이미지에서 9:16을 선택하면 가운데 세로 띠가 유지되므로 피사체를 가운데에 두는 것이 가장 안정적입니다.

4K로 출력할 수 있나요?

아니요. 출력은 약 1080p이며 화면 비율에 따라 달라지고, 가장 넓은 것은 21:9의 2200×940입니다.

Kling 3.0 Turbo와 어떻게 선택하나요?

5초나 10초로 충분하고 최저 가격을 원하면 Kling 2.5 Turbo를 선택하세요. 3–15초를 초 단위로 선택하거나 720p와 1080p 중에서 고르고 싶다면 Kling 2.5 Turbo와 3.0 Turbo 비교를 참고하세요.

가격 상세는 Kling 2.5 Turbo API 가격에서, 더 많은 활용 사례는 Kling 2.5 Turbo 프롬프트 모음에서 확인하세요. 먼저 결과를 보고 싶다면 위의 도예 프롬프트를 복사해서 모델 페이지에서 첫 영상을 생성해 보세요.