튜토리얼
HiAPI API를 통해 minimax-h3-max-turbo 텍스트 투 비디오를 호출하는 방법
- 모델
- minimax-h3-max-turbo
이 페이지에서
이 엔드포인트의 기능과 적용 시나리오
minimax-h3-max-turbo/text-to-video는 HiAPI API로 노출된 텍스트 투 비디오 모델 엔드포인트입니다. 목표 장면을 설명하는 텍스트 프롬프트와 출력 형태를 제어하는 소수의 파라미터를 보내면 HiAPI가 생성된 비디오를 반환합니다. 텍스트 설명은 있지만 소스 소재가 없을 때 이 모델이 매우 적합합니다: 마케팅 단편, 소셜 미디어 전환 장면, 스토리보드 미리보기, 앱 배경 루프 비디오, 또는 동일한 창의적 콘셉트의 대량 변형 생성 등입니다.
코드를 작성하기 전에 몇 가지 특성을 알아두는 것이 좋습니다:
- 템플릿이 아니라 생성 엔드포인트입니다. 출력은 구조적으로만 예측 가능하며(비디오를 받습니다), 내용 자체는 예측할 수 없습니다. 매 작업을 완전히 새로운 렌더링으로 간주하고 재사용성을 중심으로 프롬프트를 설계하세요.
- 비동기입니다. 작업 제출 호출은 완성된 비디오 바이트를 직접 반환하지 않습니다. 먼저 작업 핸들을 받은 다음 결과를 폴링합니다. 동기 응답을 가정하는 모든 통합 방식은 첫 타임아웃에서 실패합니다.
- 출력은 요청 파라미터로 결정됩니다. 길이와 해상도는 렌더링 비용과 실제 소요 시간을 바꾸므로, 선택하는 파라미터는 곧 지연 시간과 예산 결정입니다.
- 소스 미디어가 필요 없습니다. 비디오나 이미지를 업로드할 필요가 없으며, 프롬프트와 파라미터가 전부 입력면입니다.
언제 다른 방식을 써야 할까요? 이미 소재가 있고 스타일을 다시 입히거나 확장하고 싶다면 이 엔드포인트는 적합하지 않습니다. 카메라 움직임이나 정확한 구도에 프레임 단위 제어가 필요하다면 텍스트 프롬프트는 너무 느슨합니다. 정적 이미지 하나만 필요하다면 텍스트 투 이미지 엔드포인트가 더 저렴하고 빠릅니다. 프롬프트가 장면 명세로 충분할 때 minimax-h3-max-turbo/text-to-video를 사용하세요.
이 가이드의 나머지 부분에서는 인증, 실행 가능한 curl 호출, 동등한 Python 호출, 작업 수명 주기, 주요 파라미터, 마주치게 될 오류, 그리고 출시 전 강화 단계를 차례로 소개합니다.
전제 조건과 인증
첫 요청 전에 세 가지를 준비해야 합니다:
- HiAPI 계정의 API 키. 기밀 정보로 취급하세요: 환경 변수에서 로드하고 절대 코드베이스에 커밋하지 말며, 유출되면 즉시 교체하세요.
- HiAPI 기본 URL. 이 가이드의 모든 호출은 동일한 기본 호스트로 전송됩니다. 모델은 각 모델마다 다른 도메인이 아니라 경로 세그먼트로 선택됩니다.
- HTTP 클라이언트. 스모크 테스트에는 curl, 서비스 코드에는 임의의 표준 라이브러리 또는 HTTP 클라이언트를 사용하세요.
키 전달 방식
HiAPI는 Authorization 요청 헤더의 bearer token으로 요청을 인증합니다. 형식은 항상 일관됩니다:
export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
두 가지 습관이 디버깅 시간을 크게 절약합니다:
- 헤더 철자가 정확해야 합니다.
Authorization의 A는 대문자,Bearer뒤에 공백 하나, 그다음 키입니다. 공백 하나 빠짐은 신비한 401의 가장 흔한 원인입니다. - 항상
Content-Type: application/json을 보내세요. JSON을 기대하는 서버는 이 헤더가 없는 요청 본문을 거부하거나 잘못 파싱하며, 받는 오류는 종종 진짜 원인이 아니라 특정 필드가 누락되었다고 말합니다.
개발 전에 먼저 검증하세요
처음부터 비디오 엔드포인트를 쓰지 마세요. 먼저 저렴하고 빠른 호출로 키와 기본 URL이 올바르게 해석되는지 확인한 후 진행하세요. 이 정상성 검사가 실패하면 다운스트림의 모든 것이 작동하지 않으며, 잘못된 계층에서 디버깅하게 됩니다. 키를 코드베이스의 한 곳—작은 클라이언트 모듈—에 두면 나중에 교체가 한 줄 수정으로 끝납니다.
실행 가능한 curl 요청
제출 호출은 프롬프트와 파라미터를 JSON 요청 본문으로 모델 경로에 보냅니다. 다음은 최소 실행 가능한 호출입니다:
curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "일출 무렵, 안개 낀 소나무 숲을 천천히 지나가는 공중 돌리인 샷, 부드러운 볼류메트릭 광, 시네마틱",
"duration": 5,
"resolution": "720p"
}'
각 부분의 역할:
-X POST—— 생성 작업은 POST로 생성됩니다.- URL —— 기본 호스트에
minimax-h3-max-turbo/text-to-video경로를 더한 것입니다. 기본 호스트를 변수에 두면 테스트와 프로덕션이 동일한 코드 경로를 가리킬 수 있습니다. Authorization—— 이전 섹션에서 설명한 bearer token입니다.Content-Type—— JSON 요청 본문임을 선언합니다.prompt—— 유일하게 필수인 창의적 입력입니다. 장면 설명처럼 작성하세요: 주체, 카메라 동작, 조명, 분위기. 짧은 명사구는 모호한 결과를 낳고, 구체적인 시각적 방향을 담은 한두 문장이 훨씬 좋습니다.duration과resolution—— 출력 형태를 제어하는 파라미터로, 아래에 별도 섹션이 있습니다.
-sS를 사용하면 curl이 조용히 실행되면서도 오류는 출력하며, 탐색 단계에서는 예쁜 출력 도구로 응답을 출력하세요. 응답은 작업 식별자를 포함한 JSON입니다. 저장하세요. 완성된 비디오를 폴링하는 데 필요합니다. 이 응답에 비디오 바이트가 포함될 것이라고 기대하지 마세요.
디버깅 시 실제로 무엇이 전송되었는지 보고 싶다면 -v를 추가해 상세 출력을 받으세요. 하지만 로그를 공유하기 전에 제거하세요. 상세 출력에 헤더가 포함될 수 있습니다.
동등한 Python 요청
Python 버전은 동일한 요청이며, 환경에서 키를 로드하고 응답을 파싱할 뿐입니다. 다음은 작은 재사용 가능 클라이언트입니다:
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"
def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
resp = requests.post(
f"{BASE_URL}{MODEL_PATH}",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job = submit_video(
"일출 무렵, 안개 낀 소나무 숲을 천천히 지나가는 공중 돌리인 샷, 부드러운 볼류메트릭 광, 시네마틱"
)
print(job)
적용 시 주의 사항:
json=payload는 요청 본문과 콘텐츠 유형을 동시에 설정합니다. 수동으로 직렬화하지 마세요.timeout=30은 제출 호출의 시간을 제한합니다. 제출은 빠르고 렌더링은 빠르지 않으므로, 여기서는 타임아웃을 짧게 두고 폴링이 대기를 담당합니다.raise_for_status()는 비 2xx 응답을 예외로 바꿔 인증 및 검증 실패가 즉시 드러나게 합니다. 그렇지 않으면 오류 응답 본문이 조용히 반환되어 나중에 작업으로 오해하고 파싱하게 됩니다.- 파싱된 JSON을 딕셔너리로 반환하고 호출 지점에서 작업 식별자를 추출하세요. 이렇게 하면 헬퍼 함수는 범용으로 유지되고 오케스트레이션 코드가 처리 방법을 결정합니다.
비동기 스택을 사용한다면 동일한 형태가 선택한 HTTP 클라이언트에 적용됩니다: 헤더를 한 번 만들고, 본문을 POST하고, 상태를 확인하고, 파싱된 응답 본문을 반환합니다.
비동기 작업 수명 주기 처리
생성에는 시간이 걸리므로 엔드포인트는 제출과 폴링으로 나뉩니다. 수명 주기는 항상 다음과 같습니다: 제출하고, 작업 식별자를 받고, 작업이 종료 상태를 보고할 때까지 폴링한 다음, 출력을 가져옵니다.
제출
앞서 설명한 POST를 보내고 응답에서 작업 식별자를 읽으세요. 즉시 기록하고 자체 요청 ID와 연결하세요. 그러면 나중에 폴링이 실패할 때 원래 프롬프트로 추적할 수 있습니다.
백오프를 동반한 폴링
타이트한 루프로 폴링하지 마세요. 짧은 간격으로 시작해 백오프하세요:
def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
deadline = time.time() + max_wait
interval = 2.0
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}{MODEL_PATH}/{job_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
status = job.get("status")
if status in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 15.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
세 가지 세부 사항이 이 코드를 신뢰할 수 있게 만듭니다. 첫째, 마감 시간: 항상 결국 포기하고 타임아웃을 던져야 하며, 영원히 폴링하지 마세요. 둘째, 상한이 있는 백오프: 몇 초로 시작해 점차 배수하고 간격을 상한으로 제한하면 꾸준히 진행하면서도 API를 자주 때리지 않습니다. 셋째, 종료 상태 처리: 성공과 실패만 종료 상태로 간주하고 작업 객체를 반환해 호출자가 분기 처리하게 하세요.
결과 가져오기
작업이 성공을 보고하면 응답에 완성된 비디오의 위치가 담깁니다. 가능한 한 빨리 자체 저장소로 다운로드하거나 스트리밍하고, URL을 작업 ID와 함께 기록하세요. 링크가 영구적이라고 가정하지 말고, 각 폴링 반복에서 비디오를 가져오지도 마세요. 작업 상태를 폴링하고, 성공 시 한 번만 가져오세요.
길이와 해상도 파라미터
두 요청 파라미터가 출력을 결정하며, 동시에 렌더링 시간과 호출 비용도 결정합니다.
duration
생성되는 클립의 길이입니다. 클립이 길수록 렌더링 시간이 비례해 늘어나며, 이는 더 긴 폴링 창과 클라이언트 타임아웃 발생 확률 증가를 의미합니다. 실용적 조언:
- 길이를 사용 사례에 맞추세요. 소셜 미디어 전환 장면은 짧고, 배경 루프는 수용 가능하게 순환할 수 있을 만큼만 길면 됩니다. 실제로 보여줄 것보다 긴 내용을 생성하는 것은 순수한 낭비입니다.
- 반복할 때는 작게 시작하세요. 짧은 길이로 프롬프트를 조정한 다음, 최종 길이로 승리한 프롬프트를 다시 렌더링하세요.
- 비용이 출력 규모에 따라 증가함을 기억하세요. 과금은 출력 길이로 계산되므로, 길이는 창의적 레버이자 예산 레버입니다.
resolution
출력의 공간적 품질입니다. 높은 해상도는 더 많은 디테일을 주지만 더 많은 렌더링 시간과 더 많은 비용을 소모합니다. 조언:
- 스펙 시트가 아니라 전달 시나리오로 선택하세요. 비디오가 피드나 작은 플레이어에 나타난다면, 그 시나리오보다 높은 해상도로 생성해도 아무 이득이 없습니다.
- 낮은 해상도로 반복, 높은 해상도로 출시하세요. 프롬프트를 아직 수정 중일 때는 낮은 해상도로 미리 보고, 승인된 프롬프트를 전달 해상도로 다시 제출하세요.
- 높은 설정은 더 긴 대기를 의미합니다. 폴링 마감 시간은 최소 조합이 아니라 허용하는 최대 조합에 맞춰 설정하세요.
이 두 값을 코드 곳곳에 흩어 놓지 말고 동일한 구성 객체에 두세요. 그러면 미리보기에서 프로덕션으로 전환하는 변경이 잊힌 리터럴이 아니라 의도적이고 가시적인 편집이 됩니다.
일반적인 오류 디버깅
대부분의 실패는 네 가지 범주로 나뉩니다. 코드를 바꾸기 전에 증상을 범주에 대응시키세요.
인증 실패
401은 HiAPI가 자격 증명을 받아들이지 않음을 의미합니다. 순서대로 확인하세요: Authorization 헤더가 존재하고 철자가 맞는지, Bearer 뒤에 정확히 공백 하나인지, 키가 현재 유효하고 다른 프로젝트의 것이 아닌지, 환경 변수가 실제로 로드되었는지(키를 붙여넣을 때 끝에 개행이 붙는 것은 고전적 문제입니다). 키 자체가 아니라 변수 길이를 출력해 확인하세요.
검증 실패
401이 아닌 4xx는 보통 요청 본문에 문제가 있음을 의미합니다. Content-Type이 없거나 application/json이 아님, prompt가 없거나 비어 있음, duration 또는 resolution이 허용 집합을 벗어남. 오류 메시지를 문자 그대로 읽으세요. 보통 문제 필드를 지목합니다. 라이브러리 계층이 요청 본문을 가리지 않으므로 curl 버전으로 재현하세요.
타임아웃
서로 다른 두 가지 타임아웃이 있습니다. 제출 타임아웃은 POST 자체가 반환되지 않음을 의미하며, 보통 네트워크 경로나 너무 공격적인 클라이언트 타임아웃을 가리킵니다. 폴링 타임아웃은 작업이 마감 시간 전에 종료 상태에 도달하지 못함을 의미합니다. 렌더링이 실제로 더 오래 걸리거나, 마감 시간이 프로덕션 설정이 아니라 미리보기 설정으로 정해졌기 때문입니다. 후자의 수정은 폴링 간격을 줄이는 것이 아니라 큰 길이와 큰 해상도에 맞춰 max_wait를 늘리는 것입니다.
폴링 오류
더 은밀한 것들입니다. 잠들지 않고 폴링하면 할당량을 낭비하고 속도 제한을 초래합니다. 고정된 짧은 간격으로 폴링해도 같은 효과입니다. 여러 제출 사이에 변수를 재사용해 잘못된 작업 ID를 폴링하는 경우가 흔합니다. 중간 상태를 오류로 취급하는 경우. 그리고 성공 시 한 번이 아니라 각 반복마다 비디오 URL을 가져오는 경우. 작업 ID와 관찰된 각 상태를 기록하세요. 시퀀스가 어느 경우에 해당하는지 즉시 알려줄 것입니다.
출시 전 프로덕션 체크리스트
작동하는 스크립트에서 무인 운영 서비스로 나아가려면 동일한 요청 주위에 몇 겹을 더해야 합니다.
- 지터를 동반한 재시도. 일시적 네트워크 오류와 5xx 응답에 지수 백오프와 무작위화를 적용해 재시도하세요. 검증 오류는 절대 재시도하지 마세요. 동일하게 실패하며 할당량을 소모합니다.
- 모든 곳에 경계가 있는 타임아웃. 제출에는 짧은 타임아웃, 폴링에는 더 긴 마감 시간(허용하는 최대 길이와 해상도에 맞춤), 비디오 다운로드에도 타임아웃을 두세요.
- 구조화된 로깅. 자체 요청 ID, 작업 ID, 관찰된 각 상태 전환, 최종 결과를 기록하되 API 키나 전체 헤더는 기록하지 마세요. 새벽 3시에 문제가 생기면 이 로그가 유일한 증거입니다.
- 자체 계층의 멱등성. 자체 요청 ID에서 작업 ID로의 매핑을 유지해 클라이언트 재시도가 조용히 두 번째 렌더링을 만들지 않게 하세요.
- 비용 통제. 과금은 출력 길이로 계산되므로 서비스가 허용하는 최대 길이와 해상도 상한을 설정하고, 최종 렌더링이 사람이나 규칙의 승인을 받기 전까지 미리보기는 낮은 설정으로 유지하세요.
- 키 위생. 시크릿 저장소에서 키를 로드하고, 계획대로 교체하며, 테스트와 프로덕션에 다른 키를 사용해 유출된 테스트 키가 프로덕션 예산을 소모할 수 없게 하세요.
- 결과 귀속. 작업이 성공하면 즉시 완성된 비디오를 자체 제어 저장소로 복사하고, 전달 URL은 임시 링크로 취급하세요.
이것들을 갖추면 엔드포인트는 예상치 못한 원천이 아니라 예측 가능한 의존성이 됩니다. 먼저 위의 curl 요청으로 자격 증명을 확인한 다음, Python 클라이언트를 서비스에 도입하고 이 체크리스트의 검사로 감싸세요.