MiniMax H3 API 가이드: 텍스트-투-비디오 및 참조 미디어

MiniMax H3의 모든 모델 변형을 같은 사양으로 취급하면 요청이 실패하기 쉽습니다. 모델 ID에 따라 길이와 해상도 검증이 달라지고, 입력 모드에 따라 시작/끝 프레임과 참조 이미지, 비디오, 오디오를 함께 보낼 수 있는지가 결정됩니다.

이 문서는 2026년 10월 22일 기준 ToAPIs 프런트엔드에 구현된 요청 계약을 설명합니다. 상위 모델의 성능 테스트나 현재 계정 가격을 나타내지는 않습니다. 운영 요청을 보내기 전에 계정에서 모델을 사용할 수 있는지 확인하세요.

빠른 시작

ToAPIs API 예제는 POST /v1/videos/generations로 비디오 생성 작업을 제출합니다. Bearer API Key, 활성화된 모델 ID, 프롬프트, 길이 및 화면 비율을 지정합니다.

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": "A slow cinematic pan across a quiet coastal town at sunrise",
    "duration": 5,
    "ratio": "16:9"
  }'

생성은 비동기 작업입니다. 계정 API 응답에서 작업 식별자를 읽고 계정 문서에 명시된 상태 조회 엔드포인트를 사용하세요. 문서에 명시되지 않았다면 응답 JSON의 특정 경로를 임의로 가정하지 마세요.

import os
import requests

BASE_URL = "https://api.toapis.com/v1"
headers = {"Authorization": f"Bearer {os.environ['TOAPIS_API_KEY']}"}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json={
        "model": "minimax-h3",
        "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
        "duration": 5,
        "ratio": "16:9",
    },
    timeout=30,
)
response.raise_for_status()
print("Submission response:", response.json())

예제는 작업 ID나 비디오 URL 위치를 추측하지 않고 응답을 출력합니다. 응답 파싱은 계정용 API 스키마에 맞추세요. 그래야 응답 구조가 바뀌었을 때 미완료 작업을 성공으로 잘못 처리하지 않습니다.

정확한 모델 ID 선택

프런트엔드는 기본 계열 ID로 minimax-h3와 minimax-h3-global을 인식하고, minimax-h3-max를 포함하는 ID도 인식합니다. Turbo 모델 ID는 minimax-h3-max-turbo입니다. 모델 카탈로그의 전체 ID를 사용하고 임의로 축약하거나 별칭을 추측하지 마세요.

현재 프런트엔드가 검증하는 사양은 다음과 같습니다.

이는 프런트엔드 검증 조건이며 모든 계정이나 상위 경로에서 동일한 기능을 사용할 수 있다는 보장은 아닙니다. 현재 클라이언트는 정확한 ID가 minimax-h3-max일 때만 1080P를 추가합니다. Turbo, -global 별칭 또는 모든 H3 모델이 1080P를 지원한다고 추론하지 마세요.

두 입력 모드 중 하나 선택

H3 폼은 서로 함께 사용할 수 없는 두 가지 흐름을 지원합니다.

1. 프레임 모드: first_frame_image는 최대 1개, last_frame_image도 최대 1개입니다. 프레임 입력이 있으면 클라이언트가 화면 비율을 adaptive로 설정합니다.
2. 참조 미디어 모드: 시작/끝 프레임 없이 참조 이미지, 비디오 및/또는 오디오를 제공합니다. 선택한 화면 비율이 사용됩니다.

시작 프레임 요청 예제:

{
  "model": "minimax-h3",
  "prompt": "The subject turns toward the camera as the camera gently moves forward",
  "duration": 5,
  "ratio": "16:9",
  "first_frame_image": ["https://example.com/starting-frame.jpg"]
}

참조 미디어 요청 예제:

{
  "model": "minimax-h3",
  "prompt": "Use the supplied references to guide the scene and motion",
  "duration": 5,
  "ratio": "16:9",
  "media_mode": "reference",
  "reference_images": ["https://example.com/character-reference.jpg"],
  "reference_videos": ["https://example.com/motion-reference.mp4"]
}

업로드 미디어의 실제 값 형식은 게이트웨이 업로드 절차에 따라 달라집니다. 위 예제는 요청 필드를 설명할 뿐 모든 경로가 임의의 공개 URL을 허용한다는 뜻은 아닙니다. 문서화된 업로드 절차에서 반환한 URL 또는 미디어 ID를 사용하세요.

현재 프런트엔드는 참조 이미지 최대 9개, 비디오 최대 3개, 오디오 최대 3개를 허용하며 전체 참조 개수는 12개 이하여야 합니다. 각 참조 비디오는 2~15초이고 전체 비디오 길이는 15초를 넘을 수 없습니다. 오디오 참조에는 시각 미디어가 최소 하나 필요합니다. Turbo 요청에는 참조 미디어를 넣을 수 없습니다.

제출 전에 모드, 개수, 길이를 검증하세요. 입력 모드를 섞거나 개수를 초과하거나 시각 참조가 없으면 프런트엔드에서 요청을 거부합니다.

프롬프트, 비율, 옵션

프롬프트는 필수이며 현재 프런트엔드는 Unicode 문자 7,000자까지 허용합니다. 피사체, 장면, 동작, 시각적 의도를 일반 문장으로 작성하세요. 상위 문서에서 특수 문법을 정의하지 않았다면 [Pan Left] 같은 문자열은 일반 프롬프트 텍스트로 취급해야 합니다. 프런트엔드 계약만으로 해당 문자열이 H3 기본 명령이라고 확인할 수 없습니다.

요청 빌더는 모델 경로에 따라 prompt_optimizer, watermark, seed 같은 옵션을 처리합니다. 모든 상위 채널에서 동일하게 허용된다고 가정하지 마세요. 모델을 바꾸면 이전 모델에서 남은 비호환 필드도 제거해야 합니다.

프런트엔드가 허용하는 비율은 adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16입니다. 프레임 입력은 adaptive로 고정됩니다. 텍스트-투-비디오에서 adaptive를 고르면 16:9로 정규화되고, 참조 미디어 모드에서는 선택한 지원 비율이 유지됩니다.

비율은 화면 모양을, 해상도는 모델 경로에서 허용하는 출력 크기를 의미합니다. 모델별 옵션의 대소문자도 다를 수 있습니다(768p, 768P). 선택한 모델의 계약을 확인하지 않은 채 전체 필드를 일괄 변환하지 마세요.

상태 조회, 오류 및 재시도

작업을 제출한 뒤 작업 ID를 저장하고 계정 문서의 상태 엔드포인트를 조회하세요. 최대 대기 시간과 횟수가 정해진 백오프를 사용하고 작업 실패와 클라이언트 대기 시간 초과를 구분하세요. 클라이언트 타임아웃만으로 상위 작업 실패를 단정할 수 없습니다. 과금될 수 있는 요청을 다시 제출하기 전에 기존 작업 상태를 확인해 중복 생성을 막으세요.

클라이언트는 HTTP 상태를 확인하고, 공개된 스키마에 따라 응답을 파싱하며, 문서화된 종료 상태에서 폴링을 끝내야 합니다. 재시도 횟수와 전체 경과 시간도 제한하세요. 요청 또는 작업 식별자는 로그에 남길 수 있지만 API Key와 비공개 미디어 URL은 기록하지 마세요.

이는 일반적인 진단 범주이며 ToAPIs의 모든 경로에서 동일한 오류 코드가 반환된다는 뜻은 아닙니다.

가격, 개인정보 및 출시 점검

가격, 가동 시간, 환불 정책 및 SLA는 모델, 경로, 계정에 따라 달라질 수 있습니다. 이 문서는 초당 가격이나 가용성 SLA를 인용하지 않습니다. 현재 모델 카탈로그와 계정 가격을 확인하고 기획 초안의 가격을 운영 견적으로 사용하지 마세요.

참조 미디어는 사용자 데이터로 취급하세요. 업로드 전에 파일 형식, 크기, 개수를 확인하고 사용 권한이 있는 미디어만 처리하세요. 데모를 위해 개인 자료를 공개 URL에 올리지 말고 임시 미디어 URL을 장기 로그에 남기지 마세요.

출시 전에는 계정에서 활성화된 각 모델에 유효한 요청을 테스트하고, 소수 길이, 미지원 해상도, 참조 초과, 모드 혼합, Turbo 참조 미디어를 음성 테스트로 추가하세요. 모델을 변경하면 호환되지 않는 입력이 지워지는지도 확인해야 합니다. 응답 필드와 작업 상태는 로컬 픽스처나 승인된 테스트 계정으로 확인하세요. 이 문서는 운영 API를 호출해 동작을 확인하지 않았습니다.

관련 링크

• 비디오 모델 둘러보기
• Playground에서 MiniMax H3 열기
• Playground에서 MiniMax H3 Max Turbo 열기