개요
MiniMax H3(Hailuo 3.0)는 MiniMax가 2026-07-31 (UTC+8)에 출시한 옴니모달 동영상 모델입니다. 단일 모델이 텍스트, 이미지, 동영상, 오디오를 입력받아 스테레오 오디오 트랙이 포함된 동영상을 출력합니다. APIYI는 공개 가중치를 자체 호스팅한 배포 환경에서MiniMax-H3을 제공하며, 해상도는 768P, 클립당 길이는 4~15초이고 초당 과금됩니다.
주요 특징: 하나의 엔드포인트로 텍스트 기반 동영상 생성, 첫 프레임 / 마지막 프레임 / 첫 프레임과 마지막 프레임 기반 동영상 생성, 이미지 / 동영상 / 오디오 참조를 혼합한 생성을 지원합니다. 참조 이미지는 9개, 참조 동영상은 3개, 참조 오디오 클립은 3개까지 사용할 수 있으며, 전체 미디어 항목은 최대 12개입니다. 출력에는 스테레오 오디오 트랙이 포함됩니다. 출력 동영상과 입력 참조 동영상은 각각 초당 $0.03의 비용이 부과됩니다(공식 MiniMax API는 각각 $0.08을 부과합니다). 참조 동영상 없이 텍스트나 이미지로 10초 동영상을 생성하는 작업의 비용은 $0.30입니다. 실패한 작업은 자동으로 환불됩니다.
동영상 생성 API 참조 문서
작업을 생성하고 task_id로 조회하는 방법과 Python / cURL / Node.js 예제 및 실시간 플레이그라운드를 제공합니다
충전 보너스
충전 보너스로 실질 가격을 더 낮출 수 있습니다
AI 에이전트로 통합하기
이 prompt를 복사하여 Codex / Claude Code / Cursor에 붙여넣으십시오
에이전트는 먼저 이 페이지의 일반 텍스트 버전을 가져온 다음(문서 URL 뒤에 .md를 추가합니다), 사용 중인 기술 스택에 맞는 코드를 작성합니다. 흔히 발생하는 실수는 이미 명시되어 있습니다. 경로에는 /hailuo가 필요하고, 결과는 task 안에 있으며, duration는 4~15 사이의 정수여야 합니다.
이 프로젝트에서 MiniMax-H3 동영상 생성(텍스트 기반 동영상 / 첫 프레임 및 마지막 프레임 기반 동영상 / 참조 동영상)을 통합하거나 디버깅하십시오.
코드를 작성하기 전에 문서를 읽으십시오. 이 페이지의 일반 텍스트 버전은 https://docs.apiyi.com/en/api-capabilities/minimax-h3/overview.md 에서 가져오십시오. 매개변수와 코드 예제는 https://docs.ap … 에 있습니다.
- 엔드포인트:
POST https://api.apiyi.com/hailuo/v2/video_generation로 제출하고, 다음으로 조회하십시오 …
요구 사항은 총 10개입니다. 아래 버튼을 사용하여 전체 prompt를 복사하십시오.
이 prompt로 방지할 수 있는 실수
이 prompt로 방지할 수 있는 실수
APIYI의 MiniMax-H3는 왜 선택해야 합니까?
다양한 생성 모드
텍스트, 첫 프레임/마지막 프레임, 이미지 / 동영상 / 오디오 혼합 참조 생성을 지원하며, 전체 미디어 항목은 최대 12개입니다. 미디어 유형별 제한은 기술 사양을 참조하십시오.
초당 과금, 실패 시 환불
출력 동영상과 입력 참조 동영상은 각각 초당 $0.03이며, 실패한 작업은 전액 환불되고 제출 오류에는 요금이 부과되지 않습니다.
충전 보너스 중첩
충전 보너스와 함께 사용하여 실질 비용을 낮출 수 있습니다.
글로벌 액세스, 제한 없음
하나의 API 키로
api.apiyi.com에 직접 연결할 수 있으며, 해외 계정이 필요하지 않습니다.완전한 동영상 모델 라인업
동일한 키로 Seedance 2.0 / 2.5, Wan3.0, Wan2.7 등도 사용할 수 있습니다.
전문 지원
통합 관련 질문은 지원팀에 문의할 수 있으며, 엔터프라이즈 고객에게는 직접적인 온보딩 지원이 제공됩니다.
주요 기능
네이티브 스테레오 오디오
출력에는 prompt와 참조 오디오를 기반으로 한 스테레오 오디오 트랙이 포함되며, 사운드 생성과 참조 오디오 재사용을 지원합니다
7가지 화면 비율
21:9부터 9:16까지 6가지 고정 비율과 참조 이미지의 비율을 따르는 adaptive을 지원합니다4~15초 범위에서 1초 단위로 길이 설정
출력 길이를 1초 단위로 선택할 수 있으며, 참조 동영상은 입력 길이에 따라 별도로 과금됩니다
긴 prompt
prompt당 최대 7000자를 지원하므로 장면별 설명을 충분히 작성할 수 있습니다
첫 프레임/마지막 프레임 제어
첫 프레임만, 마지막 프레임만 또는 둘 다 제공하여 클립의 시작과 끝을 설정할 수 있습니다
여러 참조 이미지
참조 이미지를 최대 9개까지 사용할 수 있으며, prompt에서
<Picture 1> 등의 태그로 등장인물과 사물을 지정할 수 있습니다동영상의 모션 전이
참조 동영상을 최대 3개까지 사용하여 카메라 움직임과 동작 리듬을 복사할 수 있습니다
오디오 기반 동영상
참조 오디오 클립을 최대 3개까지 사용할 수 있으며, 영상이 음악이나 음성에 맞춰 움직입니다
가격
이 채널은 자체 배포 환경에서 MiniMax의 오픈 H3 가중치를 실행합니다. 공식 MiniMax API의 릴레이가 아니므로 별도의 가격이 적용됩니다.이 채널은 오픈 가중치를 자체 호스팅하는 배포 환경이며, 공식 MiniMax API와 별도로 가격이 책정되고 가격은 변경될 수 있습니다. 위 표는 참고용이며, 상단 탐색 메뉴의 모델 가격 탭이 기준입니다: 모델 가격.
platform.minimax.io/docs/guides/pricing-paygo의 공식 가격(2026-09-29 조회)입니다.과금 세부 정보:
- 출력 동영상: 초당 $0.03, 입력 참조 동영상: 초당 $0.03. 최종 과금은 업스트림에서 보고한 출력 및 입력 동영상 사용량을 기준으로 합니다. 입력 동영상 길이는
usage.input_seconds에서 가져옵니다. - 요청한
duration을 기준으로 요청이 수락되면 플랫폼이 출력 비용을 선결제합니다. 작업이 완료된 후 실제 사용량을 정산하고 차액을 추가 청구하거나 환불합니다. - 정산 로그에는 전체 비용이 다시 기록되는 것이 아니라 조정 금액만 기록됩니다. 최종 비용 = 선결제 금액 + 추가 청구액 − 환불액이며, 작업마다 과금 기록이 정확히 두 건씩 생성되는 것은 아닙니다.
- 참조 이미지(최대 9장)와 참조 오디오는 추가 요금이 없습니다.
- 실패한 작업(미디어 다운로드 실패, 지원되지 않는 형식, 실행 실패 등)은 자동으로 전액 환불됩니다.
- 제출 시 4xx / 5xx를 반환하는 요청은 과금되지 않습니다. 조회 및 다운로드는 무료입니다.
- 실질 비용을 낮추려면 충전 보너스를 참조하십시오.
이 예시는 과금 방식을 보여 줍니다. 가격은 변경될 수 있으므로 최신 요율은 상단 탐색 메뉴의 모델 가격에서 확인하십시오. 입력 길이에는 요청한 출력
duration이 아니라 업스트림에서 보고한 usage.input_seconds을 사용하십시오.
그룹 설정
MiniMax-H3는default 그룹에서 작동하며, svip 그룹에서도 작동하므로 전용 그룹이 필요하지 않습니다. Token의 과금 모델을 사용한 만큼 지불하는 우선 처리로 설정하는 것을 권장합니다. 호출 시 “현재 그룹에 사용 가능한 채널이 없습니다”가 반환되면 Token의 그룹에 이 모델이 포함되어 있지 않거나 model 값의 철자가 잘못된 것입니다(대소문자를 구분합니다).
기술 사양
예상 생성 시간
MiniMax-H3의 생성 시간은 주로 두 가지에 따라 달라집니다. 출력 시간과 참조 동영상 포함 여부입니다. 아래 표는 (UTC+8) 2026-09-29부터 2026-10-10까지 400건 이상의 작업을 성공적으로 완료한 결과를 바탕으로, 이 채널의 현재 상태를 반영한 것입니다.- 시간은 길이보다 더 빠르게 증가합니다: 15초 클립은 5초 클립보다 약 3배가 아니라 약 5배 더 오래 걸립니다.
- 참조 동영상이 가장 오래 걸립니다: 모델이 참조 동영상을 프레임 단위로 분석한 다음 새 프레임과 함께 계산하므로 작업량이 배로 증가합니다.
- 이 표를 기준으로 클라이언트 타임아웃을 설정합니다: 참조 동영상이 없는 작업에는 30분, 참조 동영상이 있는 작업에는 2시간을 설정해야 실행 중인 작업을 실패로 잘못 판단하지 않습니다.
이 수치는 이 채널에서 현재 측정된 값입니다. 시간에 민감한 작업의 경우 4–6초 클립으로 시작하거나 참조 동영상 대신 참조 이미지를 사용하십시오. 더 빠르고 품질이 높은 MiniMax 그룹이 곧 출시됩니다. 이 페이지와 변경 로그에서 안내하겠습니다.
API 엔드포인트
생성 모드
생성 모드는content[]의 미디어를 바탕으로 추론됩니다.
프롬프트에서 미디어 참조하기
각 미디어 유형은content[]에서의 순서에 따라 번호가 지정됩니다. 첫 번째와 두 번째 참조 이미지는 <Picture 1>와 <Picture 2>, 첫 번째 참조 동영상은 <Video 1>, 첫 번째 참조 오디오 클립은 <Audio 1>입니다. 예를 들면 다음과 같습니다.
참조 오디오 재사용 및 제한
type: "audio_url", audio_url.url, role: "reference_audio"을 사용해 오디오를 전송하세요. role: "reference_image"를 사용하면 이미지와 함께 사용할 수 있습니다.
content[]의 type: "text" 항목에서 text 필드에 <Audio 1>: fully_copy을 사용해 오디오 재사용을 안내하세요. 다음은 프롬프트의 retention_analysis 섹션에서 발췌한 내용입니다. 참조 오디오 및 완전한 시각적 설명과 함께 전송하세요.
fully_copy은 프롬프트의 오디오 재사용 지침이며, 별도의 JSON 매개변수나 원본 오디오 패스스루 스위치가 아닙니다. 이 채널에서 오디오 재사용을 테스트했지만, 출력은 모델이 생성합니다. 샘플 단위의 동일성, 추가 사운드가 없을 것, 참조 오디오가 끝난 뒤 엄격한 무음이 유지될 것은 보장되지 않습니다. 원본 사운드트랙을 완전히 변경 없이 유지해야 한다면 동영상 생성 후 오디오 트랙을 교체하고 직접 재생 시간을 일치시키세요.모범 사례
1
먼저 4~5초로 테스트합니다
초당 과금되므로 10~15초를 렌더링하기 전에 짧은 클립으로 구도와 스타일을 확인합니다
2
텍스트-동영상 변환에는 고정 비율을 사용합니다
16:9는 가로 방향, 9:16는 세로 방향, 21:9는 와이드스크린입니다. 첫 프레임이 있으면 adaptive가 이미지의 비율을 유지합니다3
안정적인 공개 스토리지에 미디어를 호스팅합니다
핫링크 보호나 만료된 서명으로 미디어 다운로드가 중단되지 않도록 자체 오브젝트 스토리지 또는 CDN의 직접 링크를 사용합니다
4
카메라 움직임과 사운드를 설명합니다
주제, 동작, 카메라 움직임, 조명, 원하는 음악과 음향 효과를 설명합니다. 모델이 이를 함께 생성합니다
5
10초마다 상태를 확인합니다
5초 클립은 보통 약 3분이 걸립니다. 참조 동영상이 없으면 전체 클라이언트 타임아웃을 30분으로, 참조 동영상이 있으면 2시간으로 설정합니다(「예상 생성 시간」 참조)
6
멱등성은 직접 처리합니다
비즈니스 ID와 task_id의 매핑을 유지합니다. 제출 시간이 초과되면 다시 제출하기 전에 기존 작업을 확인합니다
7
동영상을 즉시 저장합니다
GET으로
task.content.url를 다운로드하고 자체 스토리지에서 제공합니다오류 코드 및 재시도
클라이언트 팁: 제출 타임아웃을 60초로 설정합니다(피크 시간에는 제출에만 10초 이상 걸릴 수 있습니다). HTTP 500 오류와 네트워크 오류만 백오프를 적용해 재시도합니다. 실행 단계에서 발생한 모든 실패는 자동 환불되며, 다시 제출하면 새 요금이 부과됩니다.
FAQ
JSON 대신 웹 페이지가 표시되는 이유는 무엇입니까?
JSON 대신 웹 페이지가 표시되는 이유는 무엇입니까?
경로에
/hailuo 접두사가 누락되었습니다. 올바른 경로는 /hailuo/v2/video_generation 및 /hailuo/v2/query/video_generation/{task_id}입니다.2K 또는 1080P를 지원합니까?
2K 또는 1080P를 지원합니까?
이 채널은
768P만 지원합니다. 공식 MiniMax 모델은 2K를 지원하지만 이 채널에서는 제공하지 않습니다.1~3초로 설정할 수 있습니까?
1~3초로 설정할 수 있습니까?
아니요.
duration는 4에서 15 사이의 정수입니다.동영상에 소리가 포함됩니까? 소리를 끌 수 있습니까?
동영상에 소리가 포함됩니까? 소리를 끌 수 있습니까?
출력에는 스테레오 오디오 트랙이 포함되며 오디오 생성을 비활성화하는 매개변수는 없습니다.
generate_audio=false를 전달하면 HTTP 400 unsupported field generate_audio이 반환됩니다. 오디오가 필요하지 않다면 후처리에서 트랙을 제거하십시오.고정된 랜덤 시드를 설정할 수 있습니까?
고정된 랜덤 시드를 설정할 수 있습니까?
이 엔드포인트는
seed 매개변수를 지원하지 않으며, 이를 전달하면 HTTP 400 unsupported field seed가 반환됩니다. 또한 작업 쿼리는 재현성을 위한 실제 시드를 반환하지 않습니다.모델 리비전과 전체 실행 매개변수를 조회할 수 있습니까?
모델 리비전과 전체 실행 매개변수를 조회할 수 있습니까?
현재 생성 및 쿼리 엔드포인트는 모델 리비전이나 전체 실행 매개변수 스냅샷을 반환하지 않습니다. 쿼리에는
model, duration, ratio, resolution과 같은 메타데이터가 포함될 수 있지만, MiniMax-H3는 모델 이름일 뿐 배포된 가중치 스냅샷을 식별하지 않습니다.Idempotency-Key 헤더가 이중 과금을 방지합니까?
Idempotency-Key 헤더가 이중 과금을 방지합니까?
현재는 그렇지 않습니다. 동일한
Idempotency-Key로 다시 제출해도 별도로 과금되는 새 작업이 생성됩니다. 제출한 작업은 자체 애플리케이션에서 추적하십시오.실패한 작업도 과금됩니까?
실패한 작업도 과금됩니까?
아니요. 작업이
failed에 도달하면 전액이 자동으로 환불됩니다. 제출 단계에서 거부된 요청도 과금되지 않습니다.Base64 또는 로컬 파일을 전송할 수 있습니까?
Base64 또는 로컬 파일을 전송할 수 있습니까?
아니요. 모든 미디어는 공개 HTTPS URL이어야 합니다. 먼저 자체 오브젝트 스토리지에 업로드한 후 링크를 전달하십시오.
adaptive는 어떤 크기로 생성됩니까?
adaptive는 어떤 크기로 생성됩니까?
입력 이미지의 가로세로 비율을 따릅니다. 예를 들어 정사각형 이미지는 768×768, 16:9 이미지는 1344×768로 생성됩니다. 텍스트만 포함된 요청과 오디오만 포함된 요청에는
adaptive를 사용할 수 없습니다.15초보다 긴 참조 동영상은 오류로 처리됩니까?
15초보다 긴 참조 동영상은 오류로 처리됩니까?
단일 클립이 15초를 초과하면 처음 15초로 자동 잘립니다. 그러나 여러 참조 동영상의 합계가 15초를 초과하면 작업이 실패하고 환불됩니다.
생성에는 얼마나 걸립니까?
생성에는 얼마나 걸립니까?
5초 클립은 약 3분, 15초 클립은 약 13분이 걸립니다. 참조 동영상이 포함된 작업은 훨씬 오래 걸리며, 15초 기준 약 85분이 소요됩니다. 전체 표는 위의 “예상 생성 시간”을 참조하십시오.
동영상 URL은 얼마 동안 유효합니까?
동영상 URL은 얼마 동안 유효합니까?
빠르게 만료되는 현상은 확인되지 않았지만 장기적인 가용성은 보장되지 않으므로 동영상을 즉시 다운로드하여 저장하십시오. GET으로 URL을 확인하십시오. HEAD 요청은 403을 반환합니다.
제출 시 간헐적으로 500 Unknown Error가 반환되면 어떻게 해야 합니까?
제출 시 간헐적으로 500 Unknown Error가 반환되면 어떻게 해야 합니까?
먼저 요청 본문이 규칙을 따르는지 확인하십시오(텍스트 항목 정확히 하나, 추가 필드 없음, HTTPS 미디어 링크). 규칙을 따른다면 일시적인 과부하일 가능성이 높으므로 몇 초 기다린 후 다시 시도하십시오. 제출에 실패한 요청은 과금되지 않습니다.