Skip to main content
POST

인증

string
필수
모든 API 엔드포인트는 Bearer Token 인증이 필요합니다API 키 받기:API 키 관리 페이지에서 API 키를 받으세요요청 헤더에 추가:

생성 모드

MiniMax-H3 는 요청 필드에 따라 해당 모드로 자동 라우팅합니다. mode 필드는 필요하지 않습니다:
엄격한 상호 배타: 이미지-비디오 필드(first_frame_image / last_frame_image, 및 image_with_rolesfirst_frame / last_frame)와 멀티모달 참조 필드(image_urls, video_urls, audio_urls, 및 image_with_rolesreference_image)는 동시에 사용할 수 없습니다. 혼용 시 400 이 반환됩니다.
오디오만 단독 사용은 불가합니다. audio_urls 를 전달할 경우 참조 이미지 또는 참조 비디오를 최소 하나 함께 제공해야 합니다.

요청 매개변수

공통 필드

string
필수
고정값: MiniMax-H3
model 필드는 필수이며 명시적으로 전달해야 합니다. 이미 Hailuo 시리즈를 연동한 클라이언트는 modelMiniMax-H3 로 변경하기만 하면 본 모델을 사용할 수 있습니다.
string
필수
비디오 콘텐츠 설명. 모든 시나리오에서 필수이며 비어 있을 수 없습니다. 요청당 최대 7000 자.장면, 주체, 동작, 스타일 등을 자세히 설명하면 더 나은 생성 결과를 얻을 수 있습니다.예시: "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work"
integer
기본값:"5"
출력 길이(초)
  • 범위: 4 ~ 15 정수
  • 기본값: 5
string
기본값:"2K"
비디오 해상도
  • 지원 값: 2K 만 가능(기본값)
string
화면비. size 또는 ratio 로도 동일하게 전달할 수 있습니다.허용 비율: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16시나리오별 동작은 아래 “화면비 규칙”을 참조하세요.
boolean
기본값:"false"
AIGC 워터마크 추가 여부기본값: false호환 별칭: aigc_watermark
string
작업이 최종 상태(성공 / 실패)에 도달했을 때 본 서비스가 이 주소로 푸시합니다
webhook 을 사용하세요. 공식 callback_url 은 전달하지 마세요. callback_url 은 본 서비스 내부용이며 사용자 입력을 받지 않습니다.

이미지-비디오 필드

첫 / 끝 프레임 이미지-비디오를 수행하려면 역할을 명시적으로 지정하세요. image_urls 개수로 추론하지 마세요.
string
첫 프레임 이미지 URL전달 시 해당 이미지가 비디오의 시작 프레임으로 사용됩니다.
string
끝 프레임 이미지 URL전달 시 해당 이미지가 비디오의 종료 프레임으로 사용됩니다. first_frame_image 와 조합하여 첫+끝 프레임 제어가 가능합니다.

멀티모달 참조 필드

string[]
참조 이미지 URL 배열
image_urls 의 이미지는 개수와 관계없이 모두 참조 이미지(reference_image)로 처리됩니다. 개수에 따라 첫 / 첫+끝 프레임으로 자동 매핑되지 않습니다.
  • 수량: ≤ 9
string[]
참조 비디오 URL 배열
  • 수량: ≤ 3
  • 형식 및 제한: 아래 “입력 미디어 제한” 참조
string[]
참조 오디오 URL 배열
  • 수량: ≤ 3
  • 단독 사용 불가. 참조 이미지 또는 참조 비디오와 함께 사용해야 합니다

공통 이미지 배열(선택 형식)

object[]
역할이 지정된 이미지 배열. first_frame_image / last_frame_image / image_urls 를 대체할 수 있습니다. 각 요소 구조:예시(첫 + 끝 프레임):
예시(참조 이미지):

화면비 규칙

허용되는 구체적 비율: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16.

입력 미디어 제한

요청 본문 총 크기 ≤ 64 MB. 큰 파일은 공개 URL 을 사용하고, Base64 는 사용하지 마세요.

이미지

비디오(멀티모달 참조 전용)

오디오(멀티모달 참조 전용)

매개변수 제약

다음 제약을 위반하면 요청이 거부되고 400 이 반환됩니다(민감 콘텐츠는 422 가능). 과금되지 않습니다:

응답

integer
응답 상태 코드. 성공 시 200
array
응답 데이터 배열

요청 예시

케이스 1: 텍스트-비디오

케이스 2: 이미지-비디오 — 첫 프레임

케이스 3: 이미지-비디오 — 첫 + 끝 프레임

케이스 4: 멀티모달 참조-비디오

케이스 5: image_with_roles 로 첫 + 끝 프레임 지정

작업 결과 조회비디오 생성은 비동기 작업으로, 제출 후 task_id 가 반환됩니다. 작업 상태 가져오기 엔드포인트를 사용하여 생성 진행 상황과 결과를 조회하세요.권장 폴링 간격: 5 ~ 10초마다. 클라이언트 타임아웃: 15분. 성공 시 result.videos[0].url 이 mp4 URL 입니다. 비디오 URL 은 약 24시간 후 만료되므로 즉시 저장하세요. 실패한 작업은 자동으로 환불됩니다.