MiniMax H3 Max API 사용법: 텍스트 또는 이미지로 비디오 생성하기

MiniMax H3 Max는 HiAPI에서 두 가지 모델명으로 제공됩니다: 텍스트→비디오 minimax-h3-max/text-to-video, 이미지→비디오 minimax-h3-max/image-to-video. 0.92–15초 비디오를 생성하며 480P는 초당 $0.072, 768P는 초당 $0.115, 1080P는 초당 $0.229이고 요청한 초 수만큼 과금됩니다. 먼저 아래 종이배 프롬프트로 5초 가로형 단편을 생성해 보세요. 768P 예산은 $0.575입니다. API를 연동할 때는 작업을 한 번 제출한 뒤 반환된 taskId로 비디오를 가져옵니다.

MiniMax H3 Max는 HiAPI에 출시되었습니다. 이 프롬프트로 생성하기 →. 프롬프트가 자동으로 입력되면 이어서 5초, 768P, 16:9를 직접 선택하세요.

첫 번째 비디오: 비 온 뒤의 종이배

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

이 프롬프트로 생성하기 →

이 프롬프트는 동작과 카메라 무빙을 분리합니다. 종이배는 물을 따라 떠다니고, 낮은 앵글의 카메라가 부드럽게 따라가며, 소리는 멀리서 들리는 새소리로 표현합니다. 종이배를 다른 피사체로 바꿀 때는 동작 하나와 카메라 무빙 하나를 먼저 유지하면 어디를 조정해야 할지 쉽게 파악할 수 있습니다.

온라인 체험과 API 연동, 무엇을 선택할까?

먼저 결과를 보고 싶다면 텍스트→비디오 모델 페이지를 열어 프롬프트를 복사하고 길이와 해상도를 선택한 뒤 생성을 제출하세요. 시작 화면이 이미 있다면 이미지→비디오 모델 페이지로 이동해 첫 프레임 이미지를 업로드하세요. 애플리케이션에 연동한다면 먼저 API Key 페이지에서 키를 발급받고, 서버 측 요청으로 작업을 생성한 뒤 taskId를 저장하고, 작업이 성공하면 비디오 주소를 읽습니다.

해상도는 명시적으로 지정하는 것이 좋습니다: 5초 480P는 $0.36, 768P는 $0.575, 1080P는 $1.145입니다. 먼저 낮은 해상도로 동작을 확인하고, 전달 요구에 맞춰 등급을 선택하세요. 전체 예산은 H3 및 H3 Max 가격표에서 확인할 수 있습니다.

cURL: 작업 생성 후 결과 조회

API Key를 로컬 환경 변수 HIAPI_API_KEY로 설정한 뒤 다음 요청을 실행하세요:

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

POST 타임아웃, 연결 중단 또는 응답 내용으로 생성 결과를 확정할 수 없을 때는 제출 상태가 불명확합니다. 먼저 작업 기록을 조회하고 POST를 바로 다시 실행하지 마세요. 응답의 code=200, data가 객체이고 data.taskId가 비어 있지 않음을 확인한 뒤 ID를 저장하고 조회 주소의 YOUR_TASK_ID를 교체하세요:

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

대기 중인 작업은 같은 ID로 계속 조회하세요. data.status가 success이면 data.output에서 비디오 항목의 url을 읽고, fail이면 작업 오류 메시지를 확인하세요. 입력 또는 인증 오류가 발생하면 해당 문제를 먼저 수정하고, 이미 작업 ID가 있으면 그 작업을 계속 조회하세요.

Python: 한 번 제출하고 같은 작업을 기다리기

아래는 Python 표준 라이브러리를 사용합니다. POST는 한 번만 하고 응답을 검증하며, 제출 결과가 불명확하면 중단하고 작업 기록을 조회하라고 안내합니다. 조회가 일시적으로 실패하면 작업 ID를 유지하고 계속 GET하며, 600초는 이 예제의 대기 상한입니다.

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

이미지로 첫 프레임 또는 마지막 프레임 제어하기

비디오가 내 상품 이미지에서 시작하게 하려면 모델명을 minimax-h3-max/image-to-video로 바꾸고 input에 first_frame_image를 추가하세요. 끝을 지정하려면 last_frame_image를 추가하세요. 마지막 프레임만 단독으로 전달할 수도 있고 첫/마지막 프레임을 동시에 전달할 수도 있습니다. 이미지→비디오에는 aspect_ratio 필드가 없으며 화면비는 이미지를 따릅니다.

필드	사용법
prompt	필수, 최대 50000자, 동작, 카메라 무빙, 소리를 설명
duration	0.92–15초, 소수 허용, 기본 5초
resolution	480P, 768P 또는 1080P, 기본 768P
aspect_ratio	텍스트→비디오에만 존재: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, 기본 16:9
first_frame_image	이미지→비디오: 첫 프레임 공개 이미지 URL
last_frame_image	이미지→비디오: 마지막 프레임 공개 이미지 URL
target_audio_url	선택, 자체 오디오로 오디오 트랙 교체, 최소 2초
prompt_expansion_mode	선택, disabled / balanced(기본) / quality

아래는 첫/마지막 프레임의 전체 요청 본문입니다. 이미지 URL은 직접 공개 접근 가능한 주소 자리표시자이며, 이미지가 시작과 마무리 구도를 담당합니다:

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

마지막 프레임만 제어하려면 first_frame_image를 삭제하고 last_frame_image를 유지하세요. 카메라 동작만 프롬프트에 쓰고, 이미지가 피사체와 초기 구도를 담당하게 하세요. 여러 장면은 프롬프트에 전환마다 명확히 적으세요. 요청 필드는 여전히 이 표를 사용하며 camera_angle, mode, watermark를 추가하지 마세요.

세로형 단편을 원한다면 텍스트→비디오에는 "aspect_ratio": "9:16"을 직접 쓰고, 이미지→비디오에는 세로형 첫 프레임 이미지를 사용하세요. 화면비는 이미지를 따릅니다.

애플리케이션에 연동할 때는 콜백을 요청 최상위에 두기

생성 요청의 최상위에 model, input과 나란히 선택적 콜백을 추가하세요:

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

이 부분을 전체 요청에 합치세요. 수신 측은 taskId로 중복 제거하고 성공과 실패를 분리 처리하며, 누락된 알림은 작업 조회로 보완하세요. 작업 ID를 받은 뒤에는 다시 제출하지 마세요. HTTP 오류가 발생하면 먼저 응답 내용을 읽어 인증 문제인지 파라미터 문제인지 구분하세요.

연동 후 확인할 네 가지

1. 비어 있지 않은 data.taskId를 저장하고, 조회 예외가 발생해도 계속 사용하세요.
2. 종료 상태가 success 또는 fail인지 확인하고, 대기 상한을 모델 소요 시간으로 간주하지 마세요.
3. 성공한 작업의 data.output에서 type=video로 비디오 URL을 찾으세요.
4. 산출물을 다운로드해 실제 크기, 길이, 화면이 전달 요구에 맞는지 확인하세요.

자주 묻는 질문

H3 Max는 참조 비디오나 오디오를 사용할 수 있나요? H3 Max는 target_audio_url로 오디오 트랙을 교체할 수 있지만 참조 비디오는 지원하지 않습니다. 이미지, 비디오, 오디오 멀티모달 참조가 필요하면 MiniMax H3를 선택하세요.

H3와 비교해 Max가 더 비싼가요? H3 2K는 초당 $0.1189, Max 768P는 초당 $0.115, 1080P는 초당 $0.229입니다. 먼저 필요한 해상도와 참조 소재로 모델을 선택한 뒤 길이로 예산을 계산하세요.

세로형 단편은 어떻게 시작하나요? 텍스트→비디오에는 "aspect_ratio": "9:16"을 쓰고, 이미지→비디오에는 세로형 첫 프레임 이미지를 준비하세요. 화면비는 이미지를 따릅니다.

종이배 프롬프트를 복사하고 이 프롬프트로 생성하기 →로 먼저 5초 단편을 만들어 보세요. 더 많은 동작과 카메라 무빙 표현은 실제 비디오 4편과 전체 프롬프트에서, 전체 필드는 텍스트→비디오 파라미터 문서와 이미지→비디오 파라미터 문서에서 확인하세요.