LTX 2.5 Fast 텍스트-투-비디오 API 사용법? 5분 만에 첫 영상 만들기

TL;DR

• LTX 2.5 Fast Text to Video(ltx-2.5-fast/text-to-video)는 한 편의 텍스트를 2–20초 영상으로 변환하며, 720p / 1080p, 가로·세로 화면, 네이티브 오디오를 함께 출력합니다. 모델 페이지 열기에서 바로 시도해 볼 수 있고, 신규 사용자 가입 시 200 크레딧을 증정합니다.
• 가격은 초 단위로 계산: 720p 초당 $0.043(6초 한 편 $0.258), 1080p 초당 $0.086이며, generate_audio 스위치는 가격에 영향을 주지 않습니다.
• 호출은 HiAPI /v1/tasks 인터페이스를 사용합니다: 작업을 제출해 taskId를 받고, 결과를 조회한 뒤 성공하면 output에서 영상 주소를 가져옵니다(임시 주소이므로 즉시 저장).

무엇을 할 수 있나

• 한 문장으로 사운드 포함 장면 생성: 장면, 움직임, 카메라, 사운드를 하나의 프롬프트에 작성하면 오디오가 화면과 함께 생성됩니다.
• 2–20초, 12가지 길이: duration은 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 18, 20 중 선택, 기본 6초.
• 가로·세로 화면과 두 가지 해상도: 16:9 / 9:16, 720p / 1080p; 프레임 레이트는 25fps MP4 고정.
• 같은 시리즈에 이미지-투-비디오도 있음: ltx-2.5-fast/image-to-video는 첫 프레임(마지막 프레임 추가 가능)을 업로드해 정지 이미지를 움직이게 하며, 가격 규칙은 동일합니다. 이미지-투-비디오 모델 페이지 참고.

두 인터페이스 선택법:

	ltx-2.5-fast/text-to-video(이 페이지)	ltx-2.5-fast/image-to-video
입력	한 편의 텍스트	이미지 1–2장 + 한 문장의 움직임 설명
적합	제로에서 장면 탐색, 광고 아이디어, 스토리보드	보유한 제품 이미지/사진을 움직이게 할 때
제어 포인트	프롬프트, 해상도, 길이, 화면비	첫 프레임(+마지막 프레임), 프롬프트, 해상도, 길이

한마디로: 화면 내용이 정해지지 않았으면 텍스트-투-비디오, 화면이 이미 있으면 이미지-투-비디오; 두 인터페이스는 연결 가능 — 텍스트-투-비디오로 확정된 첫 프레임을 만든 뒤 이미지-투-비디오에 넘겨 카메라 무빙을 추가.

아래는 실제 결과물(720p · 6초, 사운드 포함):

A barista pours steamed milk into a latte, creating a leaf pattern, close-up, soft morning light through a café window, gentle clinking cups and café ambience

(한국어 의미: 바리스타가 스팀 밀크를 라떼에 부어 잎 모양을 만들고, 클로즈업, 아침 햇살이 카페 창문을 통해 들어오며, 잔 부딪히는 소리와 카페 환경음. 파라미터는 기본값 사용: 720p, 6초, 16:9, 오디오 켜짐.)

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

이 프롬프트로 생성하기 →

두 가지 시작 경로

브라우저 3단계: 모델 페이지 열기 → 프롬프트 붙여넣고 길이와 해상도 선택 → 생성 클릭, 720p 6초 한 편 $0.258, 영상 생성 후 바로 온라인 미리보기.

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/text-to-video",
  "input": {
    "prompt": "A barista pours steamed milk into a latte, creating a leaf pattern, close-up, soft morning light through a café window, gentle clinking cups and café ambience",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

이 720p × 6초는 $0.258입니다.

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/text-to-video",
    "input": {
        "prompt": "A barista pours steamed milk into a latte, creating a leaf pattern, close-up, soft morning light through a café window, gentle clinking cups and café ambience",
        "resolution": "720p",
        "duration": 6,
        "aspect_ratio": "16:9",
        "generate_audio": True,
    },
}

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")
    video_url = video["url"]   # 임시 주소이므로 빨리 다운로드하여 저장
    mp4 = requests.get(video_url, timeout=120)
    with open("output.mp4", "wb") as f:
        f.write(mp4.content)
    print("saved output.mp4")

파라미터 표

필드	필수	값	설명
prompt	예	1–5000자	한 문장으로 전부 작성: 장면, 움직임, 카메라, 사운드
resolution	아니오	720p / 1080p, 기본 720p	1080p 초당 가격은 720p의 약 2배
duration	아니오	2/3/4/5/6/8/10/12/14/16/18/20, 기본 6	이 열거값만 가능(7, 9 없음)
aspect_ratio	아니오	16:9 / 9:16, 기본 16:9	세로 숏폼 영상은 9:16 선택
generate_audio	아니오	기본 true	네이티브 오디오; 꺼도 가격 인하 없음

요청 본문에 표에 없는 필드가 있으면 즉시 400.

만나게 될 오류

상태 코드	의미	처리 방법
400 INVALID_REQUEST	요청 본문 불법(prompt 누락, duration에 7 같은 비열거값 전달, 표 외 필드 전달)	파라미터 표에 맞춰 요청 본문 수정
402 INSUFFICIENT_QUOTA	잔액 부족(과금 없음)	충전 후 재시도
429 RATE_LIMITED	속도 제한 발생	제출 빈도 낮추기
409 / 422 IDEMPOTENCY_KEY_*	동일 멱등 키 중복 제출	새 Idempotency-Key로 변경

작업 종료 상태 실패에는 CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT 등이 있으며; 실패 시 과금 없음.

출시 전 주의

• 콜백: 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달하면 종료 상태를 자동으로 알려줍니다; 영상 작업은 소요 시간이 길어 사용을 권장.
• 즉시 이전 저장: output의 영상 주소는 임시이므로 받자마자 다운로드.
• duration과 resolution 명시: 이 두 필드가 청구를 결정하므로 기본값에 의존하지 말 것; 출시 전 이 두 값을 로그에 남기면 대사 시 한눈에 파악.
• 배치 리듬: 6초 영상 한 편은 제출부터 생성까지 대기가 필요하므로, 배치 작업은 대기열 제출 + 콜백 결과 수신을 권장하며 동기적으로 하염없이 기다리지 말 것.
• 정지 이미지를 움직이게 하려면: 같은 시리즈의 이미지-투-비디오 모델 페이지를 사용하고 첫 프레임을 업로드하면 더 제어 가능.

자주 묻는 질문

• 네, 오디오는 영상과 함께 생성됩니다: generate_audio는 기본 켜짐; 프롬프트에 소리를 작성하면(바람 소리, 잔 부딪히는 소리) 오디오가 화면에 더 잘 맞습니다.
• 네, 길이는 12단계뿐: 2에서 20초 사이의 열거값, 7초, 9초 같은 값을 전달하면 400.
• 네, 가격 = 초당 가격 × 초 수: 720p 6초 $0.258, 1080p 6초 $0.516; 오디오 꺼도 저렴해지지 않음.
• 네, $10로 약 38편: 720p 6초 한 편 기준.
• 네, 세로형은 9:16 선택: 출력 720×1280(720p) 또는 1080×1920(1080p), 숏폼 플랫폼에 다시 자를 필요 없음.
• 네, 해상도는 낮은 것부터 높은 것으로 권장: 프롬프트와 구도 조정은 720p로, 확정되면 1080p로 올려 같은 프롬프트 재실행, 초당 가격 차이는 두 배지만 완성품은 하나.
• 네, 오디오 꺼도 비용 절감 없음: 후반 더빙/음악을 넣으려면 generate_audio: false를 전달해 깨끗한 화면 확보.

다음 단계: 라떼 아트 프롬프트로 모델 페이지에서 첫 영상 만들기, 네 가지 장면 템플릿은 텍스트-투-비디오 프롬프트 모음 참고.