튜토리얼

Kling 2.5 Turbo 이미지-투-비디오 API 사용 방법 (curl + Python)

실행 가능한 첫 프레임 기반 영상 생성 실습: 작업 생성, 작업 폴링, MP4 다운로드 — 그리고 엄격한 입력 스키마 전체 목록.

Oct 21, 2026

TL;DR

kling-2.5-turbo/image-to-video는 첫 프레임 이미지 한 장을 5초 또는 10초짜리 영상 클립으로 변환합니다. 두 번째 이미지 URL을 전달하면 마지막 프레임을 고정할 수 있습니다. 이 모델은 HiAPI의 비동기 작업 API에서 실행됩니다 — 먼저 POST /v1/tasks로 작업을 생성한 다음, GET /v1/tasks/{taskId}를 폴링하여 생성된 MP4를 가져옵니다.
출력 비용은 초당 $0.06입니다: 5초 클립 $0.30, 10초 클립 $0.60. 과금은 완료된 출력 초수를 기준으로 계산되며, 입력이 유효하지 않아 실패한 작업은 출력을 생성하지 않으므로 요금이 부과되지 않습니다.
입력 스키마는 엄격하고 닫혀 있습니다. 필수: image_urls (배열, 1–2개 항목 — 복수형임에 주의), prompt, duration (5 또는 10만 가능). 선택: aspect_ratio, negative_prompt, cfg_scale. 단수형 image_url은 즉시 거부됩니다.
이 모델은 HiAPI에 출시되어 있습니다: 모델 페이지 열기에서 먼저 브라우저로 체험한 후 아래 API에 연결하세요.

무엇을 만들고 무엇을 준비해야 하는가

이 글을 다 읽으면 첫 프레임 → 영상 호출이 동작하게 됩니다: 이미지와 모션 프롬프트 제출, 작업 폴링, MP4 다운로드. 먼저 두 가지를 준비해야 합니다:

HiAPI 대시보드에서 API Key를 발급받으세요 — 모든 요청은 반드시 Authorization: Bearer sk-... 형식으로 전송해야 합니다. 아직 생성하지 않았다면 인증 문서를 참고하세요.
공개적으로 접근 가능한 첫 프레임 이미지 URL. 생성 호출은 입력의 구조만 검사하며, 이미지는 실제로 작업이 실행될 때 가져오므로 localhost나 비공개 URL은 생성 후 실패하는 작업을 만들게 됩니다(자세한 내용은 아래 참조).

이것은 이미지-투-비디오이므로 모델 id는 kling-2.5-turbo/image-to-video입니다. 프롬프트만으로 영상을 생성하고 싶다면 별도의 텍스트-투-비디오 엔드포인트가 있습니다.

최소 실행 예제 (curl)

작업을 생성합니다. 모델 이름은 최상위에 두고, 모델이 읽는 모든 내용은 input 안에 넣습니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/image-to-video",
    "input": {
      "prompt": "The perfume bottle rotates slowly on the marble stand, light glints across the glass, petals drift down, slow orbit",
      "image_urls": ["https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg"],
      "duration": 5,
      "aspect_ratio": "9:16"
    }
  }'

생성에 성공하면 영상이 아니라 작업 id가 반환됩니다:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5CW..." }, "message": "success" }

그런 다음 status가 종료 상태에 도달할 때까지 상세 엔드포인트를 폴링합니다:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CW... \
  -H "Authorization: Bearer sk-YOUR_KEY"

작업이 실행되는 동안에는 비종료 상태가 보이며, 완료 후 data.output[0].url에서 MP4 URL을 얻을 수 있습니다:

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "kling-2.5-turbo/image-to-video",
    "storage": "temp",
    "output": [{ "url": "https://temp.hiapi.ai/kling-i2v/tk-hiapi-01M5CW.mp4?expireAt=1761350400" }]
  },
  "message": "success"
}

해당 output[0].url은 임시 링크입니다 — 애플리케이션에서 직접 핫링크로 참조하지 말고 즉시 다운로드하세요(프로덕션 환경 주의사항 참조).

최소 실행 예제 (Python)

SDK가 필요 없습니다 — HiAPI 작업 API는 순수 HTTP 인터페이스이므로 표준 라이브러리만으로 충분합니다:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}


def create(image_url: str, prompt: str, duration: int = 5) -> str:
    payload = {
        "model": "kling-2.5-turbo/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # 1–2 items; 2nd = last frame
            "duration": duration,        # 5 or 10 only
        },
    }
    r = requests.post(API, json=payload, headers=HEADERS, timeout=60)
    body = r.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id


def wait(task_id: str, timeout_s: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


task_id = create(
    "https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg",
    "slow orbit around the product, light glints across the glass, petals drift down",
    duration=5,
)
mp4_url = wait(task_id)

# Download immediately — the URL is short-lived.
with requests.get(mp4_url, stream=True, timeout=120) as resp:
    resp.raise_for_status()
    with open("clip.mp4", "wb") as f:
        for chunk in resp.iter_content(1 << 16):
            f.write(chunk)
print("saved clip.mp4")

프로덕션 환경 주의사항

폴링 또는 콜백 사용. 5초마다 폴링하는 것(위 예시와 같음)이 가장 간단한 방법이며 예제에서 사용한 방식입니다. 결과를 푸시받고 싶다면 생성 호출이 최상위 callback 객체를 받습니다 — {"url": "https://you/webhook", "when": "final"} — 작업이 종료 상태에 도달하면 HiAPI가 엔드포인트로 POST 요청을 보냅니다. 정확한 webhook 계약은 작업 생성 문서를 참고하세요. 대부분의 단일 클립 작업에는 작업 상세 엔드포인트 폴링이면 충분합니다.

항상 data.status를 기준으로 분기하고, 절대 생성 호출의 HTTP 상태 코드를 기준으로 분기하지 마세요. 생성이 200을 반환한다는 것은 접수됨을 의미할 뿐 렌더링됨을 의미하지 않습니다. 상세 엔드포인트가 status: "success"를 반환할 때만 클립이 실제로 존재합니다.

출력 URL은 임시 링크로 취급하세요. storage가 temp이고 URL이 만료되므로, 작업 성공 후 즉시 MP4를 다운로드해야 합니다(또는 자체 스토리지 버킷에 복사). HiAPI URL을 최종 사용자에게 직접 제공하지 마세요.

비용 관리. 완료된 출력 초당 과금됩니다 — 초당 $0.06 — 따라서 5초 클립은 $0.30, 10초 클립은 $0.60입니다. 프롬프트와 첫 프레임을 반복 테스트하는 동안에는 먼저 5초로 렌더링하고, 만족하면 10초로 다시 실행하세요. 최신 가격은 가격 페이지를 참고하세요.

실측 노트와 주의사항

이 글의 모든 내용은 단순한 파라미터 표가 아니라 실제 운영 엔드포인트에 대한 실제 요청에서 나온 것입니다(스키마는 2026-10-21에 재검증):

필드는 image_urls(복수형)이며 스키마는 닫혀 있습니다. 자연스러워 보이는 image_url을 보내면 작업 생성 전에 실패합니다:
```
{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: image_urls: missing required field \"image_urls\"; <root>: additional properties 'image_url' not allowed" }
```
인식할 수 없는 필드(mode, 오타 등)도 동일한 방식으로 거부됩니다 — 조용히 무시되는 추가 필드는 없습니다.
duration은 열거형이지 범위가 아닙니다. 5와 10만 허용되며, 7을 보내면 duration: value must be one of 5, 10이 반환됩니다.
image_urls는 1개 또는 2개 항목을 포함합니다. URL 하나는 첫 프레임이고, 두 번째 URL은 제어된 전환을 위해 마지막 프레임을 고정합니다. URL 세 개를 보내면 maxItems: got 3, want 2가, 빈 배열을 보내면 minItems: got 0, want 1이 반환됩니다.
실제로 존재하는 선택 필드: aspect_ratio는 16:9, 9:16, 1:1, 4:3, 3:4, 21:9만 허용됩니다. cfg_scale은 최대 1이며(99를 보내면 cfg_scale: maximum: got 99, want 1 반환), negative_prompt는 문자열이어야 합니다. aspect_ratio를 생략하면 모델이 첫 프레임을 따릅니다.
생성 호출은 구조만 검증하고 접근성은 검증하지 않습니다 — 가장 함정에 빠지기 쉬운 부분입니다. 문법은 유효하지만 접근할 수 없는 이미지 URL은 200과 taskId를 반환하며, 이후 작업이 비동기적으로 실패로 전환됩니다:
```
{ "data": { "status": "fail",
  "error": { "code": "INVALID_REQUEST",
    "message": "The image URL is not readable. Please provide a valid public HTTP(S) URL or an accessible file path and try again." } } }
```
해당 작업은 output을 생성하지 않았고 과금되지 않았습니다 — 실패에는 요금이 부과되지 않습니다 — 하지만 생성 응답만 확인하면 성공한 것으로 오인하게 됩니다. 이것이 바로 폴링 루프가 data.status를 기준으로 판단해야 하는 이유입니다.

자주 묻는 질문

클립 길이는 얼마나 될 수 있나요? 5초 또는 10초입니다 — 이것이 스키마가 허용하는 유일한 두 가지 duration 값입니다.

엔딩을 제어할 수 있나요? 네. image_urls에 URL 두 개를 넣으세요: 첫 번째는 시작 프레임, 두 번째는 마지막 프레임입니다. 모델이 두 프레임 사이를 보간하여 모션을 생성합니다.

생성은 200을 반환했는데 작업이 fail로 표시되는 이유는 무엇인가요? 생성 호출은 JSON이 스키마를 준수하는지만 검사합니다. 이미지는 작업이 실행될 때 가져오므로, 접근할 수 없거나 비공개 URL은 작업을 생성한 후 실패시킵니다. 항상 상세 엔드포인트에서 data.status를 읽고 첫 프레임 URL이 공개적으로 접근 가능한지 확인하세요.

실패한 작업에도 요금이 부과되나요? 아닙니다. 완료된 출력 초수 기준으로 과금되므로 입력이 유효하지 않아 실패한 작업은 output을 생성하지 않고 요금도 부과되지 않습니다.

화면 비율 제어가 있나요? aspect_ratio는 선택 사항이며 16:9, 9:16, 1:1, 4:3, 3:4, 21:9를 허용합니다. 비워두면 첫 프레임을 따릅니다.