LTX 2.5 Fast 이미지-투-비디오 API 사용법? 정지 이미지를 움직이게 하기

TL;DR

• LTX 2.5 Fast Image to Video(ltx-2.5-fast/image-to-video)는 정지 이미지를 움직이게 합니다: 첫 프레임 이미지 1장(선택적으로 마지막 프레임 1장 추가)을 업로드하면 720p / 1080p의 2–20초 영상을 원본 오디오와 함께 생성합니다. 모델 페이지 열기에서 이미지 한 장을 업로드하면 바로 체험할 수 있고, 신규 사용자는 가입 시 200 크레딧을 받습니다.
• 가격은 텍스트-투-비디오와 동일한 규칙입니다: 720p 초당 $0.043, 1080p 초당 $0.086, duration 초 수 기준으로 과금되며 오디오 스위치는 가격에 영향을 주지 않습니다.
• 호출은 HiAPI /v1/tasks 인터페이스를 사용합니다: image_urls에 이미지 1–2장(첫 프레임 / 첫 프레임+마지막 프레임)을 전달하고, 성공하면 output에서 영상을 가져옵니다.

할 수 있는 일

• 첫 프레임 움직이기: 정지 사진 한 장 + 한 줄의 동작 설명으로 화면의 주체는 그대로 두고 움직임, 카메라, 소리를 더합니다.
• 첫 프레임 + 마지막 프레임: 이미지 두 장을 전달하면 모델이 첫 프레임에서 마지막 프레임까지의 전환 과정을 채워 넣습니다(예: 낮의 오두막에서 별밤의 오두막으로).
• 세로 화면 지원: 출력 화면 비율은 aspect_ratio로 결정되며(16:9 / 9:16), 잘림이나 여백을 피하려면 첫 프레임과 일치시키는 것을 권장합니다.
• 같은 시리즈의 텍스트-투-비디오: 처음부터 생성하려면 텍스트-투-비디오 연동 가이드를 참고하세요. 두 인터페이스의 가격 규칙은 완전히 같습니다.

아래는 실제 결과물입니다(정지 등대 사진 → 6초 사운드 영상):

Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls

(한국어 의미: 파도가 등대 아래 바위에 부딪히고, 갈매기가 황금빛 하늘을 가로질러 날아가며, 카메라가 천천히 다가가고, 파도와 갈매기 소리. 첫 프레임은 소재의 등대 사진을 사용, 파라미터: 720p, 6초, 16:9.)

→

ltx-2.5-fast/image-to-video, 720p, 6초, 16:9, 1280×720, 사운드 포함, $0.258.전체 영상 보기 →

이 프롬프트로 생성하기 →

첫 프레임 / 첫 프레임 + 마지막 프레임 전달 방법

입력	image_urls	효과
1장	["첫 프레임 이미지"]	이 이미지에서 움직이기 시작, 주체는 그대로 유지
2장	["첫 프레임 이미지", "마지막 프레임 이미지"]	첫 프레임에서 마지막 프레임으로 전환, 모델이 중간 과정을 채움

이미지는 JPG / PNG / WebP의 공개 URL을 지원합니다. 두 이미지의 화면 비율을 일치시키고 aspect_ratio를 첫 프레임과 같게 설정하는 것을 권장합니다.

두 가지 시작 방법

브라우저 3단계: 모델 페이지 열기 → 첫 프레임 이미지 업로드, 동작 설명 작성 → 생성 클릭, 결과가 나오면 바로 미리보기.

API 3단계: POST /v1/tasks 제출 → taskId 획득 → GET /v1/tasks/<taskId>로 success 확인 후 다운로드.

curl: 첫 번째(단일 첫 프레임)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ltx-2.5-fast/image-to-video",
  "input": {
    "prompt": "Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls",
    "image_urls": ["https://static.hiapi.ai/gallery/2026/10/0ca26560398eae72.jpg"],
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "16:9"
  }
}'

첫 프레임 + 마지막 프레임(낮의 오두막 → 별밤의 오두막)은 image_urls만 변경합니다:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ltx-2.5-fast/image-to-video",
  "input": {
    "prompt": "Time passes from bright winter day to starry night, the sky darkens, the cabin windows light up warmly and smoke rises from the chimney, an aurora appears, fixed camera",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/7756ea1a228b0b88.jpg",
      "https://static.hiapi.ai/gallery/2026/10/16e267619aa1b003.jpg"
    ],
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }
}'

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

import time, uuid, requests

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

payload = {
    "model": "ltx-2.5-fast/image-to-video",
    "input": {
        "prompt": "Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls",
        "image_urls": ["https://example.com/your-first-frame.jpg"],
        "resolution": "720p",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video = next(o for o in task["output"] if o.get("type") == "video")
    mp4 = requests.get(video["url"], timeout=120)   # 임시 주소, 가능한 한 빨리 저장
    with open("output.mp4", "wb") as f:
        f.write(mp4.content)
    print("saved output.mp4")

파라미터 표

필드	필수	값	설명
image_urls	예	공개 URL 1–2장	1번째는 첫 프레임, 2번째는 마지막 프레임(JPG/PNG/WebP)
prompt	예	1–5000자	동작, 카메라, 소리를 설명. 화면에 이미 있는 것은 반복해서 설명하지 않아도 됨
resolution	아니오	720p / 1080p, 기본 720p	1080p 초당 가격은 720p의 약 2배
duration	아니오	2/3/4/5/6/8/10/12/14/16/18/20, 기본 6	열거형 값
aspect_ratio	아니오	16:9 / 9:16, 기본 16:9	첫 프레임과 일치시키는 것을 권장, 잘림이나 여백 방지
generate_audio	아니오	기본 true	원본 오디오. 후반 작업으로 직접 음악을 넣으려면 끄기

요청 본문에 표에 없는 필드가 있으면 바로 400이 반환됩니다.

발생할 수 있는 오류

상태 코드	의미	처리 방법
400 INVALID_REQUEST	요청 본문이 유효하지 않음(image_urls 또는 prompt 누락, 이미지 3장 전달, duration이 열거형 값이 아님)	파라미터 표에 맞춰 요청 본문 수정
402 INSUFFICIENT_QUOTA	잔액 부족(과금되지 않음)	충전 후 재시도
429 RATE_LIMITED	속도 제한 발생	제출 빈도 낮추기
409 / 422 IDEMPOTENCY_KEY_*	동일한 멱등 키로 중복 제출	새 Idempotency-Key로 변경

최종 상태 실패에는 CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT 등이 있으며, 실패 시 과금되지 않습니다.

출시 전 주의 사항

• 콜백: 영상 작업은 시간이 오래 걸리므로 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달해 폴링을 줄이세요.
• 즉시 저장: output의 영상 주소는 임시이므로 받는 즉시 다운로드하세요.
• 첫/마지막 프레임 화면 비율 일치: 두 이미지의 비율 차이가 너무 크면 전환이 왜곡되기 쉽습니다. aspect_ratio를 첫 프레임과 같게 설정하세요.
• 후반 작업으로 직접 음악 삽입: generate_audio를 false로 전달하면 깨끗한 화면을 얻으며 가격은 동일합니다.
• 첫 프레임 품질이 결과물 품질을 결정: 흐리거나 해상도가 너무 낮은 첫 프레임은 움직여도 선명해지지 않습니다. 먼저 선명한 큰 이미지를 사용하고 모델에 동적 효과를 맡기세요.

자주 묻는 질문

• 네, 최대 2장의 이미지: 첫 프레임 1장 또는 첫 프레임 + 마지막 프레임. 3번째 이미지는 400이 반환됩니다.
• 네, 화면 비율은 이미지를 따르지 않습니다: aspect_ratio로 결정되므로 첫 프레임과 같게 수동으로 설정하는 것을 권장합니다.
• 네, 가격은 텍스트-투-비디오와 같습니다: 720p 초당 $0.043, 6초 한 건 $0.258.
• 네, 마지막 프레임 전환은 '시간 경과' 연출에 적합합니다: 낮에서 밤으로, 빈 장면에서 제품이 가득한 장면으로, 두 이미지와 한 줄 프롬프트면 충분합니다.
• 네, 제품 이미지를 움직이는 것이 강점입니다: 상품 대표 이미지를 첫 프레임으로 하고 프롬프트에 카메라 워크(orbit, push in)와 장식 요소를 적으면 한 편의 쇼케이스 영상이 나옵니다.
• 네, 세로 사진에는 9:16: 720×1280으로 출력되어 숏폼 플랫폼에 바로 게시할 수 있습니다. 가로 사진은 16:9를 유지하세요.

다음 단계: 제품 이미지를 가지고 모델 페이지에서 움직이게 하기, 네 가지 이미지-투-비디오 시나리오는 프롬프트 모음을 참고하세요.