Kling 4.0 이미지-투-비디오 API: 요청 참조 및 실제 실행 1회

Kling 4.0 이미지-투-비디오는 첫 프레임 이미지 한 장으로 3–30초 길이의 동기화된 오디오가 포함된 클립을 만들 수 있습니다. 이 가이드에서는 hiapi에서 바로 사용할 수 있는 요청 예시, API가 허용하고 거부하는 필드, 그리고 실제 실행 1회의 결과를 제시합니다. hiapi 콘솔에서 API 키를 발급받아야 하며, 모델 ID는 kling-4.0/image-to-video이고 모델 페이지에 현재 사양이 나열되어 있습니다.

아직 Kling 3.0을 사용 중이라면, Kling 4.0 API 개요는 출시 전에 작성되어 출시 공지를 설명한 것이므로, 현재 사용 가능한 참조는 이 페이지입니다.

최소 요청(curl)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "prompt": "그녀가 살짝 고개를 카메라 쪽으로 돌리고, 머리카락이 바람에 흩날리며, 카메라가 천천히 다가가고, 주변에는 파도 소리",
      "image_urls": ["https://example.com/first-frame.jpg"],
      "duration": 3,
      "resolution": "720p"
    }
  }'

응답은 즉시 작업 ID를 반환합니다:

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

GET /v1/tasks/<taskId>를 data.status가 success가 될 때까지 폴링한 뒤, data.output[0].url을 읽으세요.

Python: 제출 및 폴링

import os, time, requests

BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def kling4_i2v(image_url, prompt, duration=5, resolution="720p"):
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, json={
        "model": "kling-4.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # 정확히 한 장의 첫 프레임 이미지
            "duration": duration,        # 정수, 3-30
            "resolution": resolution,    # "720p" 또는 "1080p"
        },
    })
    body = r.json()
    if body["code"] != 200:
        raise RuntimeError(body["message"])
    task_id = body["data"]["taskId"]

    while True:
        d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)

반환된 MP4 파일을 즉시 다운로드하세요. 출력 URL에는 expireAt 타임스탬프가 포함되며(당사 실행에서는 약 7일 후) 임시 도메인에 호스팅되므로, 직접 핫링크하지 말고 자체 스토리지에 복사하세요.

API가 허용하는 필드

의도적으로 유효하지 않은 값으로 이 엔드포인트를 테스트했습니다(이 값들은 HTTP 400 INVALID_REQUEST를 반환하며 작업이 생성되지 않음):

필드	관찰된 규칙
image_urls	필수 배열, 정확히 한 항목 (두 항목 → maxItems: got 2, want 1)
duration	정수, 최소 3, 최대 30. "5" 같은 문자열은 거부됨(got string, want integer)
resolution	720p 또는 1080p
aspect_ratio	선택 사항: 16:9, 9:16, 1:1, 21:9. 생략하면 구도가 소스 이미지를 따르며, 모델 페이지에 그렇게 명시되어 있음
prompt	움직임 설명. 검증기 테스트에서는 이 필드 없이 요청만 보냈으므로 권장 필드로 간주함

다른 비디오 모델에서 코드를 이전할 때 실수하기 쉬운 두 가지가 있습니다:

• 필드는 image_urls이며 image_url이 아닙니다. image_url을 보내면 "필수 필드 image_urls 누락"과 "추가 속성 image_url 허용되지 않음"이 동시에 보고됩니다.
• 오디오 스위치는 없습니다. audio, generate_audio, sound는 모두 추가 속성으로 거부됩니다. 오디오는 항상 화면과 함께 생성되므로, 프롬프트에서 오디오를 유도하세요(위 예시는 주변 파도 소리를 요구함).

알 수 없는 필드는 무시되지 않고 거부되므로, 오타는 조용히 무시된 설정이 아니라 400으로 드러납니다.

프로덕션 환경 고려 사항

• 폴링보다 콜백을 우선하세요. 클립 생성에는 수 분이 걸리므로 작업 생성 시 callback(url과 when: "final" 포함)을 전달하고 웹훅에서 결과를 처리하세요. 폴링은 백업 수단으로만 사용하세요.
• 과금 전에 검증하세요. 유효하지 않은 입력은 400을 반환하고 작업을 생성하지 않으므로, 먼저 자체 코드에서 길이와 해상도를 확인하세요. 잘못된 요청은 비용이 들지 않지만, 올바른 요청은 요구한 매 초마다 과금됩니다.
• 과금은 초 단위이며 해상도에 따라 달라집니다. 더 긴 클립과 1080p는 더 비쌉니다. 기사 속 숫자에 의존하지 말고 가격에서 현재 요율을 확인하세요.
• 작업 ID를 저장하세요. 일시적인 네트워크 오류로 폴링이 실패하면 다시 제출하지 말고 같은 ID를 다시 폴링하세요. 그렇지 않으면 두 번째 클립이 생성되고 과금됩니다.

실측 실행

위 요청을 제출했습니다: 세로형 첫 프레임 이미지, duration: 3, resolution: "720p", aspect_ratio 없음.

• 약 10초마다 폴링했을 때 관찰된 상태 순서: handling → archiving → success.
• 총 실제 소요 시간: 3초 클립 기준 약 274초. handling이 약 255초를 차지하므로 초 단위가 아니라 분 단위로 계획하고 콜백 중심으로 설계하세요.
• 출력 파일(ffprobe로 확인): H.264 비디오, 1280×720, 3.04초, 그리고 동일 길이의 AAC 오디오 트랙. 따라서 오디오는 실제로 MP4에 임베드되며, 구도는 16:9 소스 이미지를 따릅니다.

다음은 테스트하지 않았습니다: 1080p, 3초를 초과하는 길이, 그리고 기본값이 아닌 aspect_ratio 값. 이러한 제한은 생성된 출력이 아니라 API 검증 메시지와 모델 페이지에서 나온 것입니다.

관련 페이지

• Kling 4.0 이미지-투-비디오 모델 페이지
• Kling 4.0 텍스트-투-비디오 모델 페이지, 소스 이미지가 없을 때 적합
• Kling 3.0 이미지-투-비디오 모델 페이지
• Kling 3.0 Turbo 이미지-투-비디오 사용 방법
• hiapi 가격
• hiapi 문서

자주 묻는 질문

Kling 4.0 이미지-투-비디오에서 오디오를 끌 수 있나요?

요청 필드로는 불가능합니다. audio, generate_audio, sound는 모두 검증기에서 거부됩니다. 원하는 소리(또는 원하지 않는 소리)를 프롬프트에 설명하세요.

입력 이미지를 몇 장까지 보낼 수 있나요?

한 장입니다. image_urls는 정확히 한 장의 첫 프레임 이미지를 포함해야 합니다.

요청 하나에 얼마나 걸리나요?

당사의 3초 720p 클립은 엔드투엔드로 약 274초가 걸렸습니다. 프로덕션 부하에서는 콜백을 사용하세요.

가장 긴 클립은 얼마나 되나요?

API는 duration 최대 30(정수 초)을 허용하며 더 높은 값은 거부합니다. 당사는 직접 3초 클립만 생성했습니다.