튜토리얼
HiAPI API로 kling-4.0-flash 이미지-투-비디오 사용하는 방법: curl과 Python
실용 요청 실습: 첫 프레임 이미지 입력, 비동기 작업 폴링, 동기 오디오와 오류 진단
- 모델
- kling-4.0-flash
이 페이지에서
kling-4.0-flash 이미지-투-비디오 엔드포인트의 역할
kling-4.0-flash/image-to-video는 이미지를 조건으로 하는 비디오 생성 모델입니다. 이미지—즉 첫 프레임—와 텍스트 프롬프트를 주면, 그 프레임에서 시작해 설명대로 전개되는 생성된 비디오를 반환합니다.
코드를 작성하기 전에 가장 먼저 새겨야 할 점: 이것은 하나의 HTTP 교환에서 비디오 바이트를 반환하는 요청/응답식 호출이 아닙니다. 생성에는 시간이 걸리므로 이 엔드포인트는 비동기 작업 모델을 따릅니다. 첫 요청으로 작업을 제출하고, 이후 작업이 종료 상태에 도달할 때까지 상태를 폴링하여 결과를 가져옵니다.
이 세 가지 개념을 머릿속에서 구분하세요. 클라이언트의 서로 다른 세 부분에 대응하기 때문입니다:
- 제출——보내는 페이로드: 첫 프레임 이미지, 프롬프트, 생성 옵션.
- 작업 참조——제출 시 반환되는 식별자로, 나중에 해당 작업을 조회하는 데 사용합니다.
- 결과 가져오기——상태를 반복 확인하여 최종적으로 완료된 비디오(또는 실패)를 반환받습니다.
엔드포인트를 RPC가 아닌 작업 큐로 취급하면, 통합의 나머지 부분—폴링 간격, 타임아웃, 재시도—은 특수 상황이 아니라 평범한 비동기 파이프라인이 됩니다. 이 실습 외에 더 완전한 엔드포인트 문서를 함께 참고하려면 다른 탭에 열어 두고 따라 하세요.
요청을 보내기 전에
첫 호출 전에 세 가지를 준비해야 합니다.
1. API 자격 증명
HiAPI API 키가 필요합니다. 모든 요청에서 Authorization 헤더로 bearer 토큰 형태로 보냅니다. 소스 코드 관리에 포함하지 말고, 스크립트에 붙여 넣지 말고 환경 변수에서 읽으세요.
export HIAPI_API_KEY="your-api-key-here"
2. 엔드포인트 경로
모든 호출은 통합 HiAPI 인터페이스를 통해 이루어집니다. 대상 모델 식별자는 kling-4.0-flash/image-to-video입니다. 제출 요청과 이후 상태 조회 모두 같은 모델 네임스페이스를 가리키므로, 이 식별자를 코드의 상수 하나에 두고 문자열 리터럴을 곳곳에 흩뿌리지 마세요.
3. 준비된 첫 프레임 이미지
오프닝 프레임으로 사용할 이미지가 필요합니다. 보내기 전에 두 가지를 정하세요:
- 전달 방식——공개적으로 접근 가능한 URL로 보낼지, 인코딩된 이미지 데이터로 보낼지는 사용 사례에서 이 엔드포인트가 어떤 형식을 받아들이는지에 따릅니다.
- 형식이 올바른지——형식이 올바르고 읽을 수 있으며, 요청 본문을 비대하게 만들 만큼 크지 않아야 합니다.
실용적인 규칙 하나: 요청 본문을 작고 명확하게 유지하세요. URL을 전달한다면 호출 측이 인증 없이 접근할 수 있는지 확인하세요. 인코딩 데이터를 전달한다면 인코딩이 엔드포인트가 기대하는 것과 정확히 일치하는지 확인하세요.
동시에 짧고 구체적인 프롬프트를 준비하세요. 이미지-투-비디오 프롬프트는 프레임에 이미 보이는 내용을 되풀이하기보다 움직임과 변화(무엇이 움직이는지, 카메라가 어떻게 움직이는지)를 설명할 때 가장 잘 작동합니다.
사용 가능한 curl 요청
아래는 완전한 제출 호출입니다. 자리 표시자를 자신의 키, 이미지, 프롬프트로 교체하세요.
curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Slow dolly-in on the subject as light shifts across the scene",
"image": "https://your-host.example/first-frame.jpg"
}'
항목별 설명:
-X POST——제출은 조회가 아닌 쓰기 작업입니다.- URL——모델 식별자는 통합 엔드포인트 경로의 일부입니다. 모델을 지정하는 유일한 곳입니다.
Authorization: Bearer $HIAPI_API_KEY——셸이 환경 변수에서 확장하는 헤더입니다. 큰따옴표로 감싸면 변수가 확장되면서 그 값이 단일 인자로 유지됩니다.Content-Type: application/json——요청 본문은 JSON입니다. 이 헤더가 없으면 일부 게이트웨이가 페이로드를 거부하거나 잘못 파싱합니다.-d '{ ... }'——JSON 요청 본문입니다.prompt는 움직임을 설명하고,image는 첫 프레임을 제공합니다. 모든 필드가 명시적이며, 위치나 보이지 않는 기본값에 암묵적으로 의존하는 것은 없습니다.
성공적인 제출은 작업 식별자가 담긴 JSON 본문을 반환합니다. 이를 캡처하세요. 그 값이 해당 작업을 다루는 핸들입니다. 대화식으로 탐색 중이라면 응답을 JSON 포매터로 처리해 식별자를 복사하세요:
curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool
이 응답에 비디오가 있다고 생각하지 마세요. 없습니다. 이 응답은 작업이 접수되었음을 알려줄 뿐입니다.
같은 요청을 Python으로 구현
Python 클라이언트는 curl 페이로드와 정확히 대응합니다. 언어를 바꿔도 의미는 바뀌지 않고, 바이트를 보내는 메커니즘만 다릅니다. requests를 사용하고 키는 환경 변수에서 읽으세요:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"
def submit_job(prompt: str, image: str) -> dict:
response = requests.post(
f"{BASE_URL}/{MODEL}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"prompt": prompt,
"image": image,
},
timeout=30,
)
response.raise_for_status()
return response.json()
job = submit_job(
prompt="Slow dolly-in on the subject as light shifts across the scene",
image="https://your-host.example/first-frame.jpg",
)
print(job)
이식 요점:
-d대신json=사용——dict를 넘기면requests가 요청 본문을 직렬화하고 콘텐츠 유형을 설정합니다. JSON을 직접 작성하지 않고도 curl 예제와 같은 전송 형식을 얻습니다.raise_for_status()——2xx가 아닌 응답을 예외로 변환하여 오류 본문을 작업 참조로 착각하지 않게 합니다.timeout=30——제출은 빨라야 합니다. 넉넉한 타임아웃은 진짜 느린 호출을 감추지 않으면서 연결이 매달리는 것을 막습니다.- 모델은 단일 상수 사용——나중에 모델을 바꾸면 한 줄만 수정하면 됩니다.
반환된 dict에는 작업 식별자가 포함되어 있으며, 다음 섹션에서 활용합니다.
비동기 작업 수명 주기 처리
통합 패턴은 먼저 제출, 다음 폴링입니다. 두 단계가 명확히 구분됩니다.
1단계: 제출하고 참조 캡처
이전 섹션의 submit_job 호출은 작업 식별자가 담긴 JSON 본문을 반환합니다. 저장하세요. 이후 모든 상태 확인에 필요하며, 잃으면 해당 작업을 잃는 것입니다.
2단계: 종료될 때까지 폴링
상태 확인은 같은 작업에 대한 읽기 요청입니다. 작업이 종료 상태—완료 또는 실패—에 도달할 때까지 고정 간격으로 반복합니다. 시도 횟수 상한이 있는 간단한 루프:
import time
def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
for _ in range(attempts):
response = requests.get(
f"{BASE_URL}/{MODEL}",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"task_id": task_id},
timeout=30,
)
response.raise_for_status()
status = response.json()
state = status.get("status")
if state in ("succeeded", "failed"):
return status
time.sleep(interval)
raise TimeoutError(f"Job {task_id} did not finish in time")
의도적으로 내려야 할 설계 결정:
- 루프 횟수 제한. 절대 무한 폴링하지 마세요. 최대 시도 횟수와 고정 간격이 예측 가능한 최악 대기 시간을 제공합니다.
- 요청 내부가 아니라 확인 사이에 대기하세요. 지나치게 잦은 폴링은 할당량을 낭비하고 속도 제한을 유발할 수 있습니다.
- 실패를 종료 상태로 취급하세요. 실패한 작업이 다음 폴링에서 성공으로 바뀌지 않습니다. 멈추고 오류를 노출하세요.
- 대기 중과 완료를 구분하세요. 종료 상태만 루프를 끝냅니다. 다른 상태는 계속 기다려야 함을 의미합니다.
- 작업 ID를 영속화하세요. 프로세스가 폴링 중간에 크래시하면 재생성 대신 복구할 수 있기를 원합니다.
프로덕션에서는 폴링을 요청 스레드 밖으로 이동하세요—백그라운드 워커나 큐 소비자에 맡기세요—그래야 긴 생성이 웹 요청을 계속 열어 두지 않습니다.
동기 오디오 옵션 사용
이 엔드포인트는 동기 오디오 옵션을 제공합니다. 실무적으로 클라이언트에게 의미하는 바는 한 가지입니다: 이를 활성화하면 호출이 폴링할 작업 참조를 반환하는 대신 생성이 완료될 때까지 블로킹됩니다.
이는 구체적인 방식으로 설계를 바꿉니다:
- 타임아웃 예산을 늘려야 합니다. 블로킹 생성 호출은 일반 API 요청보다 훨씬 오래 걸릴 수 있습니다. 클라이언트 타임아웃을 제출 시간이 아닌 전체 예상 소요 시간을 덮도록 설정하세요.
- 중간 체크포인트가 불가능합니다. 폴링을 쓰면 크래시 후 작업 ID로 복구할 수 있습니다. 블로킹 호출을 쓰면 연결이 끊기는 순간 작업을 다시 해야 합니다.
- 스레드와 연결 풀 압박. 블로킹 호출은 전체 지속 시간 동안 워커 하나를 점유합니다. 웹 서버에서는 동시성 능력이 빠르게 제한됩니다.
언제 블로킹 호출이 허용될까요? 일회성 스크립트, CLI 도구, 배치 작업을 실행 중이고 결과를 기다리는 다른 것이 없으며 단순함이 처리량보다 중요할 때입니다. 이런 시나리오에서는 동기 호출이 폴링 메커니즘을 완전히 제거하고 코드도 더 짧아집니다.
언제 피해야 할까요? 사용자 대면 요청 경로, 고동시성 서비스, 또는 클라이언트가 타임아웃 후 재시도할 수 있는 모든 곳—재시도된 블로킹 호출은 작업량을 두 배로 만들 수 있습니다. 이런 시나리오에서는 이전 섹션의 비동기 제출 및 폴링 패턴을 유지하고 동기 옵션을 끄세요.
일반적인 실패 진단
실패를 계층적으로 처리하세요. 처음 보는 오류는 보통 가장 얕은 것이므로, 여러 문제를 한꺼번에 추측하지 말고 그것을 고친 뒤 다시 실행하세요.
인증 오류
401 또는 403은 자격 증명이 누락되었거나, 형식이 잘못되었거나, 거부되었음을 의미합니다. HIAPI_API_KEY가 실제로 프로세스가 보는 환경에 설정되어 있는지 확인하세요—한 셸에서 export한 변수는 다른 셸이나 컨테이너로 전달되지 않습니다. Authorization 헤더가 Bearer <key> 형식인지, 공백이 하나뿐인지, 복사-붙여넣기로 생긴 여분의 따옴표가 없는지 확인하세요.
페이로드 형식 오류
400은 보통 요청 본문을 파싱할 수 없거나 필수 필드가 누락되었음을 의미합니다. Content-Type: application/json을 보냈는지, JSON이 유효한지(후행 쉼표는 실패를 유발함), prompt와 image가 모두 존재하고 비어 있지 않은 문자열인지 다시 확인하세요. 디버깅할 때는 보내려고 한 dict가 아니라 실제로 보낸 요청 본문을 덤프하세요.
이미지 입력 문제
이 문제들은 보통 명확한 이미지 오류가 아니라 검증 오류로 나타납니다. 순서대로 확인하세요:
- 접근 가능성——URL을 전달한다면 요청이 시작되는 동일한 네트워크 환경에서 가져와 보세요. 브라우저에서는 되는 URL이 API에는 방화벽으로 막히거나 인증 보호를 받을 수 있습니다.
- 형식——이미지가 지원되는 손상되지 않은 파일인지 확인하세요. 의심되면 다시 내보내세요.
- 크기——너무 큰 이미지는 검증 실패를 일으키거나 요청 본문을 한도 초과로 비대하게 만들 수 있습니다.
- 인코딩——인코딩 데이터를 보낸다면 인코딩이 엔드포인트 기대와 정확히 일치하는지 확인하세요. 불일치하는 접두사나 여분의 공백이 실패를 유발합니다.
작업 수준 실패
제출은 성공했는데 작업이 실패 상태로 끝나면 요청 형식은 올바르지만 생성이 완료되지 않은 것입니다. 프롬프트를 다시 읽고 모호함이나 물리적으로 불합리한 움직임이 있는지 확인하고, 첫 프레임 이미지가 실제로 시작점으로 쓸 수 있는지 확인하세요. 시스템적 문제라고 단정하기 전에 단순화한 프롬프트로 한 번 재시도하고, 나중에 연관 지을 수 있도록 작업 ID와 실패 정보를 기록하세요.
폴링 루프 타임아웃
wait_for_job이 던진 TimeoutError는 작업이 죽은 것이 아니라 한도가 너무 빡빡하다는 의미입니다. 시도 횟수나 간격을 늘리고, 더 이전에 끝난 실행의 task ID를 폴링하고 있지 않은지 확인하세요.
최소 요청—이미지 하나, 짧은 프롬프트, 선택 필드 없음—으로 시작하고, 베이스라인이 동작한 후에만 복잡도를 높이세요. 페이로드가 작고 명확할 때 대부분의 통합 문제는 사라집니다.