MiniMax Hailuo 2.3 API 연동: 비디오 API로 복잡한 인체 모션 생성하기

대상 모델: MiniMax-Hailuo-2.3
추론 엔드포인트: https://api.toapis.com/v1/videos/generations
관련 글: MiniMax H3 API 가이드 · H3 카메라 워크 프롬프트 · 자동 R2V 파이프라인

1. 핵심 요약 및 개요 (TL;DR)

• 작업: ToAPIs 비디오 생성 엔드포인트에 텍스트-투-비디오, 또는 첫 프레임이 있는 이미지-투-비디오 작업을 보내 캐릭터 및 인체 모션 클립을 만듭니다.
• 계약: MiniMax-Hailuo-2.3는 정수 길이 6초 또는 10초와 해상도 **768P 또는 1080P**를 받습니다. 1080P는 6초만 지원합니다. 현재 API 레퍼런스는 프롬프트를 2,000자로 제한합니다.
• ID: 텍스트 및 이미지 생성에는 카탈로그 문자열 MiniMax-Hailuo-2.3를 사용합니다. MiniMax-Hailuo-2.3-Fast는 이미지-투-비디오만 지원하며 첫 프레임 URL이 필요합니다. 두 ID 모두 minimax-h3와 호환되지 않습니다.
• 카메라 표현: ToAPIs Hailuo 2.3 레퍼런스에는 [Push in], [Pan left, Pedestal up] 같은 대괄호 지시가 문서화되어 있습니다. 아래 표는 현재 문서의 어휘입니다. 샷 문법을 하드코딩하기 전에 공개 문서로 다시 확인하세요.
• 프로토콜: Bearer REST. 제출 응답의 작업 id를 저장하고, 기한 안에 GET /v1/videos/generations/{task_id}(또는 GET /v1/tasks/{task_id})를 폴링합니다. 클라이언트 시간 초과가 업스트림 작업 실패를 뜻하지는 않습니다.

2. 복잡한 인체 모션 프롬프트 패턴

ToAPIs 공개 카탈로그는 MiniMax Hailuo 2.3를 표현력 있는 이야기와 캐릭터 클립을 위한 캐릭터 모션, 표정, 스타일 비디오 모델로 소개합니다. 이는 제품 포지셔닝이지, “사지가 절대 왜곡되지 않는다”는 독립 벤치마크가 아닙니다. 프로덕션에서는 한 피사체와 한 주요 동작을 역학적으로 적은 뒤 결과물을 검토하세요.

유용한 인체 모션 프롬프트는 스타일보다 먼저 신체 역학을 적습니다. 누가 움직이는지, 어느 사지가 선행하는지, 무게 중심이 어떻게 이동하는지, 동작이 어떻게 시작하고 끝나는지입니다. 길이나 해상도를 A/B 할 때는 이 핵심을 고정해 두어야, 문구 변화를 모델 차이로 오해하지 않습니다.

ToAPIs Hailuo 2.3 API 레퍼런스는 다음 카메라 지시를 프롬프트 문자열 안에 둡니다. 별도의 요청 필드가 아닙니다. 프론트엔드 계약도 prompt를 텍스트로 검증합니다. 동시 움직임은 한 괄호에 최대 3개, 순서가 있는 움직임은 문장 안에 나열하세요.

그림 1: 정지 포즈를 첫 프레임 입력으로 삼고, 이어질 동작을 프롬프트에 적은 다음, ToAPIs 게이트웨이에 생성 요청을 한 번만 제출합니다.

검증하기 쉬운 짧은 템플릿:

SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES

예: A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs.

이미지-투-비디오에서는 공개적으로 접근 가능한 첫 프레임 URL 하나를 image_urls에 넣습니다. 이미지는 시작 프레임이고, 프롬프트는 그 이후의 움직임을 설명합니다. 현재 문서의 이미지 제한은 JPG, JPEG, PNG 또는 WebP, 20MB 미만, 짧은 변이 300px 초과, 종횡비 2:5–5:2입니다. image_urls에 base64를 넣지 말고, 로컬 파일은 먼저 업로드하세요.

MiniMax-Hailuo-2.3-Fast는 텍스트-투-비디오를 받지 않으며 첫 프레임 URL이 필수입니다. Hailuo 2.3에는 마지막 프레임 필드가 문서화되어 있지 않습니다. 첫 프레임에서 마지막 프레임으로의 보간은 MiniMax-Hailuo-02의 계약이며 이 ID의 것이 아닙니다. H3의 ratio나 reference_videos를 Hailuo 2.3 요청에 그대로 복사하지 마세요.

플레이그라운드 옵션은 소문자 768p / 1080p를 보여줄 수 있습니다. 현재 API 예시는 768P와 1080P를 사용합니다. 배치를 자동화하기 전에 계정이 받는 값을 확인하세요. 같은 카메라 문구는 MiniMax H3에서도 프롬프트 텍스트로 쓸 수 있지만, 길이·해상도·미디어 모드 계약은 다릅니다. ID를 바꾸기 전에 해당 가이드를 다시 읽으세요.

3. 프로덕션 구현: cURL과 Python

1단계: cURL로 제출

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs",
    "duration": 6,
    "resolution": "768P"
  }'

2단계: Python 헬퍼와 폴링

공식 문서가 현재 안내하는 공개 오리진은 https://toapis.com입니다(중국 본토는 https://toapis.cn). 이 시리즈의 다른 가이드는 https://api.toapis.com을 사용합니다. 베이스 URL은 하나로 유지하세요. 아래 예시는 문서화된 작업 조회 경로와 completed / failed 상태를 따릅니다. 배포 전에 계정 API 레퍼런스에서 id, result.data[0].url, 응답 엔벨로프를 확인하세요.

import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_motion_clip(
    prompt: str,
    duration: int = 6,
    resolution: str = "768P",
    image_url: str | None = None,
    model: str = "MiniMax-Hailuo-2.3",
) -> str:
    if resolution == "1080P" and duration != 6:
        raise ValueError("1080P currently supports a 6-second duration only")
    payload = {
        "model": model,
        "prompt": prompt,
        "duration": duration,
        "resolution": resolution,
        "metadata": {"prompt_optimizer": True, "aigc_watermark": False},
    }
    if image_url:
        payload["image_urls"] = [image_url]
    elif model == "MiniMax-Hailuo-2.3-Fast":
        raise ValueError("MiniMax-Hailuo-2.3-Fast requires a first-frame image_urls value")
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 300) -> str:
    poll_url = f"{BASE}/v1/videos/generations/{task_id}"
    interval = 5.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 30))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 10.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = (
        "A contemporary dancer in a black practice leotard plants the left foot, "
        "then uncoils a slow 360-degree turn with the right arm leading and the "
        "torso stacked over the standing leg, warehouse skylight, [Tracking shot], "
        "photorealistic, no morphing limbs"
    )
    task_id = dispatch_motion_clip(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

프롬프트 템플릿 버전을 작업 기록 옆에 두면 모델 변경과 문구 변경을 구분할 수 있습니다. 첫 프레임 작업이면 dispatch_motion_clip에 image_url=을 전달하세요. Fast SKU에서는 이 인자가 필수입니다.

Hailuo 2.3의 기본 길이는 6초 또는 10초입니다. 1080P와 duration: 10을 함께 보내지 마세요. 연속 4–15초, 참조 미디어, 마지막 프레임이 필요하면 다른 계약입니다. H3 API 가이드와 R2V 파이프라인을 보세요.

4. 오류 처리 및 상태 매트릭스

아래 분류는 진단의 출발점일 뿐, ToAPIs의 정확한 오류 코드를 보장하지 않습니다. HTTP 조회가 성공해도 작업 status는 반드시 읽어야 합니다.

$\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)$

5. 요금과 FinOps ROI

$\text{Estimated cost} = \text{successful billable jobs} \times \text{current account rate for that model, duration, and resolution}$

• 기획 초안의 단가를 그대로 쓰지 마세요. 초당 또는 건당 요금, 과금 단위, 실패 작업 처리는 모델·해상도·길이·경로·계정에 따라 달라집니다. ToAPIs 요금 페이지의 공식 벤더 참고 행은 표시용이며 계정 청구액과 다를 수 있습니다. 샷 리스트를 예측하기 전에 현재 카탈로그와 계정 견적을 읽으세요.
• Fast는 다른 SKU이지, 같은 ID의 무료 속도 스위치가 아닙니다. MiniMax-Hailuo-2.3-Fast는 이미지-투-비디오만 지원한다고 문서화되어 있습니다. 요금은 따로 확인하세요.
• 비용은 프롬프트 계층에서 통제하세요. 먼저 768P와 6초로 초안을 만들고, 버전 있는 템플릿을 쓰며, 한 번에 변수 하나만 바꾸고, 클라이언트 시간 초과 뒤에는 상태를 확인하기 전에 재제출하지 마세요.
• 공식 벤더 계약에는 연간 약정, 좌석, 선결제 하한이 붙는 경우가 많습니다. ToAPIs 과금은 보통 사용량 기준입니다. 유효 조건은 계정에서 확인하세요.

6. 자주 묻는 질문

구조화 FAQ는 frontmatter를 보세요. 요약: 요청의 모델 문자열은 MiniMax-Hailuo-2.3이며 하이픈 슬러그나 H3 ID가 아닙니다. 1080P는 6초만 가능합니다. Fast에는 첫 프레임 URL이 필요하고 텍스트-투-비디오는 지원하지 않습니다. 문서화된 카메라 지시는 프롬프트 안에 있으며 별도 필드가 아닙니다. Hailuo 2.3에는 마지막 프레임 입력이 없습니다.

7. 액션 체크리스트

• ToAPIs 개발자 포털에서 키를 만듭니다.
• MiniMax-Hailuo-2.3, resolution: "768P", 6초로 위의 cURL을 스모크 테스트합니다.
• 계정이 768P와 768p 중 무엇을 받는지 확인하고, GET /v1/videos/generations/{id}를 기한 있게 폴링합니다.
• 다음: 다른 길이나 미디어 계약이 필요하면 H3 카메라 워크 가이드. 카탈로그 현황은 Hailuo 2.3 모델 가이드.