MiniMax H3 프롬프트 가이드: API로 영화적 카메라 워크 만들기

대상 모델: minimax-h3
추론 엔드포인트: https://api.toapis.com/v1/videos/generations
관련 글: MiniMax H3 API 가이드 · H3와 Turbo 선택 · 자동 R2V 파이프라인

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

• 목표: 샷 리스트를 피사체·동작·카메라 경로·렌즈·조명이 담긴 재사용 가능한 MiniMax H3 프롬프트로 만든 뒤 ToAPIs generations 엔드포인트에 제출합니다.
• 작성법: 카메라 의도를 앞에, 피사체를 뒤에 둡니다. 방향 구문을 초점거리(예: 35mm와 85mm) 및 조명 단서와 결합합니다.
• 계약: 기본 minimax-h3는 정수 4–15초 클립을 받습니다. ratio(16:9, 9:16 및 아래에 나열된 값)를 사용하세요. 이는 프론트엔드 요청 계약이며 지연 시간이나 품질 벤치마크가 아닙니다.
• 구문 주의: 대괄호 태그는 프롬프트 도우미입니다. 업스트림 모델 문서가 명시하지 않는 한 [Pan Left]를 문서화된 네이티브 명령으로 다루지 마세요.
• 프로토콜: Bearer REST. 한 번만 제출하고 작업 식별자를 저장한 뒤, 제한 시간 안에서 문서화된 작업 상태 엔드포인트를 폴링합니다.

2. 카메라 워크 프롬프트 패턴

유용한 H3 프롬프트는 카메라 방향·렌즈·스타일을 더하기 전에 장면 하나와 주된 동작 하나를 설명합니다. 모델이나 duration을 비교할 때는 이 부분을 고정하세요. 그렇지 않으면 문구 변경이 결과 차이를 설명할 수 있습니다.

아래 표의 태그는 프롬프트 도우미이며 보장된 명령 문법이 아닙니다. ToAPIs 프론트엔드 계약은 프롬프트를 텍스트로 검증할 뿐(최대 7,000 Unicode 문자) [Pan Left] 같은 문자열이 H3 네이티브 명령임을 입증하지 않습니다. 템플릿의 통일된 어휘로 쓴 뒤 결과물을 검토하세요.

그림 1: 팬, 틸트, 달리, 오비트를 한 피사체 주위의 프롬프트 공간 궤적으로 이해한 뒤, ToAPIs 게이트웨이에 생성 요청을 한 번만 제출합니다.

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

[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES

예시: [Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur.

첫 프레임(R2V) 작업에서도 같은 프롬프트 문구가 앵커 이미지 주위나 바깥으로의 카메라 움직임을 설명합니다. 요청 필드는 R2V 파이프라인 튜토리얼을 참고하세요. 프레임 입력과 참조 미디어는 여전히 배타적 모드입니다.

현재 프론트엔드가 받는 ratio 값은 adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16입니다. 프레임 입력이 있으면 adaptive로 강제됩니다. aspect_ratio를 보내지 마세요. 계약 필드 이름은 ratio입니다.

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-h3",
    "prompt": "[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur",
    "duration": 6,
    "ratio": "16:9"
  }'

2단계: Python 프롬프트 도우미와 폴러

필드 이름과 응답 형태는 계정용 API 레퍼런스에 맞추세요. 아래 예시는 다른 ToAPIs 비디오 가이드와 같은 작업 상태 경로를 사용합니다. 배포 전에 task_id, status, video_url을 확인하세요.

import os
import time
import requests

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


def build_cinematic_prompt(
    subject: str,
    camera_move: str,
    lighting: str,
    lens: str = "35mm anamorphic",
) -> str:
    return (
        f"[{camera_move}] {subject}, {lighting}, "
        f"shot on {lens}, photorealistic, cinematic motion blur."
    )


def dispatch_camera_shot(prompt: str, duration: int = 6, ratio: str = "16:9") -> str:
    payload = {
        "model": "minimax-h3",
        "prompt": prompt,
        "duration": duration,
        "ratio": ratio,
    }
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 180) -> str:
    poll_url = f"https://api.toapis.com/v1/videos/tasks/{task_id}"
    interval = 3.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status in {"succeeded", "success"}:
            return data["video_url"]
        if status in {"failed", "error"}:
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = build_cinematic_prompt(
        subject="Matte black mechanical wristwatch resting on volcanic stone",
        camera_move="Orbit 180 + Slow Dolly In",
        lighting="Moody low-key rim lighting, subtle steam haze",
        lens="85mm macro lens",
    )
    task_id = dispatch_camera_shot(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

프롬프트 템플릿 버전을 작업 기록과 함께 저장하면 모델 변경과 문구 변경을 구분할 수 있습니다. 클라이언트 쪽 타임아웃은 업스트림 작업 실패의 증거가 아닙니다. 과금되는 작업을 다시 제출하기 전에 상태를 확인하세요.

기본 H3 duration은 4–15초 정수입니다. Max 계열 ID는 5초부터 시작하며 해상도 목록이 다릅니다. Turbo는 참조 미디어를 받지 않습니다. ID를 바꾸기 전에 API 가이드를 확인하세요.

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

아래 분류는 진단 출발점이며 ToAPIs의 정확한 오류 코드를 보장하지 않습니다.

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

5. 요금과 FinOps ROI

$\text{Estimated cost} = \text{successful output seconds} \times \text{current account rate per second}$

• 기획 초안의 단가를 재사용하지 마세요. 초당 요율, 과금 단위, 실패 작업 처리는 모델·경로·계정에 따라 다릅니다. 샷 리스트 비용을 예측하기 전에 현재 ToAPIs 카탈로그와 계정 견적을 확인하세요.
• 공식 벤더 계약에는 연간 약정, 좌석 할당, 선불 하한이 붙는 경우가 많습니다. ToAPIs는 일반적으로 사용량 과금입니다. 계정에 표시된 현행 조건을 확인하세요.
• 프롬프트 계층에서 지출을 제어하세요. 버전 있는 템플릿을 쓰고, 한 번에 변수 하나만 바꾸며, 클라이언트 타임아웃 뒤에는 상태를 확인한 다음 재제출을 결정하세요.
• 기본 H3, canonical Max, Turbo의 선택은 검증되지 않은 속도·품질 점수가 아니라 선택 가이드를 따르세요.

6. 자주 묻는 질문

구조화된 FAQ는 frontmatter를 보세요. 요약: 프롬프트는 카메라 의도로 시작하고, 복합 카메라 표현은 보장된 문법이 아닌 프롬프트 텍스트이며, 같은 문구는 첫 프레임 모드에도 적용되고, 대괄호 태그는 공식 API 매개변수가 아닙니다.

7. 액션 체크리스트

• ToAPIs Developer Portal에서 키를 발급합니다.
• minimax-h3, ratio: "16:9", 6초 duration으로 cURL 예제를 스모크 테스트합니다.
• 프롬프트 도우미를 도입하고 템플릿 버전을 저장하며 180초 제한으로 폴링합니다.
• 이어서 H3 API 요청 계약과 자동 R2V 파이프라인을 읽습니다.