튜토리얼
HiAPI API로 kling-4.0-flash Reference-to-Video 호출하기: curl과 Python 실전
다중 참조 이미지 기반 영상 생성의 실행 가능한 호출 실전, 비동기 폴링 및 문제 해결 가이드
- 모델
- kling-4.0-flash
이 페이지에서
참조 이미지 기반 영상 생성이 텍스트 기반 영상 생성보다 적합한 경우
텍스트 기반 영상 생성은 작가의 도구입니다. 장면을 설명하면 모델이 모든 것을 새로 만들어 냅니다. 참조 이미지 기반 영상 생성은 감독의 도구입니다. 모델에 하나 이상의 이미지를 주고, 그 주체·스타일·구도를 식별 가능하게 유지하는 움직이는 영상을 생성하도록 요구합니다. HiAPI에서 이 차이는 엔드포인트 수준에서 드러납니다. kling-4.0-flash/reference-to-video는 일반 텍스트 기반 영상 생성 호출과는 다른 독립된 라우트이며, 미리 올바른 엔드포인트를 선택하면 특정 외형을 끝내 완전히 재현하지 못하는 프롬프트 엔지니어링에 빠지는 일을 피할 수 있습니다.
다음 중 하나라도 해당하면 참조 이미지 기반 영상 생성을 선택하세요.
- 정체성 또는 제품 일관성이 결정적입니다. 캐릭터 설정 이미지, 제품 사진, 마스코트가 있고 결과물이 일반화된 유사 형상으로 흐트러지면 안 됩니다.
- 여러 소스를 조합해야 합니다. 한 장면에서 한 이미지로 캐릭터를 정하고, 다른 이미지로 환경이나 의상을 정해야 할 수 있습니다. 여러 참조 이미지라면 산문 설명 대신 이러한 구성을 명확히 표현할 수 있습니다.
- 스타일 전이가 목적입니다. 주어진 화면의 색조, 조명, 렌더링 스타일을 움직이는 영상에 반영하고 싶습니다.
- 특정 샷을 반복 개선 중입니다. 참조 이미지는 시각적 기준점이 고정되어 있으므로 여러 번 다시 실행해도 비교 가능성이 생기고, 움직임 관련 파라미터만 조정하면 됩니다.
개념을 탐색 중이거나, 권리가 명확한 이미지를 기준점으로 쓸 수 없거나, 요구 사항 자체가 추상적이어서("새벽 무렵 안개를 가로지르는 느린 항공 촬영") 어떤 합리적 해석도 허용되는 경우에는 계속 텍스트 기반 영상 생성을 사용하세요. 참조 이미지는 모델을 제약하며, 제약은 정말 필요할 때만 유익합니다.
실용적인 규칙이 하나 있습니다. 특정 물체의 정확한 외형을 설명하기 위해 긴 문단을 쓰고 있다면, 그것이 이 엔드포인트로 전환해 이미지를 직접 제공하라는 신호입니다. 설명은 토큰을 소모하면서도 여전히 흐트러집니다. 참조 이미지가 기준을 고정합니다.
요청 구조: 참조 이미지와 핵심 파라미터
이 엔드포인트는 JSON 요청 본문을 받습니다. 실제로 다루게 되는 부분은 참조 이미지, 프롬프트, 출력 형성 파라미터의 세 가지로 나뉩니다.
참조 이미지
참조 이미지는 배열 형태로 전달되므로 같은 필드에서 한 이미지에서 여러 이미지로 자연스럽게 확장할 수 있습니다. 각 항목은 서비스가 가져올 수 있는 URL입니다. 설계 시 고려해야 할 실제 제약은 다음과 같습니다.
- 공개적으로 접근 가능한 HTTPS URL 또는 계정에 접근 권한이 있는 URL을 사용하세요. 로컬 파일 경로와
file://URI는 원격 서비스가 가져올 수 없습니다. - 몇 분 뒤 만료되는 서명 링크보다 안정적인 호스팅을 선호하세요. 장시간 실행되는 작업은 예상보다 늦은 시점에 이미지를 가져올 수 있습니다.
- 각 이미지를 집중된 형태로 유지하세요. 깔끔한 주체 이미지가 복잡한 콜라주보다 더 도움이 됩니다. 모델이 보이는 내용을 식별해야 하기 때문입니다.
- 순서가 참조 이미지의 해석 방식에 영향을 줄 수 있으므로, 코드에서 배열 순서를 딕셔너리 반복 순서에 의존하지 말고 확정적으로 유지하세요.
프롬프트
참조 이미지를 제공한 뒤에는 프롬프트가 외형이 아니라 움직임, 카메라, 분위기를 설명해야 합니다. 주체가 어떻게 움직이는지, 카메라가 어떻게 움직이는지, 리듬이 어떤 느낌인지 설명하세요. 참조 이미지를 다시 설명하는 것은 프롬프트 예산을 낭비하고 방금 제공한 기준점과 충돌할 수 있습니다.
출력 형성 파라미터
prompt와 참조 이미지 배열 외에도 요청 본문에는 보통 출력 형식과 생성 동작을 제어하는 필드가 포함됩니다. 이것들은 마지막에 조정할 손잡이로 생각하세요. 먼저 기본값으로 호출을 성공시키고, 참조 이미지가 실제로 반영되는지 확인한 다음 출력 설정을 조정하세요. 필드 이름과 허용 값은 엔드포인트 참조 문서에 정의되어 있으며, 인식되지 않는 필드를 보내는 것은 요청 본문이 거부되는 흔한 원인입니다. 따라서 추측하지 말고 문서의 스키마에 맞게 검증하세요.
멘탈 모델은 간단합니다. 참조 이미지는 무엇인지를, 프롬프트는 어떻게 움직이는지를, 파라미터는 무엇을 돌려받는지를 설명합니다.
사용 가능한 curl 요청
클라이언트 코드를 작성하기 전에 요청 본문을 확인하는 가장 확실한 방법은 curl 호출 한 번입니다. 자격 증명과 입력을 셸 변수로 설정하고 JSON을 읽기 쉽게 유지한 뒤 요청을 보내세요.
API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai" # 콘솔에 표시되는 기본 URL을 사용하세요
curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "캐릭터가 창문 쪽으로 몸을 돌리고, 카메라가 천천히 다가간다. 부드러운 아침 햇살, 차분한 리듬.",
"reference_images": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg"
]
}'
실행 전에 세 가지를 확인하세요.
- 경로와 버전 접두사. 계정의 엔드포인트 문서와 대조해 정확한 라우트를 확인하세요. 경로에 버전 번호가 포함되며, 오래된 접두사는 검증 오류가 아니라 찾을 수 없음 오류를 반환합니다.
- 인증 헤더. 키는 bearer token 형태로
Authorization헤더에 넣습니다. 요청 본문이나 쿼리 문자열에 넣지 마세요. 로그에 유출됩니다. - 플레이스홀더. 반드시 교체해야 하는 값은 모두 명백한 플레이스홀더입니다. 기본 URL 주석, 두 개의 CDN URL, 프롬프트가 그렇습니다. 프로덕션 사용 가능을 선언하기 전에 요청에서
example.com을 검색하세요.
성공적인 제출은 완성된 영상이 아니라 작업 식별자를 반환합니다. 다음 단계의 폴링에 사용되므로 응답 본문에서 해당 식별자를 캡처하세요. 응답을 JSON 포매터(| jq .)로 처리하면 작업 ID를 한눈에 볼 수 있으므로 습관화할 가치가 있습니다.
같은 호출의 Python 버전
Python 버전의 주요 차이는 요청 본문 구성 방식입니다. dict를 하나 만들고 한 번 직렬화하며, 요청 함수와 폴링 로직을 분리해 각각 독립적으로 테스트할 수 있게 하세요.
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]
REFERENCE_IMAGES = [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg",
]
def submit_reference_video(prompt: str) -> str:
payload = {
"prompt": prompt,
"reference_images": REFERENCE_IMAGES,
}
response = requests.post(
f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()["task_id"]
if __name__ == "__main__":
task_id = submit_reference_video(
"캐릭터가 창문 쪽으로 몸을 돌리고, 카메라가 천천히 다가간다."
)
print("submitted:", task_id)
다음 주의 사항을 따르면 불필요한 고통을 피할 수 있습니다.
- 키는 환경 변수에서 읽으세요. 하드코딩된 키는 결국 git 기록과 스크린샷에 남습니다.
data=가 아니라json=을 사용하세요. 클라이언트가 콘텐츠 타입을 올바르게 설정하고 본문을 이스케이프합니다.- 명시적인
timeout을 설정하세요. 기본값인 무한 대기는 멈춘 연결을 중단된 워커 프로세스로 바꿉니다. - 파싱 전에
raise_for_status()를 호출하세요. 그러면 4xx 응답 본문이 혼란스러운 JSON 응답의KeyError가 아니라 HTTP 오류로 보고됩니다. - 작업 식별자의 응답 필드 이름을
task_id라고 가정하지 말고 문서와 대조하세요. 추출하는 줄도 그에 맞게 조정하세요.
submit_reference_video는 ID만 반환하게 하세요. 폴링은 별개의 관심사이며 자체 함수에 두어야 합니다.
비동기 작업 수명 주기 처리
영상 생성에는 시간이 걸리므로 이 엔드포인트는 설계상 비동기입니다. 제출 호출은 작업 식별자를 빠르게 반환하고, 실제 작업은 그 뒤에 일어납니다. 통합에서는 이를 모델링해야 하며, 가장 단순한 올바른 모델은 세 가지 상태입니다. pending 또는 processing(계속 대기), succeeded(출력 가져오기), failed(오류를 읽고 중지).
일정 간격으로 작업 엔드포인트를 폴링하고 총 대기 시간에 상한을 두세요.
import time
def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
url = f"{BASE_URL}/v1/tasks/{task_id}"
while time.monotonic() < deadline:
r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
상태 문자열과 작업 경로는 문서 규정에 맞게 조정하세요. 위 구조는 패턴일 뿐이며, 이 영역의 대부분의 실패는 존재하지 않는 상태 레이블을 가정하는 데서 비롯됩니다.
가능한 한 일찍 도입할 가치가 있는 폴링 예절은 다음과 같습니다.
- 점진적 백오프. 짧은 고정 간격은 이득 없이 API를 반복적으로 때립니다. 적당한 값에서 시작해 시도 사이의 대기 시간을 늘리세요.
- 항상 루프에 상한을 두세요. 원격 작업을 둘러싼
while True는 고장을 기다리는 것과 같습니다. 위의 데드라인은 멈추는 대신 예외를 발생시킵니다. - 작업 ID를 영속화하세요. 제출 후 프로세스가 죽으면, 그 ID가 두 번째 생성 비용을 내지 않고 결과를 복구하는 유일한 방법입니다.
failed를 종료 상태로 취급하세요. 실패한 작업을 다시 폴링해 재시도하지 마세요. 오류를 읽고 적절할 때 수정된 요청 본문으로 다시 제출하세요.- 만료를 명시적으로 처리하세요. 작업 결과가 영구적으로 제공되지 않을 수 있으므로, 작업이 성공하면 즉시 출력을 다운로드하고 저장하세요.
흔한 오류와 해결 방법
대부분의 첫 통합 실패는 몇 가지 범주에 속합니다. 코드를 바꾸기 전에 증상과 원인을 맞춰 보세요.
인증 및 권한 부여 실패
401 또는 403은 거의 항상 자격 증명이 잘못되었거나, 없거나, 범위가 올바르지 않다는 뜻입니다. 헤더가 정확히 Authorization: Bearer <key>인지 확인하고, 해당 환경 변수가 호출을 수행하는 프로세스에 실제로 채워졌는지(shell export는 systemd 유닛으로 전달되지 않습니다) 확인하며, 키가 교체되거나 폐기되지 않았는지 확인하세요.
참조 이미지 문제
이미지 때문에 요청이 거부되었거나 생성 시 특정 참조 이미지를 무시했다면 의심할 곳은 URL입니다. 링크가 당신의 머신 바깥에서도 확인 가능한지 검증하세요. 내부 호스트 이름이나 localhost 주소는 서비스에 도달할 수 없습니다. 서명 URL의 만료 시간을 확인하고, 파일이 실제 이미지인지(200 상태로 반환되는 HTML 오류 페이지가 아닌지) 확인하며, 크기와 형식 제한을 확인하세요. 다중 이미지 배열의 항목 하나가 잘못되면 전체 요청이 실패할 수 있으므로 디버깅할 때는 참조 이미지를 하나씩 테스트하세요.
유효하지 않은 요청 본문
검증 메시지가 있는 400은 보통 요청 본문 형식이 잘못되었다는 뜻입니다. 최상위가 객체가 아니라 배열이거나, 필수 필드가 빠졌거나, reference_images가 배열이 아니라 따옴표로 감싼 문자열로 전송되었거나, 파라미터 이름이 인식되지 않은 경우입니다. 요청 본문을 문서 스키마와 필드별로 비교하고, 실제로 보낸 정확한 요청 본문을 로깅하세요. 결함은 종종 테스트 경로와 프로덕션 경로 사이의 직렬화 차이입니다.
라우트 또는 메서드 오류
404는 보통 모델을 사용할 수 없다는 뜻이 아니라 경로가 잘못되었다는 뜻입니다. 문서와 대조해 버전 접두사와 엔드포인트 이름을 다시 확인하고, 제출에는 POST를, 작업 상태 조회에는 GET을 사용하는지 확인하세요.
타임아웃과 폴링 오류
제출 자체가 타임아웃되면 클라이언트 타임아웃을 적절히 높이고 재시도하세요. 하지만 작업이 이미 수락되었다면 무작정 다시 제출하지 마세요. 중복 생성 비용을 지불하게 됩니다. 폴링이 끝나지 않는다면 상태 검사에서 잘못된 문자열을 비교하고 있을 가능성이 큽니다. 처음 몇 번의 폴링 동안 원시 상태 값을 기록해 실제로 무엇이 반환되는지 확인하세요.
속도 제한
429는 속도를 늦춰야 한다는 뜻입니다. 즉시 재시도하지 말고 주어진 간격을 지키며, 지터를 더한 지수 백오프를 적용해 병렬 워커들이 동시에 재시도하지 않게 하세요.
출시 전 프로덕션 체크리스트
노트북에서 실행되는 코드는 안정적인 통합과 같지 않습니다. 이 엔드포인트를 사용자에게 노출하기 전에 운영 경계를 단단히 하세요.
- 구성. 기본 URL과 API 키를 환경 변수나 시크릿 관리에 보관하고, 절대 소스 코드에 쓰지 마세요. 엔드포인트 경로를 상수로 두면 버전 업그레이드 시 한 줄만 바꾸면 됩니다.
- 백오프를 포함한 재시도. 연결 재설정, 429, 5xx 같은 일시적 장애에는 지터를 더한 지수 백오프로 재시도하세요. 4xx 검증 오류는 재시도하지 마세요. 같은 방식으로 실패합니다.
- 멱등성 규율. 제출한 모든 작업 ID와 그 입력을 기록하세요. 재시작 시 새 작업을 제출하지 말고 기존 작업의 폴링을 재개하세요.
- 제한된 대기. HTTP 클라이언트와 폴링 루프 모두에 명시적 타임아웃을 설정하고, 타임아웃은 조용히 버리지 말고 사람이 점검할 수 있는 데드 레터 경로로 보내세요.
- 구조화된 로깅. 작업 ID, 타임스탬프가 있는 상태 전이, 제출과 완료 시점, 실패 시 오류 본문을 기록하세요. 키는 마스킹하고, 프롬프트에 사용자 데이터가 포함되면 잘라내세요.
- 출력 처리. 작업이 성공하면 즉시 생성된 미디어를 자체 스토리지로 다운로드하고, 사용자에게 표시하기 전에 결과를 검증하세요.
- 비용 가시성. 청구는 사용량에 따라 달라지므로 기능별, 사용자별로 얼마나 많은 작업이 제출되었는지 추적하세요. 불확실성 속에서 재제출하는 재시도 루프는 예상치 못한 지출의 가장 흔한 원인입니다.
- 입력 위생. 참조 URL과 프롬프트 길이를 먼저 당신 쪽에서 검증하세요. 잘못된 URL을 로컬에서 잡는 것이 왕복 한 번보다 빠르고 저렴합니다.
이를 마치면 통합은 가볍고 예측 가능한 계층이 됩니다. 요청 본문 구성, 제출, 폴링, 저장. 엔드포인트 참조 문서에서 시작해 curl 예제를 한 번 실행한 뒤, 같은 요청 본문을 Python으로 옮기세요. shell에서 동작하는 요청은 당신의 서비스에서도 동작합니다.