튜토리얼

AI 비디오의 첫 프레임과 마지막 프레임 제어: hiapi에서 모델 간 정확한 움직임 가이드

Sep 4, 2026

대부분의 이미지-투-비디오 API는 정지 이미지 한 장만 받은 뒤 움직임을 즉흥적으로 생성합니다. 시작점만이 아니라 샷의 종착점까지 고정할 수 있는 모델은 소수에 불과합니다——첫 프레임과 마지막 프레임을 제공하면 모델이 그 사이를 보간하여 움직임을 생성합니다. 바로 이것이 '이 사진을 움직이게 하기'와 '이 전환을 정확히 구현하기'의 차이입니다.

문제는 모델마다 마지막 프레임 제어 지원이 일관되지 않으며, 같은 제조사의 제품 라인 안에서도 플래그십 등급과 고속/초고속 등급이 다를 수 있다는 점입니다. 이 튜토리얼은 어떤 hiapi 비디오 모델이 첫 프레임 제어만 지원하는지, 어떤 모델이 첫 프레임+마지막 프레임 제어를 지원하는지 명확히 설명하고, 각자의 실제(그리고 통일되지 않은) 입력 필드를 제시합니다. 그래야만 한참 고생한 끝에 선택한 모델이 마지막 프레임을 조용히 무시했다는 사실을 뒤늦게 발견하는 일이 없을 것입니다.

1. 준비물

콘솔에서 발급받은 hiapi API key(sk-...)와 대상 모델이 가져올 수 있는 이미지 URL 두 개(공인 HTTPS URL——작업 엔드포인트는 로컬 파일 업로드를 지원하지 않습니다)가 필요합니다. 아래의 모든 모델은 동일한 통합 task API로 호출되므로, 키가 그중 하나에 작동하면 모든 모델에 작동합니다.

2. 최소 실행 예제

모든 hiapi 비디오 생성은 같은 엔드포인트를 사용합니다: 작업을 생성한 뒤, 종료 상태가 될 때까지 폴링합니다(또는 콜백 사용——프로덕션 패턴 참조).

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video는 이 패턴의 가장 전형적인 예입니다: input.image_urls는 이미지 URL을 하나 또는 두 개 받습니다. 하나를 전달하면 모델은 첫 프레임만 고정하고 나머지는 자유롭게 생성합니다. 두 개를 전달하면 두 번째 URL이 강제 마지막 프레임이 됩니다——모델은 샷이 어디에서 끝나야 하는지 지정받습니다. 길이는 3–15(초)의 정수이며, resolution은 720p / 1080p / 4k, 선택적 sound 불리언은 생성된 분위기 오디오를 추가합니다. 여기에는 aspect_ratio 필드가 없습니다——출력 화면 비율은 제공한 프레임을 따릅니다.

모든 모델이 이런 구조는 아닙니다. seedance-2.5/image-to-video는 배열이 아닌 따로 이름 붙은 두 필드로 같은 효과를 냅니다:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url은 first_frame_url과 짝을 이룰 때만 의미가 있습니다——first_frame_url만 보내 첫 프레임 전용 샷을 만들 수는 있지만 그 반대는 불가능합니다. 이 모델의 길이 범위는 4–30s이며, 해상도는 최대 720p/1080p까지만 지원합니다(4K 등급 없음). 또한 aspect_ratio의 기본값은 adaptive로, 명시적인 16:9/9:16 값이 아니라 첫 프레임을 따릅니다.

모델마다 필드명이 실제로 다릅니다——image_urls와 first_frame_url/last_frame_url——따라서 모델을 바꿀 때마다 단순 교체가 아니라 스키마 변경으로 취급해야 합니다.

모든 모델이 지원하는 것은 아님

veo-3.1/image-to-video는 단일 image_url 문자열을 받으며 마지막 프레임 파라미터가 전혀 없습니다——aspect_ratio(auto/16:9/9:16), resolution, 그리고 고정된 duration 열거형(4, 6 또는 8초)을 설정할 수 있지만 종료 프레임은 고정할 수 없습니다. Kling 제품 라인의 한 단계 아래도 마찬가지입니다: kling-3.0-turbo/image-to-video(kling-3.0-omni의 고속/저가 버전)의 image_urls는 최대 한 항목만 받습니다——마지막 프레임도, 4K 해상도도 없습니다. 마지막 프레임 제어가 필요하다면 모델 패밀리 이름만 보고 판단하지 말고 플래그십 등급이나 이를 위해 설계된 모델(예: seedance-2.5)을 선택해야 합니다.

3. 프로덕션 패턴

대규모에서는 폴링 대신 콜백을 사용하세요. 루프에서 폴링하는 대신 같은 요청 본문에 callback 객체를 전달합니다:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final"은 작업이 어느 종료 상태에 도달할 때 한 번만 트리거됩니다——succeeded와 failed 모두 종료 상태이므로, webhook 핸들러는 콜백이 성공만을 의미한다고 가정하지 말고 taskId로 중복을 제거해야 합니다. GET /v1/tasks/:id 폴링은 로컬 디버깅, 저빈도 일회성 호출, 또는 콜백이 도착하지 않을 때(네트워크 지터, 엔드포인트 일시 다운)의 대조 보루로 더 적합합니다.

멱등성. 타임아웃이나 연결 중단 후의 재시도가 부주의하면 중복 작업을 생성할 수 있습니다——생성 호출이 반환한 작업 id를 기록하고, 새 작업 제출을 고려하기 전에 해당 id로 GET을 재시도로 수행하세요.

출력 URL은 만료됩니다. 각 출력 항목의 expireAt 필드는 장식이 아닙니다——콜백이든 폴링이든 작업 성공을 알게 되면 가능한 한 빨리 비디오를 다운로드하여(자체 스토리지에) 영속화해야 합니다.

인증 실패. 잘못되었거나 누락된 키는 HTTP 401과 {"error": {"code": "permission_denied", ...}}를 반환합니다. 모든 비 2xx 응답이 생성 자체의 실패를 의미한다고 가정하지 말고 해당 상태/오류 코드를 명시적으로 확인해야 합니다——오류 처리에서 '내 키가 틀렸다'와 '모델이 내 입력을 거부했다'를 구분하는 것은 매우 가치 있습니다. 수정 방법이 완전히 다르기 때문입니다.

4. 관련 페이지

Kling 3.0 Omni 이미지-투-비디오 모델 페이지 —— 위 예제에서 사용한 모델의 가격, 온라인 체험, 전체 파라미터 레퍼런스.
Seedance 2.5 이미지-투-비디오 모델 페이지 —— first_frame_url/last_frame_url 변형.
인증 문서 —— Authorization: Bearer sk-... 요청 헤더와 키 스코프의 작동 방식.
작업 생성 문서 —— 콜백 옵션을 포함한 전체 /v1/tasks 요청/응답 레퍼런스.
hiapi 가격 —— 현재 초당 및 해상도별 가격(청구는 모델과 해상도에 따라 다르므로 하드코딩된 숫자 대신 실시간 페이지를 확인하세요).

5. 자주 묻는 질문

어떤 hiapi 비디오 모델이 마지막 프레임 제어를 지원하나요? kling-3.0-omni/image-to-video(2개 항목의 image_urls 배열 사용)와 seedance-2.5/image-to-video(first_frame_url + last_frame_url 사용)가 현재 모두 지원합니다. veo-3.1/image-to-video와 kling-3.0-turbo/image-to-video는 지원하지 않습니다——단일 시작 프레임만 받습니다.

마지막 프레임만 지정하고 prompt는 제공하지 않아도 되나요? 두 모델 모두 프레임 외에 prompt를 받으며(보통 기대합니다)——이는 콘텐츠뿐 아니라 두 프레임 사이의 움직임을 이끕니다. 모든 모델이 비어 있거나 누락된 prompt를 직접 거부하지는 않지만, 전환을 명시적으로 설명하면 움직임이 더 예측 가능해집니다.

두 프레임의 화면 비율이 같아야 하나요? kling-3.0-omni/image-to-video와 seedance-2.5/image-to-video 모두 이미지 설정과 별개인 명시적 aspect_ratio를 제공하지 않습니다——출력 화면 비율은 입력 프레임을 따르므로, 첫 프레임과 마지막 프레임의 화면 비율이 일치하지 않으면 오류가 아니라 눈에 띄게 어색한 결과가 나옵니다. 제출 전에 두 프레임을 같은 비율로 자르거나 채워 넣으세요.

마지막 프레임만 보내고 첫 프레임을 보내지 않으면 어떻게 되나요? 두 모델 모두 지원하지 않습니다——seedance-2.5에서는 last_frame_url이 first_frame_url과 함께만 사용할 수 있습니다. kling-3.0-omni의 배열은 위치 기반으로 읽힙니다(첫 항목 = 첫 프레임). 종료 프레임만 지정하는 '역방향' 모드는 존재하지 않습니다.

마지막 프레임 제어는 비디오-투-비디오 움직임 전이와 같나요? 아닙니다——그것은 다른 기능입니다(hiapi의 seedance-2.5/reference-to-video. 두 정지 이미지가 아니라 움직임이나 카메라 무브를 이끄는 참조 비디오를 받습니다). 첫/마지막 프레임 제어는 두 이미지 사이를 보간하고, 참조 비디오-투-비디오는 기존 클립의 움직임 패턴을 모방합니다.

마지막 프레임을 추가하면 첫 프레임만 생성할 때보다 비싼가요? 두 모델 모두 초당/해상도별로 청구하며 입력 이미지별로 청구하지 않으므로, 마지막 프레임 추가 자체는 비용을 증가시키지 않습니다——현재 요금은 가격 페이지를 확인하세요.