HiAPI API로 Kling 3.0 이미지-투-비디오를 사용하여 숏폼 영상 만들기

숏폼 영상은 모든 콘텐츠 파이프라인이 결국 지원해야 하는 포맷이며, 이를 안정적으로 대량 생산하는 가장 저렴한 방법은 이미지-투-비디오입니다. 이미 통제하고 있는 정지 프레임—제품 이미지, 캐릭터 디자인, 생성된 키프레임—을 가져다가 비디오 모델이 움직이게 하는 것입니다. HiAPI의 Kling 3.0 이미지-투-비디오 엔드포인트는 이 분야에서 뛰어나며, 대부분의 i2v 모델이 건너뛰는 기능을 갖추고 있습니다. 첫 프레임과 마지막 프레임을 동시에 제공할 수 있어 모델이 단일 프레임에서 움직임을 외삽하는 대신 두 상태 사이에서 애니메이션을 만듭니다.

이 튜토리얼은 완전하고 스크립트화 가능한 워크플로를 구축합니다. 첫 프레임을 생성하고, Kling 3.0의 비동기 작업 API에 제출하고, 완료될 때까지 폴링하고, 네이티브 동기화 오디오가 포함된 완성된 클립을 다운로드합니다. 이 모든 것은 배치 작업에 바로 넣을 수 있는 일반 HTTP 호출로 이루어집니다.

텍스트-투-비디오 대신 이미지-투-비디오를 선택하는 이유

텍스트-투-비디오는 매번 예상치 못한 결과를 줍니다. 이미지-투-비디오는 이미 승인한 시작점을 제공합니다. 그 프레임이 제품 사진, 브랜드 캐릭터, 또는 움직이기 전에 특정하게 보여야 하는 무엇이든 이는 중요합니다. Kling 3.0의 이미지-투-비디오 모델은 첫 프레임+마지막 프레임 제어로 이를 더 발전시킵니다. 참조 이미지를 하나 전달하면 모델은 이를 시작점으로만 취급합니다. 두 개를 전달하면 두 번째가 목표 종료 상태가 되어 모델이 둘 사이에서 움직임을 보간합니다. 이것은 사실상 타임라인 편집기 없이 단일 API 호출로 구현하는 프로그래머블 키프레임 애니메이션입니다.

요청 구조

Kling 3.0 이미지-투-비디오는 HiAPI의 통합 비동기 작업 엔드포인트—POST /v1/tasks—에서 실행되며, 완료될 때까지 GET /v1/tasks/{id}로 폴링합니다. 이 모델의 입력 스키마는 의도적으로 간소하게 유지됩니다.

{
  "model": "kling-3.0/image-to-video",
  "input": {
    "prompt": "a lantern slowly lighting up as the camera pushes in, warm cinematic glow",
    "image_urls": ["https://static.hiapi.ai/blog/kling-3-0-image-to-video-short-form-workflow/first-frame-v2.jpg"],
    "duration": 3,
    "resolution": "720p",
    "sound": true
  }
}

이를 중심으로 구축하기 전에 알아둘 만한 몇 가지가 있습니다.

• image_urls는 1개 또는 2개의 항목을 받습니다. 이미지 하나는 "이 프레임에서 애니메이션 시작"을 의미합니다. 이미지 두 개는 "첫 번째에서 두 번째로 애니메이션"을 의미합니다—이것이 위에서 언급한 첫 프레임+마지막 프레임 제어입니다. 별도의 tail_image_url 필드는 없으며 모든 것은 배열 위치로 표현됩니다.
• duration은 3~15초의 정수입니다. 숏폼 플랫폼은 대부분 클립이 3~8초 범위에 있기를 원하므로 단일 장면에는 보통 이 범위의 낮은 쪽을 원합니다.
• resolution은 최대 4K까지 가능하며, 이는 kling-3.0-turbo 형제 모델(최대 1080p)보다 높습니다. 대가는 비용입니다—아래 가격 참조—따라서 720p 또는 1080p가 대부분의 숏폼 사용 사례를 충족하며, 아무도 휴대폰 화면에서 알아채지 못할 해상도에 비용을 지불할 필요가 없습니다.
• sound는 불리언이며, 이는 사후에 음악을 입힌 무음 클립이 아니라 진정한 동기화 오디오 생성입니다. 장면의 움직임이 합리적으로 소리를 낼 때(문 닫힘, 바람 소리, 발걸음) 켜면 결과가 무음 렌더보다 눈에 띄게 더 설득력 있습니다.
• aspect_ratio 필드는 없습니다—출력 화면은 입력 이미지의 기존 종횡비와 일치합니다.

엔드투엔드 스크립트

다음은 Python의 전체 흐름입니다. 작업을 생성하고, 완료될 때까지 폴링하고, 결과를 다운로드합니다.

import requests
import time

API_KEY = "YOUR_HIAPI_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_i2v(image_url, prompt, duration=3, resolution="720p", sound=True):
    payload = {
        "model": "kling-3.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "duration": duration,
            "resolution": resolution,
            "sound": sound,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_result(task_id, poll_interval=5, timeout_s=600):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = submit_i2v(
    image_url="https://static.hiapi.ai/blog/kling-3-0-image-to-video-short-form-workflow/first-frame-v2.jpg",
    prompt="a lantern slowly lighting up as the camera pushes in, warm cinematic glow",
)
video_url = wait_for_result(task_id)
print(video_url)  # temporary signed URL — download immediately, don't store it as a permanent link

이를 실제 파이프라인에 연결할 때 사람들이 쉽게 실수하는 세부 사항이 하나 있습니다. 돌려받는 output[0].url은 만료되는 임시 링크입니다. 작업의 출력 URL을 어디에도 장기 저장하지 말고, 바이트를 즉시 다운로드하여 자체 스토리지로 옮기십시오.

이 예제에서 사용된 첫 프레임과 Kling 3.0이 sound: true에서 이를 바탕으로 생성한 클립입니다.

위와 같은 3초, 720p, 오디오 포함 클립의 비용은 $0.40을 약간 넘습니다—원하는 전달 버전을 정하기 전에 프롬프트를 몇 번 반복하기에 충분히 저렴합니다.

가격: 해상도와 오디오가 모두 비용에 영향

Kling 3.0 이미지-투-비디오는 출력 길이 기준 초당 과금되며, 해상도와 오디오 스위치가 요금에 영향을 줍니다.

해상도	오디오 없음	오디오 포함
720p	$0.10/s	$0.143/s
1080p	$0.129/s	$0.193/s
4K	$0.479/s	—

계산 예시: 3초, 720p, 사운드 포함 클립은 약 $0.43입니다. 5초, 1080p, 오디오 없는 클립은 $0.645이며, 동일한 클립에 오디오를 포함하면 $0.965입니다. 대부분의 완성 클립이 3~8초 범위에 있는 숏폼 콘텐츠의 경우 720p 또는 1080p가 거의 항상 올바른 선택입니다—4K 가격은 다운스트림에서 추가 해상도의 이점을 실제로 누릴 수 있는 대상에 합성해야 할 때만 타당합니다. 대규모로 무언가를 실행하기 전에 현재 가격을 확인하십시오. 초당 요금 같은 세부 사항은 기억에 의존해 캐시하기보다 실시간 페이지에서 확인할 가치가 있습니다.

실제 워크플로로 배치 처리하기

어떤 규모의 숏폼 콘텐츠든 작업 하나를 제출하고 계속 바라보고 싶지는 않을 것입니다—작업 배치를 한 번에 보내고 결과가 도착하는 대로 수집하고 싶을 것입니다. 각 작업은 독립적이며 자체 taskId로 식별되므로 패턴은 간단합니다. 모든 이미지-투-비디오 요청을 먼저 제출하고, 반환된 작업 ID를 저장한 다음, 이를 순환 폴링하며 각 작업이 success 또는 fail이 될 때만 조치합니다. 이렇게 하면 파이프라인이 가장 느린 단일 생성에 직렬화되지 않고 플랫폼의 실제 처리량으로 실행됩니다.

처음부터 길러야 할 몇 가지 습관:

• 제출 전에 소스 이미지에 접근 가능한지 확인하십시오. 작업 API는 URL을 기꺼이 받아들이고 나중에 이미지를 가져올 수 없으면 작업이 실패합니다—HEAD 요청으로 먼저 확인하면 낭비되는 생성을 피할 수 있습니다.
• fail 상태를 예외가 아닌 정상 결과로 취급하십시오. 모델 출력이 특정 프롬프트/이미지 조합을 가끔 거부할 수 있습니다. 전체 배치를 중단하지 말고 실패를 기록하고 다음 항목으로 계속하십시오.
• 가능하면 변형 간에 클립을 재사용하십시오. 동일한 생성 애니메이션에 여러 자막이나 사운드트랙을 테스트한다면 비디오 자체를 다시 생성할 필요가 없습니다—그것은 순전히 다운스트림 편집 단계입니다.

API 키와 인증을 처음 설정하는 경우 HiAPI의 빠른 시작 가이드가 키를 얻고 첫 인증 호출을 하는 기본 사항을 다루며, 그 후에는 그 위에 전체 배치 파이프라인을 구축할 수 있습니다.

요약

Kling 3.0의 이미지-투-비디오 모델은 단일 HTTP 호출로 단일 정지 프레임—첫 프레임+마지막 프레임 제어를 원한다면 두 프레임—을 동기화 오디오가 포함된 숏폼 클립으로 바꾸며, 가격은 지속 시간, 해상도, 사운드 필요 여부에 따라 예측 가능하게 확장됩니다. 숏폼 파이프라인에서는 이러한 제어력, 720p/1080p에서의 낮은 클립당 비용, 간단한 비동기 작업 API의 조합 덕분에 비디오 편집기를 건드리지 않고도 "정지 이미지 하나"에서 "완성된 클립 배치"로 쉽게 이동할 수 있습니다.