튜토리얼
HiAPI API로 minimax-h3를 사용하는 방법: curl, Python 및 실행 가능한 요청
이 페이지에서
minimax-h3 통합의 엔드투엔드 모습
비디오 생성은 즉각적인 작업이 아닙니다. minimax-h3는 프롬프트나 소스 이미지를 받아 GPU 풀에서 작업을 스케줄링하고, 프레임을 인코딩하며, 출력 파일을 조립해야 합니다. 전체 과정은 길이와 해상도에 따라 몇 초에서 몇 분까지 걸릴 수 있습니다. HiAPI 엔드포인트가 파일이 준비될 때까지 블로킹한다면, HTTP 클라이언트는 그동안 열린 연결을 하나 점유하게 됩니다. 재시도 시 취약하고, 서버리스 시간 제한에 불리하며, 요청/응답식 웹 핸들러에서는 동작할 수 없습니다.
따라서 통합은 비동기 미디어 API의 표준 패턴인 먼저 제출하고 나중에 폴링하는 형태를 따릅니다:
- 제출. 작업을 설명하는 JSON 페이로드(프롬프트, 선택적 이미지, 길이, 화면 비율 및 모든 모델별 파라미터)를
POST합니다. API는 검증 후 즉시 작업 식별자와 초기 상태를 반환합니다. - 폴링. 짧은 간격으로 해당 식별자를 사용해 작업 상태 엔드포인트를 호출합니다. 상태는 대기, 처리 중, 그리고 성공 또는 실패 등의 상태를 거칩니다.
- 가져오기. 상태가 종료 상태에 도달하면 응답에는 결과, 즉 일반적으로 생성된 비디오의 다운로드 가능한 URL이 담깁니다.
이 모델은 이 가이드의 이후 모든 내용을 결정하는 세 가지 결과를 낳습니다:
- 작업 ID가 유일한 핸들입니다. 영속화하세요. 잃어버리면 작업을 검색할 수 없으며, 다시 제출하고 작업 비용을 또 지불해야 합니다.
- 코드에는 하나가 아닌 두 개의 실패 지점이 있습니다. 제출은 실패할 수 있고(인증, 잘못된 페이로드 형식), 폴링도 실패할 수 있습니다(타임아웃, 일시적 네트워크 오류, 작업 종료 실패). 이들을 분리해서 처리하세요.
- 폴링 리듬은 설계 결정입니다. 너무 공격적이면 요청을 낭비하고, 너무 느리면 사용자가 이미 준비된 상태를 기다리게 됩니다.
이 글에서 모든 호출은 HiAPI 통합 API로 전송됩니다. HiAPI 계정에서 API 키를 발급받고 페이로드에서 모델을 minimax-h3로 참조해야 합니다. 나머지 모든 것(인증 헤더, 기본 URL, 폴링 엔드포인트)은 플랫폼 전체에서 공유되므로 여기서 배운 패턴을 클라이언트를 재구성하지 않고도 다른 모델로 이전할 수 있습니다.
이 멘탈 모델을 갖추었다면 설정을 확인하는 가장 빠른 방법은 단일 curl 호출입니다.
첫 번째 실행 가능한 curl 요청
애플리케이션 코드를 작성하기 전에 키가 유효하고 API에 접근할 수 있는지 확인하세요. 일회성 curl 명령은 인증 문제와 페이로드 문제를 구분하는 가장 저렴한 방법입니다.
먼저 키를 내보내어 셸 기록에 그대로 남지 않게 하세요:
export HIAPI_API_KEY="your-api-key-here"
그런 다음 최소한의 텍스트→비디오 작업을 제출하세요:
curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
"duration": 5,
"aspect_ratio": "16:9"
}'
성공 응답은 작업 식별자와 상태를 포함한 JSON 객체를 반환합니다. 구조는 대략 다음과 같습니다:
{
"id": "task_abc123xyz",
"status": "queued",
"model": "minimax-h3",
"created_at": "2024-01-01T00:00:00Z"
}
아직 비디오 URL이 없습니다. 이는 예상된 일입니다. 작업이 방금 수락되었을 뿐입니다. 실제 응답의 필드 이름은 위와 약간 다를 수 있으므로 가정하지 말고 응답 본문을 읽고, 개발 중에는 전체 내용을 기록하세요.
요청의 각 부분이 하는 일
- URL은 HiAPI 플랫폼의 비디오 생성 리소스를 가리킵니다. 모든 모델 호출이 이 기반을 공유하므로 모델 전환은 코드 재작성이 아니라 페이로드 변경일 뿐입니다.
Authorization: Bearer는 API 키를 전달합니다. 가장 흔한 실패 원인이므로 문제가 생기면 먼저 이것을 검증하세요.Content-Type: application/json은 필수입니다. 없으면 서버가 요청 본문을 거부하거나 잘못 파싱할 수 있습니다.model은 minimax-h3를 명시적으로 선택합니다. 절대 생략하지 마세요. 플랫폼은 이 값을 기준으로 라우팅합니다.prompt는 창의적 지시입니다. 피사체, 카메라 움직임, 조명을 구체적으로 적으세요. 모호한 프롬프트는 모호한 비디오를 만듭니다.duration과aspect_ratio는 출력을 제한합니다. 모델이 지원하는 범위 내로 유지하세요. 범위를 벗어난 값은 서버 장애가 아니라 페이로드 검증 오류입니다.
작업 존재 확인
제출 직후 작업을 한 번 가져와 ID가 유효함을 증명하세요:
curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
-H "Authorization: Bearer $HIAPI_API_KEY"
task_abc123xyz를 제출 응답의 ID로 바꾸세요. 이것이 상태를 반환하면 키, 엔드포인트, 작업 핸들이 모두 올바르며 Python으로 넘어갈 준비가 된 것입니다.
이제 두 가지 습관을 들일 가치가 있습니다. curl을 -sS로 실행해 오류가 조용히 삼켜지지 않고 드러나게 하고, URL은 항상 따옴표로 감싸세요. JSON 페이로드에서 예기치 않은 셸 확장은 따옴표 자체보다 훨씬 많은 시간을 잡아먹는 디버깅 함정입니다.
Python에서 동일한 요청 만들기
curl 호출은 계약을 증명했습니다. Python은 재사용 가능한 것을 만드는 곳입니다. 바로 폴링 루프로 뛰어들지 말고, 제출과 결과 검색을 두 개의 명확한 메서드로 처리하는 작은 클라이언트 클래스로 시작하세요. 이 분리는 비동기 로직을 전송 계층 밖으로 옮깁니다.
requests를 사용하세요(비동기를 선호하면 httpx). 두 방식의 형태는 동일합니다.
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
class MiniMaxH3Client:
def __init__(self, api_key: str | None = None):
self.api_key = api_key or os.environ["HIAPI_API_KEY"]
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
})
def submit(self, prompt: str, duration: int = 5,
aspect_ratio: str = "16:9", **extra) -> str:
payload = {
"model": "minimax-h3",
"prompt": prompt,
"duration": duration,
"aspect_ratio": aspect_ratio,
**extra,
}
resp = self.session.post(
f"{BASE_URL}/video/generations",
json=payload,
timeout=30,
)
resp.raise_for_status()
data = resp.json()
return data["id"]
여기에는 의도적으로 중요한 몇 가지 선택이 있습니다.
단순 requests가 아닌 session 사용. requests.Session을 재사용하면 제출과 폴링 호출 사이에 연결이 활성 상태로 유지되며, 동일 호스트를 반복적으로 폴링할 때 이는 중요합니다. 헤더도 한 곳에서 관리되므로 인증 헤더를 한 번만 정의합니다.
제출 시 하드 타임아웃. 거의 즉시 반환되어야 하는 요청에 30초는 넉넉합니다. 타임아웃이 없으면 네트워크 지터가 프로세스를 무한히 매달리게 합니다. 원격 API 호출에는 절대 timeout을 설정하지 않고 넘어가지 마세요.
파싱 전 raise_for_status() 호출. 비 2xx 응답의 본문 형태는 일반적으로 성공 응답과 다릅니다. 먼저 상태 코드를 확인하면 오류 처리가 id 키 누락 시 충돌하는 대신 잘 형식화된 오류 메시지를 읽게 됩니다.
**extra 전달. 모델별 옵션은 진화합니다. 추가 키워드 인자를 통과시키면 매번 메서드 시그니처를 편집하지 않고도 새 파라미터를 실험할 수 있습니다.
사용하기
client = MiniMaxH3Client()
task_id = client.submit(
"A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")
이것이 전체 제출 경로입니다. 클라이언트는 문자열, 즉 작업 핸들만 반환합니다. submit이 결과도 기다리게 하려는 충동을 억제하세요. 제출과 대기를 한 메서드에 섞으면 재시도가 모호해집니다. 실패 시 작업이 생성되었는지 판단할 수 없어 중복 생성 위험이 있습니다. 이들을 분리하고 전략은 호출자가 결정하게 하세요.
API를 폭격하지 않고 결과 폴링하기
폴링은 부주의하게 작성하기 가장 쉬운 부분입니다. 지연 없는 순진한 while True 루프는 2분이 걸리는 작업에 수백 개의 요청을 보내며, 작업이 이미 실패한 후에도 계속합니다.
올바른 폴링 루프에는 네 가지 책임이 있습니다: 상태 확인, 대기, 종료 상태에서 중지, 최종 포기.
TERMINAL = {"succeeded", "failed", "cancelled"}
def wait_for(self, task_id: str, interval: float = 3.0,
max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status", "unknown")
if status in TERMINAL:
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")
간격 선택
비디오 생성의 경우 몇 초 고정이 합리적인 기본값입니다. 작업은 처음 몇 초 안에 완료되지 않으며(모델 로딩과 프레임 인코딩 모두 실제 시간이 필요) 200밀리초마다 폴링하는 것은 부하 외에는 아무것도 얻지 못합니다. 예의와 효율을 모두 원한다면 상한이 있는 지수 백오프를 사용하세요. 1~2초로 시작해 라운드마다 약 1.5배씩 곱하고, 5~10초에 도달하면 그대로 유지하세요. 초기 폴링은 빠른 실패를 신속히 포착하고, 후기 폴링은 긴 렌더링 동안 비용을 낮게 유지합니다.
올바르게 중지하기
인식되지 않는 상태는 종료 상태가 아닌 것으로 간주하고 계속 기다리세요. 단, 어느 한도까지만. 두 가지 중지 조건이 중요합니다:
- 종료 상태. 성공 시 즉시 반환하세요. 실패 시 빈 결과를 반환하지 말고 응답의 오류 메시지를 드러내세요. 원인은 로그에 중요합니다.
- 실제 시간 예산. 벽시계 대신 단조 시계를 사용하세요. 시스템 시계 조정으로 루프가 일찍 종료되거나 영원히 실행되지 않도록. 선택한 길이와 해상도에서 현실적인 최장 작업보다 편안히 높은 상한을 고르고, 도달을 경고가 필요한 운영 오류로 취급하세요.
결과 반환
상태가 종료 성공이면 응답에 생성된 비디오의 URL이 담깁니다. 즉시 다운로드하세요. 결과 URL에는 만료 시간이 있는 경우가 많으므로 지속적 접근이 필요하면 자체 객체 스토리지에 저장하세요. 공급업체 URL을 최종 사용자에게 직접 전달하고 영원히 존재할 것이라 가정하지 마세요.
실용적 팁 하나: 디버그 레벨에서 각 폴링의 작업 ID, 상태, 경과 시간을 기록하고, 정보 레벨에서 종료 결과를 기록하세요. 작업이 예상보다 오래 걸릴 때 이 타임라인이 5분 진단과 1시간 추측의 차이를 만듭니다.
텍스트→비디오와 이미지→비디오의 요청 형태
두 생성 모드는 페이로드의 대부분을 공유합니다. 차이는 창의적 입력에 있으며, 그 차이는 어떤 실패를 예상해야 하는지에 하류 영향을 미칩니다.
텍스트→비디오
이는 앞 장에서 보여준 형태입니다: 프롬프트와 출력 제약. 모델은 구도, 움직임, 조명, 피사체 세부사항 등 모든 것을 발명합니다. 페이로드에는 다음이 담깁니다:
model:minimax-h3prompt: 장면 설명duration,aspect_ratio및 기타 출력 제어
앵커가 없으므로 프롬프트 품질이 결과를 지배합니다. 품질에 대한 형용사를 쌓기보다 카메라 동작("천천히 다가가기", "고정 삼각대 샷")과 조명("골든 아워 역광")을 묘사하세요. 모호한 최상급 형용사는 효과가 적고 구체적 물리 묘사는 효과가 큽니다.
이미지→비디오
이미지→비디오 변형은 같은 요청에 소스 이미지 참조를 추가합니다. 일반적으로 프롬프트 옆의 이미지 필드에 이미지 URL 또는 업로드된 리소스 식별자를 제공하면 모델이 그 시작 프레임에서 애니메이션을 만듭니다.
client.submit(
"Gentle wind moves the hair, subtle camera push forward",
duration=5,
image_url="https://example.com/portraits/source.jpg",
)
이제 프롬프트는 다른 역할을 합니다. 시각적 내용이 이미 이미지로 고정되었으므로 내용이 아니라 움직임과 카메라를 지시합니다. 완전한 장면 설명을 쓰는 것은 보통 역효과입니다. 모델은 화면에 없는 위치를 추가할 수 없습니다. 움직임 프롬프트는 짧고 구체적으로 유지하세요.
이미지 모드의 정확한 필드 이름과 허용되는 이미지 형식, 두 모드의 길이와 화면 비율 유효 범위는 요청 참조를 확인하세요. 이 제약이 바로 페이로드 검증 오류를 유발하는 제약이므로 한 번 읽으면 이후 디버깅 한 라운드를 절약할 수 있습니다.
실용적 경험칙
새로운 장면이 필요할 때 텍스트→비디오를 선택하세요. B-롤, 분위기 클립, 개념 시각화. 일관성이 중요할 때 이미지→비디오를 선택하세요. 제품 사진에 애니메이션 추가, 캐릭터 초상화에 생명 부여, 스토리보드 프레임을 모션 샷으로 변환. 모드는 페이로드 차이이지 통합 차이가 아니므로 하나의 클라이언트 클래스에 선택적 이미지 파라미터를 받게 하면 둘 다 서비스할 수 있습니다.
흔한 오류 디버깅
minimax-h3 호출이 잘못되면 원인은 거의 항상 네 곳 중 하나입니다. 이 순서로 점검하세요.
1. 인증
증상: 401 또는 403 응답, 또는 자격 증명이 유효하지 않다는 오류 본문.
Authorization헤더가 존재하고Bearer <key>형식인지 확인하세요. 중간에 공백 하나.- 환경 변수에 실제로 값이 있는지 확인하세요. 환경 변수에 붙여넣은 후행 개행은 로그에 보이지 않는 방식으로 헤더를 손상시킵니다.
- 키가 기대한 동일 HiAPI 프로젝트에 속하며 교체되지 않았는지 확인하세요.
가장 빠른 테스트: 앞서의 원시 curl을 다시 실행하세요. curl은 되고 Python은 안 되면 버그는 계정이 아니라 클라이언트에 있습니다.
2. 잘못된 페이로드 형식
증상: 400 또는 422 응답, 또는 명명된 파라미터에 대한 검증 메시지.
Content-Type: application/json이고 본문이 유효한 JSON인지 확인하세요. 후행 쉼표는 고전적 원인입니다.model이 정확히minimax-h3인지 확인하세요.duration과aspect_ratio가 모델 지원 범위 내인지 확인하세요.- 이미지 모드에서는 이미지 참조에 접근 가능하고 허용된 형식인지 확인하세요.
오류 메시지를 문자 그대로 읽으세요. 검증 오류는 보통 위반한 필드를 명시합니다. 개발자들은 종종 이를 건너뛰고 페이로드의 무관한 부분을 다시 작성하기 시작합니다.
3. 폴링이 끝나지 않음
증상: 합리적 시간 후에도 상태가 대기 또는 처리 중, 또는 영원히 반복.
- 전체 상태 응답을 기록하세요. 상태 값이 코드가 가정한 것과 다를 수 있습니다.
- 읽는 필드를 확인하세요. 종료 집합이
"completed"를 확인하는데 API가"succeeded"를 반환하면 루프가 영원히 실행됩니다. 개발 초기에 원시 응답을 한 번 출력하세요. - 작업 ID가 잘림이나 공백 없이 정확히 복사되었는지 확인하세요.
- 실제 시간 마감을 추가하세요. 상한 없는 멈춘 루프는 API가 아니라 코드의 버그입니다.
4. 타임아웃과 일시적 네트워크 오류
증상: 연결 오류, 읽기 타임아웃, 또는 제출이나 폴링 시 5xx 응답.
- 모든 호출에 명시적
timeout을 전달하세요. 많은 클라이언트의 기본값은 없음이며, 이는 매달린 소켓이 영원히 블로킹될 수 있음을 의미합니다. - 연결 타임아웃과 읽기 타임아웃을 구분하세요. 읽기 타임아웃된 제출은 실제로 작업을 생성했을 수 있습니다. 요청 ID가 반환되면 응답 헤더에서 기록하고, 맹목적으로 재제출하기 전에 작업이 나타났는지 확인하세요.
- 폴링의 5xx는 재시도하세요. 작업은 괜찮을 수 있습니다. 제출의 5xx는 작업이 생성되지 않았는지 확인해 중복 생성을 피하세요.
빠른 분류 습관: 프로젝트 옆에 초안 curl 파일을 두고 제출 및 폴링 명령을 환경 변수로 미리 채우세요. 애플리케이션 코드 밖에서 버그를 재현하는 데 몇 초면 되고, 문제가 전송인지 로직인지 즉시 알려줍니다.
프로덕션 준비하기
실행 가능한 스크립트는 실행 가능한 서비스가 아닙니다. 비디오 작업은 충분히 느리므로 프로덕션 트래픽은 겹치고, 재시도하며, 때로는 단일 수동 실행으로는 결코 드러나지 않는 방식으로 실패합니다. 네 가지 패턴이 대부분의 부담을 집니다.
백오프를 사용한 재시도, 단 안전한 곳에서만
재시도 정책은 어느 호출이 실패했는지에 따라 달라집니다:
- 폴링은 본질적으로 안전하게 재시도할 수 있습니다. 실패한 상태 확인은 부작용이 없으므로 지터가 있는 지수 백오프로 소수 시도로 제한해 재시도하세요.
- 제출은 맹목적으로 재시도할 수 없습니다. 타임아웃은 작업이 생성되지 않았다는 뜻이 아닙니다. 재제출 전에 해당 요청의 작업이 이미 존재하는지 확인하세요(가능하면 응답 헤더의 요청 ID 또는 짧은 대사 창 사용). 또는 페이로드 해시로 작업 ID를 캐시해 자체 제출을 멱등하게 만들면 재시도 요청이 새 렌더링을 시작하지 않고 기존 작업을 반환합니다.
- 모델 수준 실패인 종료 상태
failed는 보통 같은 페이로드로 자동 재시도해서는 안 됩니다. 같은 입력은 같은 방식으로 실패하는 경향이 있습니다. 기록하고 경고하며 사람이나 수정된 프롬프트가 맡게 하세요.
모든 백오프 수면에 지터를 추가하세요. 없으면 동시에 재시도하는 워커 배치가 동기 스파이크를 만들어 나쁜 상황을 더 나쁘게 만듭니다.
작업 ID를 모든 곳에 기록하기
작업 ID는 시스템과 생성된 비디오 사이의 유일한 영속 링크입니다. 제출 성공 즉시 구조화 필드(task_id, 모델, 길이, 제출 타임스탬프)로 로그에 기록하세요. 사용자가 비디오 분실을 보고하면 작업 ID로 검색해 몇 초 안에 전체 이력을 찾을 수 있습니다. 종료 상태와 경과 시간도 기록해 "보통 얼마나 걸리나요"라는 질문에 기억이 아니라 데이터로 답하세요.
명시적 타임아웃 예산 설정
요청별 타임아웃이 아니라 전체 작업의 총 예산 관점에서 생각하세요. 작업에는 세 단계(제출, 대기, 다운로드)가 있으며 각각 경계가 필요합니다. 합리적 구조:
- 죽은 연결을 빠르게 감지하기 위한 제출 및 폴링 요청의 짧은 타임아웃.
- 지원하는 최장 길이와 해상도에 여유를 두고 설정한 폴링의 총 실제 시간 상한.
- 큰 파일이 메모리를 고갈시키거나 워커를 매달리게 하지 않도록 스트리밍 쓰기가 있는 경계 다운로드.
예산이 소진되면 작업을 깔끔히 실패시키고, 동시성 슬롯을 해제하며, 명확한 오류를 보고하세요. 예측 가능한 실패가 플랫폼이 컨테이너를 재시작할 때까지 매달리는 요청보다 낫습니다.
제출과 소비 분리
먼저 제출 후 폴링 설계는 자연스럽게 큐 아키텍처로 매핑됩니다. 웹 핸들러는 제출하고 작업 ID를 반환하며, 백그라운드 워커가 폴링해 결과를 저장하고, 클라이언트는 당신의 상태 엔드포인트를 폴링합니다. 이는 사용자 대면 지연을 렌더링 시간과 분리하고, 동시성 제한을 쉽게 적용하게 하며, 제출 급증이 웹 계층 스레드 풀을 고갈시키지 않음을 의미합니다.
이 네 가지를 올바르게 하면 minimax-h3의 비동기 형태는 당신과 싸우지 않고 함께합니다. 작업이 추적되고, 재시도가 안전하며, 실패가 가시적이고, 아무것도 무한히 매달리지 않습니다.