튜토리얼
HiAPI API로 pixverse-v6-max 이미지-투-비디오 사용하는 방법: curl, Python 그리고 실제로 동작하는 요청
이 페이지에서
pixverse-v6-max 이미지-투-비디오 엔드포인트가 요구하는 것
HiAPI의 pixverse-v6-max/image-to-video 엔드포인트는 비동기적이며 이미지를 조건으로 하는 비디오 생성 작업입니다. 이 한 문장이 통합 시 내리는 거의 모든 결정을 좌우합니다.
이 엔드포인트는 소스 이미지(첫 프레임)와 생성 파라미터 집합을 받아 완성된 비디오가 아닌 작업 참조를 반환합니다. 실제 렌더링은 서버 측에서 이루어지며, 선택한 파라미터에 따라 몇 초에서 몇 분까지 걸릴 수 있습니다. 클라이언트는 작업을 제출한 뒤 최종 상태를 보고할 때까지 상태를 계속 조회해야 합니다.
동기 이미지 편집과 비교해 보세요: 동기 편집에서는 요청 본문을 POST하면 같은 HTTP 응답에서 변환된 이미지를 받습니다. 여기서의 흐름은 다음과 같습니다:
- 이미지와 파라미터를 생성 엔드포인트로
POST합니다. - 작업 식별자(보통 초기 상태 포함)를 받습니다.
- 완료되거나 실패할 때까지 일정 간격으로 작업 상태를
GET합니다. - 완료된 작업 응답 본문에서 생성된 비디오 URL을 읽습니다.
이런 분리 때문에 두 종류의 오류가 존재합니다: 제출 단계의 문제(인증 오류, 잘못된 요청 본문, 이미지 거부)와 실행 단계의 문제(작업이 수락된 후 실패하거나 정체됨)입니다. 좋은 통합은 두 가지를 모두 명시적으로 처리합니다—구체적인 체크리스트는 뒤의 문제 해결 섹션을 참고하세요.
한 가지 더 명심할 점: 소스 이미지가 기준점입니다. 모델은 이 첫 프레임으로부터 애니메이션을 시작하므로, 이미지 품질, 화면 비율, 내용이 제공하는 어떤 프롬프트 텍스트보다 출력에 큰 영향을 미칩니다. 업로드의 정확성을 사후 고려 사항이 아닌 최우선 관심사로 다루세요.
API 키와 엔드포인트 준비하기
첫 요청을 보내기 전에 필요한 것은 단 두 가지입니다: HiAPI API 키와 해당 엔드포인트의 올바른 기본 URL입니다.
키 발급받기
HiAPI 계정 콘솔에서 API 키를 생성하세요. 비밀번호처럼 다루세요: 소스 코드나 셸 기록이 아니라 환경 변수에 넣으세요.
export HIAPI_API_KEY="your_key_here"
로컬에서 .env 파일을 사용하는 경우, 아무것도 커밋하기 전에 .gitignore에 추가하세요. 공유 로그, 스크린샷, 코드 저장소에 나타난 키는 즉시 교체해야 합니다.
기본 URL과 경로 이해하기
이 엔드포인트는 HiAPI API 호스트 아래에 있으며, 모델 경로는 pixverse-v6-max/image-to-video입니다. 아래 예제에서 기본 URL은 https://api.hiapi.ai로 표시되며, 전체 경로는 이를 결합하여 구성됩니다. 계정이나 리전에 따라 호스트가 다르다면 일관되게 교체하세요—호스트와 키의 불일치는 401의 가장 흔한 원인 중 하나이며, 개발자들은 이를 종종 "잘못된 키"로 오해합니다.
도구 선택하기
- curl은 첫 빠른 검증용입니다—요청 자체 외의 모든 변수를 제거합니다.
- Python 3에
requests(또는httpx)를 사용하는 것이 실제 통합용입니다.
python3 -c "import requests; print(requests.__version__)"
버전 번호가 출력되면 준비된 것입니다. 이 문서의 예제는 SDK 설치가 필요하지 않습니다; 모든 것이 순수 HTTP이며, 이는 나중에 어떤 언어로든 이식할 수 있음을 의미합니다. 키와 호스트를 확인했다면 요청 구성을 시작할 수 있습니다.
curl로 요청 구성하기
실제로 성공할 수 있는 최소 요청부터 시작한 뒤 파라미터를 추가하세요. 아래 요청 본문은 완전한 이미지-투-비디오 제출의 구조를 보여줍니다.
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://your-cdn.example.com/first-frame.jpg",
"duration": 5,
"aspect_ratio": "16:9"
}'
여기서 세 가지가 일어납니다:
- 인증은
Authorization헤더에 bearer 토큰으로 담깁니다. - 요청 본문은 JSON이므로 이미지는 URL 문자열로 제공됩니다(로컬 파일을 전달하는 방법은 다음 섹션 참고).
- 두 가지 생성 파라미터—
duration과aspect_ratio—는 최상위 필드입니다.
성공적인 제출은 작업 식별자를 포함한 JSON 객체를 반환합니다. 이를 캡처하세요:
JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"
그런 다음 폴링하세요:
curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
실패 시 반드시 상태 필드와 원시 오류 응답 본문을 확인하세요. curl은 종료 코드가 0이어도 오류 JSON을 출력할 수 있으므로 스크립트에서는 종료 코드에만 의존하지 마세요.
첫 프레임 이미지를 올바르게 제공하기
소스 이미지는 가장 흔한 실패 지점이며, 거의 모든 거부는 다음 네 가지 원인 중 하나로 귀결됩니다.
1. 이미지에 접근할 수 없음
URL을 전달할 때 HiAPI 서버가 이를 GET할 수 있어야 합니다—그들의 네트워크에서, 당신의 네트워크가 아닙니다. localhost URL, 비공개 버킷, 60초 후 만료되는 서명 URL, VPN 뒤에 있는 엔드포인트는 모두 실패합니다. 공개적으로 읽을 수 있는 객체 스토리지 URL이나 CDN 링크를 사용하고, 쿠키 없는 새 브라우저 세션에서 로드되는지 확인하세요.
2. 지원되지 않는 이미지 형식
표준 웹 형식—JPEG, PNG, WebP—을 고수하세요. 확장자가 특이한 파일, 휴대폰으로 찍은 HEIC, 동적 GIF는 위험합니다. 파이프라인에서 특이한 형식이 생성된다면 먼저 트랜스코딩하세요.
3. 첫 프레임과 선언된 화면 비율 불일치
이 점은 미묘합니다. 소스 이미지가 정사각형인데 16:9를 요청하면 서비스는 입력을 자르거나, 채우거나, 거부해야 합니다. 동작이 다양할 수 있으며, 이 세 가지 중 어느 것도 대부분의 개발자가 원하는 것은 아닙니다. 업로드 전에 직접 자르거나 검은 여백을 추가하여 이미지 기하 구조가 요청할 aspect_ratio와 이미 일치하도록 하세요. 이렇게 하면 출력이 예측 가능해지고 작업을 낭비하지 않습니다.
4. 이미지가 너무 크거나 너무 작음
매우 높은 해상도의 정지 이미지(예: 8K 카메라 출력)는 대역폭을 소모하고 거부되거나 다운샘플링될 수 있으며, 아주 작은 썸네일은 모델이 애니메이션할 내용을 거의 남기지 않습니다. 업로드 전 단계의 일부로 이미지를 합리적인 긴 변 크기로 정규화하세요.
로컬 파일 전달하기
엔드포인트가 이미지 필드에 multipart 업로드를 허용한다면 패턴은 다음과 같습니다:
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-F "image=@./first-frame.jpg" \
-F "duration=5" \
-F "aspect_ratio=16:9"
multipart를 사용하면 숫자 필드가 문자열이 된다는 점에 유의하세요. 어떤 콘텐츠 타입이 허용되는지는 엔드포인트 참조 문서를 확인하고, 프로덕션 파이프라인에서는 URL 형식을 선호하세요—이렇게 하면 대용량 바이너리 파일이 애플리케이션 서버에 전혀 나타나지 않습니다.
길이와 화면 비율 설정하기
이 두 필드는 요청 본문의 어떤 다른 내용보다 비용과 출력에 큰 영향을 미칩니다.
duration
duration은 초 단위이며 생성 클립의 길이를 나타냅니다. 또한 청구와 가장 직접적으로 관련된 필드입니다—실시간 가격은 요청한 출력 길이에 따라 계산되므로 최댓값을 기본으로 삼지 말고 신중하게 선택하세요. 실용적인 조언:
- 이야기를 전달하는 가장 짧은 길이부터 시작하세요. 5초 클립은 반복 재생, 제품 예고, 소셜 훅에 적합합니다.
- 장면이 실제로 더 긴 시간이 필요할 때만 더 긴 길이를 사용하세요; 정적인 첫 프레임을 오래 애니메이션하면 종종 표류하며 일관성을 잃습니다.
- 클라이언트에서 검증하세요: 요청이 서비스를 떠나기 전에 비정수, 0, 음수, 터무니없이 큰 값을 거부하세요.
if not isinstance(duration, int) or not 1 <= duration <= 8:
raise ValueError("duration out of supported range")
현재 지원되는 범위는 엔드포인트 참조 문서에서 확인하고 검증 로직에 반영하세요—이 문서의 가정을 하드코딩하지 마세요.
aspect_ratio
aspect_ratio는 "16:9", "9:16", "1:1" 같은 문자열입니다. 출력 화면의 기하 구조를 제어합니다.
16:9는 가로: YouTube, 웹 히어로 비디오, 데스크톱 재생.9:16은 세로: Reels, Shorts, TikTok 스타일 게재.1:1은 피드와 썸네일.
두 가지 규칙으로 문제를 피할 수 있습니다. 첫째, 소스 이미지를 요청 비율과 일치시키세요—가로 요청에 세로 첫 프레임을 사용하면 아마 원하지 않을 자르기가 발생합니다. 둘째, 비율을 자유 텍스트가 아닌 열거형으로 취급하세요: 화이트리스트로 검증하면 "16x9" 같은 오타가 한 번의 왕복 후가 아니라 코드에서 빠르게 실패합니다.
그 외 모든 것
엔드포인트가 추가 생성 제어를 노출한다면 첫 요청에서는 제외하세요. 최소의 검증된 요청 본문이 기준선이며, 한 번에 하나의 파라미터만 추가하고 출력을 비교하세요. 이 규율이 어떤 필드가 회귀를 일으켰는지 명확하게 만듭니다.
Python으로 같은 요청 구현하기
아래는 curl 흐름을 Python으로 번역한 버전입니다. 의도적으로 의존성을 최소화했습니다: requests와 표준 라이브러리.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
resp = requests.post(
f"{BASE}/v1/pixverse-v6-max/image-to-video",
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def fetch(job_id: str) -> dict:
resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job_id = submit("https://your-cdn.example.com/first-frame.jpg")
print("submitted", job_id)
참고할 만한 의도적인 선택:
- 제출 시
raise_for_status()호출.400이나401은 오류 응답 본문에서["id"]를 읽으려 할 때KeyError가 되는 것이 아니라 즉시 예외로 드러나야 합니다. - 명시적 타임아웃. 타임아웃이 없으면 정체된 연결이 워커를 무한정 매달리게 합니다.
- 환경에서 설정 읽기. 기본 URL과 키는 코드에 하드코딩하지 않습니다.
- 작고 타입이 있는 헬퍼 함수.
submit은 작업 id 문자열을 반환하고fetch는 딕셔너리를 반환합니다. 파싱을 한 곳에 집중하면 스키마 변경 시 한 줄만 수정하면 됩니다.
httpx를 선호한다면 httpx.post(...)와 httpx.get(...)로 바꾸면 됩니다; 호출은 다른 면에서 완전히 동일합니다. 웹 요청 핸들러 내부에서 실행되는 모든 것의 경우 여기서 제출한 뒤 작업 id를 백그라운드 워커에 넘기세요; 사용자의 HTTP 요청이 비디오 생성에 블로킹되지 않도록 하세요.
비동기 작업이 완료될 때까지 폴링하기
폴링은 대부분의 튜토리얼이 대충 넘어가는 부분이자 대부분의 사고의 원인입니다. 루프 자체는 짧습니다; 그 주변의 규율이 핵심입니다.
def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
job = fetch(job_id)
status = job.get("status")
if status == "completed":
return job["output"]["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish within {timeout}s")
위 코드에 담긴 핵심:
- 항상 마감 시간을 설정하세요. 비디오 생성은 느립니다; 무한 루프는 무한 청구와 멈춘 워커가 됩니다. 짧은 클립의 경우 10분이 합리적인 상한입니다—길이 설정에 맞게 조정하세요.
- 최종 상태를 구분하세요.
completed만 URL을 생성합니다.failed와cancelled도 최종 상태입니다—폴링을 멈추고 error 필드를 노출하세요. - 합리적인 간격을 사용하세요. 몇 초마다면 충분합니다. 상태 엔드포인트를 마구 폴링하면 속도 제한에 걸리고 새로운 정보도 얻지 못합니다.
- 긴 작업에는 온화한 백오프: 첫 1분 후 간격을 3초에서 10초로 늘리세요. 이는 당신에게 지연 비용을 추가하지 않고 부하를 줄입니다.
- 작업 id를 영속화하세요. 자체 기록과 함께 저장하여 프로세스가 재시작되면 동일한 작업을 다시 제출하고 다시 결제하지 않고 폴링을 재개할 수 있도록 하세요.
- 절대 브라우저에서 API 키로 직접 폴링하지 마세요. 백엔드를 통해 상태 확인을 프록시하세요.
작업이 완료되면 반환된 URL에 영원히 연결하는 대신 비디오를 자체 스토리지에 즉시 다운로드하세요; 생성된 자산 URL은 영구적으로 유효하다고 보장되지 않습니다.
실패하고 정체된 작업 문제 해결하기
이 체크리스트를 순서대로 수행하세요. 각 단계는 하나의 계층을 분리합니다.
제출 오류(작업이 생성되지 않음)
401 Unauthorized— 키 누락, 형식 오류, 취소됨, 또는 잘못된 호스트와 페어링됨. 헤더가 정확히Authorization: Bearer <key>인지, 중간에 공백이 하나뿐인지, 환경 변수에 추가 개행이 없는지 확인하세요.403 Forbidden— 키는 유효하지만 이 모델이나 엔드포인트에 허용되지 않습니다. 리소스 경로를 문자 단위로 확인하세요:pixverse-v6-max/image-to-video.400 Bad Request— JSON 형식이 잘못되었거나 필드가 유효하지 않습니다. 오류 응답 본문을 디코드하세요; 보통 문제 필드를 지적합니다. 흔한 원인:duration이 숫자가 아닌 문자열,"16:9"대신"16x9",image누락.422류 검증 오류 — 필드는 존재하지만 범위를 벗어남. 추측하지 말고 엔드포인트 참조 문서와 대조하세요.429 Too Many Requests— 너무 빠르게 제출했습니다. 제출을 큐에 넣고 지터를 포함한 지수 백오프로 재시도하세요; 절대 타이트 루프에서 재시도하지 마세요.
실행 실패(작업이 생성되었지만 성공하지 못함)
- 이미지 관련 오류와 함께 상태
failed— 제출 후 소스 URL 가져오기가 실패했습니다. 이는 전형적인 "내 브라우저에서는 되는데" 함정입니다: URL에 쿠키, 리퍼러, IP 화이트리스트가 필요할 수 있습니다. 이미지를 공개적으로 다시 호스팅하세요. - 콘텐츠 또는 검증 오류와 함께 상태
failed— 소스 이미지가 기술적 이유(형식, 기하 구조, 크기)로 거부되었습니다. 트랜스코딩하고 크기를 조정하고 선언된 화면 비율로 다시 자르세요. - 마감 시간 이후에도 작업이 큐 또는 처리 중으로 멈춤 — 먼저 올바른 작업 id를 읽고 있는지 확인하세요(복사-붙여넣기 오류가 의외로 흔합니다). 그런 다음 상태가 실제로 변하지 않았는지, 또는 폴링이 잘못된 기본 URL로 가는지 확인하세요. 정말로 정체되었다면 API가 허용하는 경우 한 번 취소하고 다시 제출하세요; 조용히 반복 재제출하는 것이 바로 예산이 사라지는 방식입니다.
시간을 절약하는 습관
모든 호출에 대해 전체 요청 id, 작업 id, HTTP 상태, 응답 본문을 기록하세요—키는 마스킹하세요. 새벽 2시에 문제가 생겼을 때, 요청 id 하나가 5분 수정과 1시간 추측의 차이를 만듭니다. 최소의 검증된 요청 본문부터 시작하여 한 번에 하나의 파라미터를 추가하면 이 체크리스트가 거의 필요 없을 것입니다.