튜토리얼
HiAPI API로 veo-3.1/image-to-video 호출하기: curl 및 Python 튜토리얼
이 페이지에서
veo-3.1 이미지-투-비디오 엔드포인트가 기대하는 것
첫 줄의 코드를 작성하기 전에 이것이 어떤 종류의 호출인지 파악하는 것이 도움이 됩니다. veo-3.1/image-to-video는 프롬프트를 보낸 그 HTTP 응답에서 바로 비디오를 반환하지 않습니다. 이는 비동기 작업 엔드포인트입니다: 원하는 비디오를 설명하면 플랫폼이 작업을 접수하고, 나중에 다시 와서 결과를 조회합니다.
개념적으로 하나의 요청은 완전히 구분되는 두 부분으로 구성됩니다:
- 첫 프레임 이미지. 생성되는 비디오의 시작 정지 프레임입니다. 오프닝 순간의 구도, 피사체, 느낌을 고정합니다. 이후의 모든 내용은 이 시작점에서부터 모델이 생성합니다.
- 생성 옵션. 비디오가 어떻게 생성될지 제어하는 파라미터입니다—예를 들어 오디오 생성 여부, 출력 해상도, 클립 길이 등입니다.
이 분리가 중요한 이유는 두 가지입니다. 첫째, 장애를 더 쉽게 추론할 수 있게 합니다: 이미지 문제는 파라미터 문제와 다르게 보이며, 두 가지를 구분할 수 있기를 원합니다. 둘째, 코드도 같은 방식으로 구성해야 함을 의미합니다—일부 로직은 이미지 준비를, 다른 부분은 옵션 집합 구성을 담당합니다.
호출자는 최소한 다음을 제공해야 합니다: 유효한 첫 프레임 이미지, 그리고 오디오, 해상도, 길이에 대한 결정. 나머지 모든 것—작업 제출, 상태 추적, 최종 비디오 반환—은 플랫폼의 작업 수명 주기가 처리합니다. 통합은 세 가지만 하면 됩니다: 형식이 올바른 요청을 보내고, 반환된 작업 식별자를 기억하고, 작업이 종료 상태에 도달할 때까지 폴링합니다.
계속하기 전에 실용적인 팁 하나: 호출이 비동기이므로 코드는 제출 후 비디오가 즉시 사용 가능하다고 가정할 수 없습니다. 처음부터 이 점을 염두에 두고 흐름을 설계하면 이후 튜토리얼이 자연스럽게 이어집니다.
두 부분으로 된 사고 모델
다음 섹션을 읽을 때 이 프레임워크를 유지하세요:
- 입력 → 준비 및 검증된 첫 프레임 이미지.
- 옵션 → 오디오, 해상도, 길이.
- 작업 → 제출, 식별자 획득, 폴링, 가져오기.
아래의 각 섹션은 이 상자 중 하나에 대응합니다.
첫 프레임 이미지 준비
첫 프레임 이미지는 이미지-투-비디오 호출에서 가장 중요한 단일 입력이므로, 요청 빌더 안에 묻어두지 말고 파이프라인에서 전용 단계로 만드세요. API 호출이 해당 이미지를 참조할 수 있어야 하며, 이는 이미지가 플랫폼이 허용하고 읽을 수 있는 형태여야 함을 의미합니다.
전송 전에 확인할 것
- 이미지가 실제로 열리는지. 잘린 다운로드나 손상된 파일은 다운스트림에서 혼란스러운 실패를 일으키는 가장 흔한 원인입니다. 아무것도 보내기 전에 정상적으로 디코딩되는지 확인하세요.
- 형식이 플랫폼에서 허용되는지. 출처가 스크린샷, 휴대폰 사진, 디자인 도구 내보내기 파일이라면 업로드 전에 널리 지원되는 형식으로 정규화하세요. 미리 한 번 변환하는 것이 나중에 디버깅하는 것보다 수월합니다.
- 크기가 적절한지. 매우 작거나 과도하게 늘어난 이미지는 모델에 제공할 재료가 거의 없습니다. 출처가 너무 작다면 업스케일링을 고려하거나 더 나은 프레임을 선택하세요.
- 구도가 좋은 시작점인지. 이것은 첫 프레임이므로 생성되는 움직임이 여기서부터 이어집니다. 피사체가 명확히 보이고, 클립 시작 부분에서 그 구도를 보게 되어 만족스러운 프레임을 선택하세요.
옵션과 분리 유지하기
코드를 구성할 때 이미지 준비가 요청 빌더에 넘길 수 있는 참조를 반환하도록 하고, 이미지 처리와 파라미터 조립을 섞지 마세요. 구체적으로:
# 의사 코드 구조, 완전한 클라이언트 아님
def prepare_first_frame(path):
image = load_and_validate(path) # 디코딩, 형식 확인, 크기 확인
ref = upload_or_encode(image) # API 호출이 참조할 수 있는 것 생성
return ref
def build_request(first_frame_ref, options):
return {
"first_frame": first_frame_ref,
# 오디오 / 해상도 / 길이를 여기에 배치
}
이 분리는 디버깅할 때 보답합니다. 작업이 실패하면 prepare_first_frame만 단독으로 다시 실행하여 생성 파라미터를 건드리기 전에 이미지 측이 정상인지 확인할 수 있습니다.
가능한 한 빨리 검증하고 크게 실패하기
자체 측에서 검증을 완료하고, 실패 시 명확한 오류를 발생시키세요. 형식이 잘못되었거나 읽을 수 없는 이미지는 절대 네트워크에 도달해서는 안 됩니다—로컬에서 잡으면 모호한 비동기 작업 실패를 직접 작성한 정밀하고 즉각적인 예외로 바꿀 수 있습니다.
생성 옵션 설정: 오디오, 해상도, 길이
이미지 처리가 끝나면 남은 결정은 생성 옵션입니다. 이는 출력의 성격을 바꾸므로 요청 본문에 묻힌 매직 값이 아니라 명시적이고 이름이 붙은 파라미터로 다루어야 합니다.
오디오
오디오 옵션은 생성된 비디오에 오디오 트랙이 포함되는지 제어합니다. 이는 기술적 결정이자 제품적 결정입니다:
- 비디오가 무음으로 삽입되는 경우—배경 루프, 자동 재생 히어로 비주얼—일반적으로 오디오가 필요 없으며, 생략하면 다운스트림 처리가 더 단순해집니다.
- 클립이 소리와 함께 독립적으로 제시되는 경우—짧은 소셜 콘텐츠, 데모—오디오를 활성화하여 한 번의 호출로 완전한 자산을 얻으세요.
무작정 기본값을 채택하지 말고 사용 사례에 따라 의도적으로 결정하세요; 이는 출력과 해당 파일을 다운스트림 파이프라인이 처리하는 방식 모두에 영향을 줍니다.
해상도
해상도는 최종 비디오의 픽셀 크기를 결정합니다. 단순히 "사용 가능한 최대값"을 선택하지 말고, 비디오가 어디에 표시될지와 콘텐츠에 필요한 디테일 수준에 따라 선택하세요. 작은 임베디드 플레이어용으로 렌더링되는 클립을 디스플레이 패널 능력을 훨씬 뛰어넘는 크기로 생성하는 것은 이점이 없습니다. 플랫폼이 지원되는 값 집합을 발표했다면 그중에서 명시적으로 선택하고, 클라이언트에서 이에 따라 검증하여 지원되지 않는 값이 빠르게 실패하도록 하세요.
길이
길이는 생성되는 클립의 길이를 설정합니다. 이는 콘텐츠 기획과 상호작용합니다: 먼저 장면을 설정한 다음 움직임을 보여주어야 하는 샷은 단일 제스처보다 더 많은 시간이 필요합니다. 이는 가장 계량화되기 쉬운 파라미터 중 하나라는 점에 유의하세요—플랫폼의 청구는 생성된 출력을 기준으로 설명되므로, 배치 요청 시 클립이 얼마나 긴지 주의하세요.
옵션을 하나의 객체로 조립하기
세 가지를 같은 옵션 구조에 넣어 살펴볼 곳 한 곳, 수정할 곳 한 곳만 있게 하세요:
options = {
"audio": True, # 오디오 트랙 생성
"resolution": "...", # 지원되는 값 중 하나
"duration": 8, # 생성 비디오의 초
}
귀하의 계정과 현재 엔드포인트 문서에서 지원된다고 명시된 값을 사용하세요—하드코딩된 추측이 아니라 문서에서 읽고, 요청 구성 시 검증하여 잘못된 값이 실패한 작업이 되지 않도록 하세요.
curl로 작업 제출하기
이제 두 부분을 합치고 제출하세요. 명령줄에서 시작하는 것이 좋은데, curl은 요청 형태를 보이게 하고 코드를 작성하기 전에 변경 사항을 빠르게 테스트할 방법을 제공하기 때문입니다.
요청
제출 요청은 구조적으로 다음과 같습니다—자리 표시자 값을 귀하의 자격 증명, 이미지 참조, 옵션 값으로 교체하세요:
curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_frame": "<업로드 단계의 이미지 참조>",
"audio": true,
"resolution": "<지원되는 값>",
"duration": 8
}'
익혀둘 만한 몇 가지 관례:
- 키를 명령에 붙여넣지 말고 환경 변수(
$HIAPI_API_KEY)에 두세요. 이 습관은 Python 코드로 그대로 이어지며 키를 셸 기록에서 멀리 유지합니다. - 명시적
Content-Type헤더로 JSON을 보내세요. - 요청 본문에서 이미지 참조를 숫자 및 불리언 옵션과 분리하여 첫 섹션의 두 부분 모델을 반영하세요.
응답 읽기
비동기 엔드포인트이므로 성공 응답은 비디오가 아닙니다. 이는 작업이 접수되었음의 확인일 뿐이며, 추적에 필요한 정보—가장 중요하게는 작업 식별자, 보통은 작업이 대기열에 있거나 실행 중임을 나타내는 상태 필드—를 담고 있습니다.
두 단계로 읽으세요. 먼저 HTTP 상태가 클라이언트 오류가 아닌 접수를 의미하는지 확인합니다. 그다음 응답 본문을 파싱하여 작업 식별자를 추출합니다:
curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | tee submit.json
응답을 submit.json에 기록하면 검사할 것이 생기고 폴링 단계로 넘길 수 있습니다. 제출이 실패하면 오류 응답 본문이 첫 번째이자 최선의 단서입니다—이미지 참조를 가리키는지 아니면 특정 옵션을 가리키는지 확인하고, 그 절반만 수정한 뒤 다시 제출하세요.
비디오가 준비될 때까지 비동기 작업 폴링하기
작업 식별자를 얻으면 워크플로는 반복문이 됩니다: 플랫폼에 작업 상태를 묻고, 작업이 종료 상태에 들어가면 멈춥니다.
수명 주기
이미지-투-비디오 작업은 소수의 상태를 거칩니다. 접수되어 대기열에 들어간 다음 처리되며, 최종적으로 성공하여 비디오를 산출하거나 실패하여 오류를 제공합니다. 폴링 코드는 세 가지만 구분하면 됩니다:
- 아직 처리 중—계속 기다립니다.
- 성공—출력 위치를 읽고 비디오를 다운로드하거나 저장합니다.
- 실패—중지하고 오류를 발생시킵니다.
책임감 있게 폴링하기
두 가지 습관이 폴링을 더 견고하게 만듭니다:
- 확인 사이에 기다리세요. 촘촘한 반복문으로 상태 엔드포인트를 두드리는 것은 요청을 낭비하고 얻는 것이 없습니다; 생성에는 실제 시간이 걸립니다. 고정 간격이나 부드러운 백오프를 사용하세요.
- 마감 시간을 설정하세요. 무한히 폴링하지 마세요. 최대 시도 횟수나 최대 경과 시간을 선택하고, 초과하면 명확히 보고할 수 있는 실패로 간주하세요.
# 폴링 루프 스케치
for i in $(seq 1 60); do
status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
-H "Authorization: Bearer $HIAPI_API_KEY")
echo "$status"
# 상태 필드가 성공 또는 실패를 보고하면 탈출
sleep 5
done
정확한 상태 문자열과 엔드포인트 경로는 스크립트에 고정된 가정이 아니라 현재 API 문서와 대조하여 확인할 사항으로 취급하세요.
성공 시
작업이 성공을 보고하면 응답은 최종 비디오의 위치를 담고 있습니다. 신속히 다운로드하여 영구 위치에 저장하세요—비동기 플랫폼의 작업 결과는 훨씬 나중에 지연 로딩할 것이 아니라 지금 가져와야 할 것으로 취급해야 합니다. 작업 식별자를 저장된 파일과 함께 기록하여 모든 출력이 이를 생성한 요청으로 추적될 수 있도록 하세요.
Python에서의 동일한 요청
Python 버전은 두 번째 구현이 아니라 한 번 표현하고 재사용하는 동일한 요청이어야 합니다. 목표는 이전에 검증한 동일한 이미지 참조와 동일한 옵션 객체로 구성된, 제출과 폴링을 수행하는 단일 함수입니다.
하나의 요청 본문, 하나의 클라이언트
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
})
def build_body(first_frame_ref, options):
return {"first_frame": first_frame_ref, **options}
def submit(body):
r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
r.raise_for_status()
data = r.json()
return data["job_id"]
def poll(job_id, interval=5, max_attempts=60):
for _ in range(max_attempts):
r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
r.raise_for_status()
data = r.json()
state = data.get("status")
if state in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"작업 {job_id}이(가) 제때 완료되지 않았습니다")
def image_to_video(first_frame_ref, options):
job_id = submit(build_body(first_frame_ref, options))
result = poll(job_id)
if result["status"] == "failed":
raise RuntimeError(result.get("error", "작업 실패"))
return result # 최종 비디오 위치 포함
왜 이 형태인가
- 하나의
Session. 세션을 재사용하면 인증 헤더를 한 곳에 두고 제출과 각 폴링 사이에 연결을 재사용합니다. - 하나의
build_body. curl 요청과 Python 요청은 동일한 요청 본문입니다—같은 키, 같은 값. 옵션을 수정할 때 한 곳에서만 수정합니다. - 명시적 타임아웃과 마감 시간. 두 호출 모두 타임아웃을 설정하고
poll은 시도 횟수 제한이 있어, 정체된 작업이 프로세스를 매달리게 하지 않습니다. - 실패는 크게 드러납니다. 제출 시
raise_for_status가 요청 수준 오류를 즉시 잡고,image_to_video의 명시적 실패 분기가 작업 수준 실패를 잡습니다.
나중에 같은 플랫폼을 통해 다른 모델을 호출해야 한다면 이 구조는 일반화될 수 있습니다: 세션, 제출 헬퍼, 폴링 헬퍼는 그대로 유지되고 엔드포인트와 요청 본문 빌더만 바뀝니다.
실패한 이미지-투-비디오 호출 문제 해결하기
호출이 비디오를 산출하지 못할 때는 어느 단계에서 실패했는지 물어 범위를 좁히세요. 두 부분 요청 모델이 명확한 체크리스트를 제공합니다.
1단계: 제출이 거부됨
제출 호출 자체가 오류를 반환하면 아무것도 생성되지 않았습니다—이는 문제가 요청에 있으므로 좋은 소식입니다.
- 이미지 참조 문제. 가장 흔한 단일 원인입니다. 이미지 준비 단계를 단독으로 다시 실행하여 유효하고 읽을 수 있으며 형식이 올바른 이미지와 API가 허용하는 참조를 산출하는지 확인하세요. 잘린 업로드와 지원되지 않는 형식을 먼저 확인하세요.
- 유효하지 않은 옵션 값. 지원되지 않는 해상도나 범위를 벗어난 길이는 제출 시 거부됩니다. 보내기 전에 문서의 지원 값과 대조하여 옵션을 검증하세요.
- 인증 및 헤더. 키가 실제로 전송되는지(
Authorization: Bearer ...), 요청 본문이 JSON으로 전송되는지 확인하세요. curl에서 수동으로 요청을 구성할 때 비어 있거나 잘못된 본문은 쉽게 간과됩니다.
2단계: 작업이 제출되었지만 실패함
제출이 접수되었으나 폴링이 실패로 끝나면 요청 형식은 올바르고 문제는 내용이나 작업 자체에 있습니다.
- 작업 오류를 읽으세요. 실패 응답은 추측보다 어디가 잘못되었는지 더 잘 설명합니다. 그대로 기록하세요.
- 첫 프레임을 살펴보세요. 명확한 피사체가 없거나, 극단적으로 잘렸거나, 심하게 왜곡된 소스 이미지는 모델에 제공할 재료가 거의 없습니다. 더 깔끔한 프레임으로 교체하고 재시도하세요.
- 옵션을 재고하세요. 매우 긴 길이나 특이한 설정 조합은 더 단순한 구성으로 재테스트하여 어떤 파라미터가 문제인지 분리해볼 가치가 있습니다.
3단계: 폴링이 끝나지 않음
반복문이 실패가 아니라 타임아웃되면 콘텐츠 문제가 아니라 인프라 문제로 취급하세요. 올바른 작업 식별자를 폴링하고 있는지, 간격이 너무 공격적이지 않은지, 마감 시간이 요청된 길이에 충분히 긴지 확인하세요. 제출 시 작업 식별자를 기록하세요—그것 없이는 정체된 작업을 조사할 수 없습니다.
효과적인 디버깅 절차
문제가 생기면 이 순서로 진행하세요: 로컬에서 이미지를 검증하고, 다시 제출하고 원시 응답을 캡처하고, 작업 오류가 나타나면 확인하고, 그런 다음 옵션을 단순화하여 재시도하세요. 각 단계는 요청의 정확히 절반을 테스트하므로, 코드에서 이미지와 생성 파라미터를 분리하는 것이 정확히 문제 발생 시 보답합니다.
이제 전체 순환을 갖추었습니다: 첫 프레임을 준비하고, 오디오, 해상도, 길이를 설정하고, 비동기로 제출하고, 완료까지 폴링합니다—curl이든 Python이든 실행되는 동일한 요청입니다.