튜토리얼
HiAPI API로 hailuo-2.3/image-to-video 호출하는 방법: curl과 Python
이 페이지에서
hailuo-2.3/image-to-video가 할 수 있는 것과 언제 사용할지
hailuo-2.3/image-to-video는 HiAPI 통합 API로 제공되는 이미지-투-비디오 모델입니다. 정적 이미지를 첫 프레임으로 주고, 화면이 어떻게 움직여야 하는지 설명하는 프롬프트를 함께 전달하면, 모델이 해당 이미지에서 시작해 그 위에 애니메이션을 이어 붙인 짧은 영상을 생성합니다.
핵심 키워드는 첫 프레임입니다. 텍스트-투-비디오에서는 모델이 프롬프트를 바탕으로 전체 화면을 상상해서 만들어내지만, 이미지-투-비디오는 구도, 피사체, 조명, 스타일을 제공한 이미지에 고정합니다. 따라서 보존해야 할 특정 시각 자료—제품 이미지, 캐릭터 레퍼런스, 스토리보드 컷, 콘셉트 렌더링—가 이미 있고, 이를 새로 해석하기보다 그 위에 움직임을 더하고 싶을 때 더 적합한 선택입니다.
이 엔드포인트가 적합한 상황:
- 기존 소재와의 일관성을 유지해야 할 때. 제품 사진은 약간 다른 제품으로 다시 생성되는 것이 아니라 움직여야 합니다.
- 정적 프레임을 기반으로 스토리보드나 애니매틱을 만들고 있으며 움직임을 빠르게 미리 보고 싶을 때.
- 통제된 구도가 필요할 때: 카메라와 피사체 위치는 이미지에서 오고, 프롬프트는 움직임만 설명하면 됩니다.
참조 이미지가 없고 모델이 카메라를 설계하기를 원하거나, 시각적 세부 사항을 프레임으로 고정하기보다 텍스트로 표현하는 편이 더 나은 경우에는 텍스트-투-비디오를 사용하는 것이 좋습니다.
사전 준비와 API 키 발급
첫 요청 전에 세 가지가 필요합니다: HiAPI 계정, API 키, 그리고 공개적으로 접근 가능한 첫 프레임 이미지 URL입니다.
계정과 API 키
HiAPI에 로그인하고 콘솔에서 API 키를 생성하세요. 키는 기밀로 취급해야 합니다: 소스 파일에 붙여 넣지 말고 환경 변수에 보관하세요. 이 가이드의 예제는 모두 HIAPI_API_KEY에서 읽어옵니다.
export HIAPI_API_KEY="your-api-key-here"
접근 가능한 이미지 URL
첫 프레임으로 전달하는 이미지는 서버에서 가져올 수 있어야 합니다—서명된 클라우드 스토리지 URL, CDN 링크 또는 임의의 공개 HTTPS URL이면 되고, 로컬 파일 경로는 안 됩니다. 소재가 인증이 필요한 위치에 있다면 요청을 위해 유효 기간이 있는 서명 URL을 생성하세요.
어떤 흐름이든 자동화하기 전에 최신 HiAPI API 참조 문서에서 현재 엔드포인트 경로, 파라미터 이름, 허용 값을 먼저 확인하세요. 모델 인터페이스는 진화하므로, 오래된 튜토리얼에서 본 파라미터 이름을 하드코딩하는 것은 흔하고 피할 수 있는 실수입니다. 현재 가격과 할당량 규칙은 웹사이트 가격 패널에 나와 있으니, 추측하지 말고 그곳에서 확인하세요.
요청 구조: 이미지 입력과 파라미터
개념적으로 이미지-투-비디오 요청은 세 부분으로 구성됩니다: 모델 식별자, 이미지, 생성 파라미터.
모델 식별자
모든 호출은 hailuo-2.3/image-to-video를 가리킵니다. 코드의 한 위치에 모아 두면 나중에 모델을 바꿀 때 한 줄만 수정하면 됩니다.
첫 프레임 이미지
영상이 시작되는 정적 이미지의 URL입니다. 이 이미지의 가로세로 비율과 해상도가 출력의 기본 기하 구조를 결정하므로, 나중에 잘라내기보다 이미 원하는 구도를 가진 이미지를 선택하세요. 깨끗하고 조명이 좋으며 피사체가 명확한 이미지가 어수선한 콜라주보다 훨씬 예측 가능한 움직임을 만들어냅니다.
프롬프트
움직임을 설명하는 텍스트 필드—다음 섹션에서 다룹니다.
길이와 해상도
이미지-투-비디오 작업은 보통 클립 길이와 출력 해상도 옵션을 제공합니다. 이 파라미터는 모델 버전에 따라 바뀔 가능성이 가장 크므로 기억에 의존해 하드코딩하지 마세요. 최신 API 참조 문서를 열어 허용되는 필드 이름과 허용 값을 읽고, 그 값들을 코드 곳곳에 리터럴로 흩뿌리지 말고 설정 객체에 넣으세요. 어떤 값이 거부되면 API 응답은 보통 어느 필드가 문제인지 알려줍니다.
요청 본문은 JSON이며, 응답은 완성된 영상이 아니라 작업 식별자를 반환합니다. 이는 아래 폴링 섹션에서 다룹니다.
그럴듯한 움직임을 만들어내는 프롬프트 작성법
이미지는 이미 장면 안에 무엇이 있는지를 설명합니다. 프롬프트의 임무는 그것이 어떻게 움직이는지를 설명하는 것입니다. 피사체를 다시 설명하는 프롬프트는 모델의 역량을 낭비하며, 움직임, 카메라 동작, 물리 법칙을 명확히 하는 프롬프트가 훨씬 나은 영상 클립을 만들어냅니다.
내용이 아닌 움직임을 설명하세요
나쁜 예: “빨간 코트를 입은 여성이 다리 위에 서 있다.”
좋은 예: “여성이 천천히 카메라 쪽으로 고개를 돌리며 미소 짓고, 코트가 바람에 흔들린다; 카메라가 부드럽게 앞으로 밀고 들어간다.”
피사체 움직임과 카메라 움직임을 분리하세요
둘 다 명확히 하세요. “천천히 앞으로 푸시 인”, “핸드헬드 드리프트”, “고정 카메라”, “오른쪽으로 오비트”는 화면 자체가 어떻게 변하는지 알려주고, “머리카락이 흩날린다”, “김이 피어오른다”, “책장이 넘어간다”는 화면 내부에서 일어나는 일을 설명합니다. 둘을 결합해야 흔들리는 화면이 아닌 일관된 촬영이 나옵니다.
물리 법칙을 따르게 하세요
합리적인 속도로 합리적인 움직임을 요구하세요: “천이 가볍게 일렁인다”, “물이 하류로 흐른다”, “연기가 위로 말려 올라간다”. 장면과 모순되는 지시—앉아 있는 피사체가 걷게 하거나, 고정 카메라 제품 촬영에 빠른 팬을 요구하는 것—은 보통 아티팩트를 초래합니다.
짧고 구체적으로 유지하세요
구체적이고 물리적인 두세 문장이 형용사로 가득한 한 문단보다 낫습니다. 주요 움직임을 먼저, 그다음 카메라를, 마지막으로 조명 변화 같은 부차적 세부 사항을 설명하세요.
작업 제출과 결과 폴링
영상 생성에는 시간이 걸리므로 API는 비동기식입니다. 생명주기는 세 단계로 나뉩니다:
1. 작업 생성
이미지 URL, 프롬프트, 파라미터를 엔드포인트로 POST하세요. 성공적인 응답은 작업 식별자와 초기 상태(보통 queued 또는 processing과 유사)를 반환합니다. 이 응답에는 아직 영상이 없습니다.
2. 작업 폴링
해당 작업 식별자로 주기적으로 GET 요청을 보내세요. 각 응답은 상태를 보고하며, 완료되면 결과 페이로드도 포함합니다. 타이트한 루프가 아니라 보통 몇 초 간격으로 합리적인 주기로 폴링하고, 시도 횟수를 제한해 멈춘 작업이 프로세스를 영구적으로 매달리게 하지 마세요.
3. 영상 가져오기
상태가 성공을 보고하면 응답에 영상 위치(보통 URL)와 함께 종종 길이 같은 메타데이터가 포함됩니다. 자체 보존 규칙에 따라 다운로드하거나 저장하세요.
프로덕션 설계 요점
- 작업 ID를 영속화하세요. 워커 프로세스가 폴링 도중 죽으면, 다시 제출해 중복 작업 비용을 지불하는 대신 복구할 수 있어야 합니다.
- 종료 상태 실패를 처리하세요. 작업은 실패할 수 있습니다; 실패는 “계속 폴링”이 아니라 별도 분기로 처리해야 합니다.
- 제출과 폴링을 분리하세요. 웹 백엔드에서는 요청 핸들러에서 제출하고 백그라운드 워커에서 폴링하여 HTTP 타임아웃이 실행 중인 생성 작업을 절대 죽이지 않게 하세요.
실행 가능한 curl 예제
다음 예제는 작업을 제출합니다. 이미지 URL과 프롬프트를 자신의 것으로 바꾸세요; 키는 앞서 설정한 환경 변수에서 가져옵니다.
curl -sS -X POST \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://your-cdn.example.com/first-frame.jpg",
"prompt": "화면 속 피사체가 카메라 쪽으로 살짝 돌아 미소 짓는다; 카메라가 천천히 밀고 들어가고, 부드러운 빛이 얼굴 위로 흐른다."
}'
응답에는 작업 식별자가 포함됩니다. GET 요청으로 폴링하세요:
curl -sS \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
상태가 종료 성공이 될 때까지 반복한 다음, 페이로드에서 영상 URL을 읽으세요. 여기 표시된 정확한 엔드포인트 경로와 필드 이름은 패턴 설명용입니다—모델 인터페이스는 실제로 바뀌므로 프로덕션 코드에 붙여 넣기 전에 최신 API 참조 문서와 대조해 확인하세요.
실행 가능한 Python 예제
이 스크립트는 작업을 제출한 뒤 완료될 때까지 폴링하며, 타임아웃과 기본 오류 처리를 포함합니다.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def create_task(image_url: str, prompt: str) -> str:
resp = requests.post(
BASE,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image_url": image_url, "prompt": prompt},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"No task id in response: {data}")
return task_id
def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = str(data.get("status", "")).lower()
if status in {"succeeded", "success", "completed"}:
return data
if status in {"failed", "error", "cancelled"}:
raise RuntimeError(f"Task {task_id} failed: {data}")
time.sleep(interval_s)
raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task = create_task(
image_url="https://your-cdn.example.com/first-frame.jpg",
prompt="컵에서 김이 피어오른다; 카메라가 천천히 오른쪽으로 드리프트한다.",
)
result = poll_task(task)
print(result)
API 버전에 따라 상태 문자열이 다를 수 있으므로, 코드는 단일 리터럴 대신 흔한 성공 및 실패 값의 작은 집합을 검사합니다—API 참조 문서에서 정확한 어휘를 확인하고 집합을 적절히 조정하세요. 여러 미디어 파이프라인을 구축한다면 이 헬퍼 함수를 분리해 두면 재사용하기 편합니다.
흔한 실패 패턴과 디버깅 방법
이 엔드포인트의 대부분 문제는 몇 가지 범주로 나뉩니다.
이미지가 거부되거나 가져올 수 없음
서비스가 이미지를 다운로드할 수 있어야 합니다. 가져오기 또는 검증 오류가 발생하면 URL이 공개 HTTPS인지, 만료되지 않았는지(서명 URL은 만료됩니다), 형식과 크기가 문서 제한 내인지 확인하세요. 빠른 확인 방법은 브라우저 시크릿 창에서 해당 URL을 여는 것입니다—로그인을 요구하면 서버도 읽을 수 없습니다.
잘못된 파라미터
거부된 길이, 해상도 또는 알 수 없는 필드는 보통 해당 필드를 지목하는 검증 오류를 반환합니다. 페이로드를 튜토리얼이 아니라 최신 API 참조 문서와 비교하고, 전체 오류 본문을 기록하세요—오류 메시지가 HTTP 상태 코드만 볼 때보다 더 구체적입니다.
인증 오류
401 또는 403은 거의 항상 키 누락, 형식 오류 또는 접근 권한 부족을 의미합니다. Authorization 헤더가 있는지, 환경 변수가 실제로 요청을 실행하는 셸이나 프로세스에 내보내졌는지 확인하세요.
폴링 타임아웃
작업이 타임아웃 후에도 processing 상태라면 먼저 올바른 작업 ID를 폴링하고 있는지 확인한 다음 타임아웃을 늘리세요. 프로덕션에서는 “아직 실행 중”과 “멈춤”을 구분해야 합니다: 상태를 영속화하고 워커가 폴링을 재개하게 하세요. 재제출은 작업을 낭비합니다.
제출 후 작업 실패
실패한 작업은 보통 프롬프트나 이미지 조합을 가리킵니다—모순되는 움직임 지시, 또는 요청한 움직임과 충돌하는 첫 프레임. 프롬프트를 단순화하고, 더 깨끗한 첫 프레임으로 시도한 뒤 다시 실행하세요.
출력이 이상해 보임
움직임이 약하거나 이상하면 해결책은 거의 항상 프롬프트입니다: 주요 움직임을 명확히 하고, 카메라 동작과 피사체 동작을 분리하고, 물리적 움직임을 합리적으로 유지하세요. 로그에 요청 ID와 작업 ID를 기록해 좋지 않은 영상 클립을 그것을 만들어낸 정확한 입력과 연결하세요. 게시 전에 API 참조 문서와 가격 패널에서 파라미터 이름과 현재 가격을 확인하세요.