MiniMax H3 비디오 생성 API 연동 가이드

본 문서에서는 MiniMax H3 비디오 생성 API의 연동 및 사용 방법을 소개합니다. 이 인터페이스는 텍스트-비디오 생성, 첫/마지막 프레임 제어 및 멀티모달 참조 비디오 생성을 지원하며, 통합된 V2 멀티모달 content 구조를 사용하여 작업을 생성합니다.

신청 절차

MiniMax H3 비디오 생성 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 보관해 두세요.

아직 로그인하거나 가입하지 않은 경우, 로그인 페이지로 자동 이동하여 가입 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.

📘 전체 문서: MiniMax H3 비디오 생성 API →

Token은 환경 변수로 저장하고, 소스 코드에 작성하거나 버전 저장소에 커밋하지 않는 것을 권장합니다:

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

인터페이스 개요

Base URL：https://api.acedata.cloud
Endpoint：POST /minimax/videos
인증 방식：HTTP Header에 authorization: Bearer {token} 포함
요청 헤더：
- accept: application/json
- content-type: application/json
모델（model）：MiniMax-H3
입력 구조：content를 통해 텍스트, 이미지, 비디오 및 오디오를 통합 전달
출력 모드：기본적으로 생성 완료까지 동기 대기하고 전체 task를 반환합니다. async: true 또는 callback_url을 전달하면 즉시 task_id와 trace_id를 반환합니다.
결과 조회：MiniMax H3 작업 조회 API를 통해 상태와 완성 영상을 가져옵니다.
비동기 콜백：선택 사항이며, callback_url을 통해 최종 작업 결과를 수신합니다.

생성 모드를 선택하기 위해 action을 전달할 필요가 없으며, 인터페이스가 content 내 소재의 유형과 role에 따라 용도를 자동으로 판단합니다.

적합한 시나리오

시나리오	입력 조합	일반적인 용도
텍스트-비디오 생성	텍스트	광고 크리에이티브, 스토리보드 사전 시각화, 숏폼 비디오, 분위기 샷
첫 프레임 이미지-비디오 생성	텍스트 + 첫 프레임 이미지	상품 이미지, 포스터, 인물 사진 또는 일러스트를 자연스럽게 움직이게 함
마지막 프레임 / 첫·마지막 프레임 비디오	텍스트 + 마지막 프레임, 또는 텍스트 + 첫 프레임 + 마지막 프레임	오프닝과 엔딩, 전환, 성장 변화 및 전후 비교 제어
멀티모달 참조 비디오 생성	텍스트 + 참조 이미지 / 비디오 / 오디오	캐릭터와 제품의 일관성 유지, 동작, 카메라 워크, 음색 또는 편집 리듬 재현

호출 절차

기본적으로 async를 전달하지 않으면 /minimax/videos는 생성 완료까지 대기한 후 전체 task를 직접 반환합니다. 즉시 연결을 해제해야 하는 경우 async: true 또는 callback_url을 전달하세요:

즉시 응답의 task_id와 trace_id를 저장합니다.
콜백을 구성하지 않은 경우 약 10초마다 /minimax/tasks를 호출하여 한 번씩 조회합니다.
task.status가 succeeded로 변경되면 task.content.url에서 비디오를 가져옵니다.
상태가 failed 또는 cancelled이면 폴링을 중지하고 task.error를 읽습니다.

최상위 요청 파라미터

파라미터	유형	필수	기본값	설명
`model`	string	예	-	`MiniMax-H3`로 고정
`content`	object[]	예	-	멀티모달 콘텐츠 배열이며, 비어 있지 않은 `text` 항목을 반드시 포함해야 함
`resolution`	string	예	-	`768P` 또는 `2K`
`duration`	integer	예	-	생성 길이, 4-15초 정수
`ratio`	string	조건부 필수	`adaptive`	`adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
`async`	boolean	아니요	`false`	`true`일 때 즉시 작업 식별자를 반환하며, 작업 인터페이스를 통해 결과를 가져옴
`callback_url`	string	아니요	-	최종 작업 결과를 수신할 공개 콜백 URL; 제공 시 비동기 모드가 자동 활성화됨

ratio의 규칙은 워크플로에 따라 다릅니다:

텍스트-비디오 생성：필수이며, adaptive일 수 없습니다.
첫 프레임, 마지막 프레임 또는 첫·마지막 프레임 비디오：화면 비율은 입력 이미지에 의해 결정되며, 생략하거나 adaptive를 전달하는 것을 권장합니다.
멀티모달 참조 비디오 생성：생략할 수 있으며, 기본값은 adaptive입니다. 고정 비율을 명시적으로 지정할 수도 있습니다.

인터페이스는 prompt, image_urls, audio_urls, messages, first_frame_image와 같은 구버전 또는 호환 필드를 허용하지 않습니다. 이러한 파라미터 오류를 받으면 구 필드를 삭제하고 content로 마이그레이션하세요. 예를 들어 "prompt": "고양이가 손을 흔든다"를 "content": [{"type": "text", "text": "고양이가 손을 흔든다"}]로 변경합니다. 새 형식과 구 형식을 동시에 전송하지 마세요.

content 콘텐츠 항목 파라미터

각 콘텐츠 항목에는 반드시 type이 있어야 하며, 나머지 필드는 유형에 따라 결정됩니다:

`type`	데이터 필드	`role`	설명
`text`	`text`	전달하지 않음	모든 요청은 비어 있지 않은 텍스트 항목을 반드시 포함해야 하며, 최대 7000자
`image_url`	`image_url.url`	`first_frame`	첫 프레임 이미지; 이미지가 한 장뿐이고 `role`을 생략한 경우에도 첫 프레임으로 처리
`image_url`	`image_url.url`	`last_frame`	마지막 프레임 이미지; 단독으로 사용할 수도 있고, `first_frame`과 결합하여 시작점과 종료점을 제어할 수도 있음
`image_url`	`image_url.url`	`reference_image`	참조 주체, 캐릭터, 제품, 의상, 장면 또는 스타일
`video_url`	`video_url.url`	`reference_video`	참조 동작, 카메라 워크, 연기 또는 편집 구조
`audio_url`	`audio_url.url`	`reference_audio`	참조 음색, 대사, 음악 또는 리듬

미디어 주소는 세 가지 형식을 지원합니다:

공개적으로 접근 가능한 HTTPS URL이며, 대용량 파일에 권장됩니다.
mm_file://{file_id}이며, 이미 업로드했거나 기존 결과의 파일을 참조합니다.
해당 미디어 유형의 Base64 data URI입니다. Base64는 용량을 약 3분의 1 증가시키므로 전체 요청 본문이 64 MB를 초과하지 않도록 하세요.

소재 사양 및 수량 제한

소재	형식	단일 파일 제한	크기 / 길이	수량 제한
이미지	JPG, JPEG, PNG, WEBP, HEIC, HEIF	30 MB 이하	너비와 높이 모두 256-5760 px; 가로세로비 0.4-2.5	첫 프레임 최대 1장, 마지막 프레임 최대 1장, 참고 이미지 최대 9장
비디오	MP4, MOV; H.264/AVC 또는 H.265/HEVC; 오디오 트랙 AAC 또는 MP3	50 MB 이하	각 구간 2-15초, 합계 15초 이하; 너비와 높이 모두 256-5760 px; 가로세로비 0.4-2.5; 23.976-60 fps	참고 비디오 최대 3개
오디오	WAV, MP3	15 MB 이하	각 구간 2-15초, 합계 15초 이하	참고 오디오 최대 3개

멀티모달 참고 시나리오의 이미지, 비디오 및 오디오는 합계 최대 12개 파일입니다. 첫·마지막 프레임 시나리오와 참고 소재 시나리오는 상호 배타적입니다. reference_image, reference_video 또는 reference_audio를 사용하면 first_frame 또는 last_frame을 더 이상 사용할 수 없으며, 그 반대도 마찬가지입니다.

프로덕션급 역량 시연

아래는 콘셉트 이미지나 자리표시자 소재가 아니라 MiniMax H3 공식 프로덕션급 역량 샘플의 실제 참고 입력과 실제 비디오 출력입니다. 세 가지 사례는 각각 브랜드 단편, 실사 내러티브 및 패션 이커머스를 다루며, 상업 제작에서 가장 중요한 모델 역량을 평가하는 데 적합합니다.

역량	중점 관찰 사항
인물 및 얼굴 일관성	다중 샷 전환 후 이목구비, 헤어스타일, 메이크업 및 인물 분위기가 안정적인지
얼굴 연기	클로즈업 속 눈빛, 미세 표정, 감정적 긴장감 및 자연스러운 머리 움직임
상품 구조 유지	안경, 핸드백 등 제품의 윤곽, 소재, 착용 관계 및 렌즈 반사
브랜드 비주얼 구현	장면 분위기, 필름 그레인, 색상, Logo 및 편집 리듬이 통일되는지
영화적 서사	샷 크기 변화, 인물 동선, 카메라 움직임, 리듬 및 사운드가 완전한 단락을 형성할 수 있는지

여기서 “얼굴 역량”은 비디오 생성에서의 인물 외관 일관성, 얼굴 디테일 및 연기 제어를 의미하며, 신원 인식, 얼굴 비교 또는 얼굴 교체 인터페이스를 의미하지 않습니다.

고급 브랜드 단편: 인물, 제품 및 브랜드 자산의 통일

제작 목표: 16:9 고급 패션 브랜드 영상. 황야 도로와 빈티지 자동차로 냉철한 분위기를 구축하고, 여주인공의 외관과 검은색 핸드백 구조를 유지하며, 브랜드 Logo를 결말에 자연스럽게 포함합니다. 이 사례는 샷 간 인물 일관성, 상품 유지, 영화적 질감 및 브랜드 마무리 역량을 중점적으로 검증합니다.

분위기 및 장면 참고	인물 참고

핸드백 제품 참고	브랜드 Logo 참고

브랜드 단편 직접 열기 또는 다운로드 해당하는 content 구성 방식:

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "15 秒、16:9 高级时装品牌片。荒漠公路旁停着复古汽车，女主从后备箱取出黑色手袋，与男主短暂对视后独自离开。保持人物、手袋与品牌视觉一致；冷峻高级，电影颗粒，剪辑利落，结尾自然呈现品牌 Logo。"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/6e65f865-f1c2-4f80-8b51-9a98d4d930b1" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/88d89cc3-e6cb-42b4-ab4c-1bbbf6c9f7c8" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/e91f7fff-f8e3-4da5-b882-87edbc3c9473" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://cdn.acedata.cloud/uploads/b68dac43-fb14-42b5-bf8b-fd4d65506520" },
      "role": "reference_image"
    }
  ],
  "resolution": "2K",
  "duration": 15,
  "ratio": "16:9"
}

실사 세로형 단편 드라마: 얼굴 일관성과 감정 연기

제작 목표: 15초, 9:16 다크 로맨스 숏드라마 예고편. 남녀 주인공 참고 이미지를 통해 인물 외형을 고정하고, 고성 참고 이미지로 공간을 제약한다. 중근경과 얼굴 클로즈업을 사용해 시선 대치, 공포, 절제와 위험감을 표현한다. 이 사례는 실사 얼굴 이목구비의 안정성, 미세 표정, 시선 관계와 연속 연기를 관찰하기에 적합하다.

남녀 주인공 참고	고성 장면 참고

실사 숏드라마 직접 열기 또는 다운로드 프롬프트는 단순히 “남녀 대화”를 묘사하는 것이 아니라 인물 관계, 감정과 숏 크기를 명확히 해야 한다:

15 秒、9:16 真人暗黑浪漫短剧预告。女主误入禁忌古堡，唤醒沉睡的吸血鬼贵族；
他危险而克制地靠近，她恐惧但不屈服。保持两位角色的五官、发型与服装一致，
以中近景和面部特写表现眼神对峙与情绪张力，暗色电影光线，节奏紧凑。

패션 안경 광고: 얼굴 디테일과 제품 구조 유지

제작 목표: 9:16 고급 패션 안경 광고. 인물 전신 이미지는 체형과 워킹을 담당하고, 얼굴 참고 이미지는 이목구비와 메이크업을 담당하며, 제품 이미지는 곡선, 렌즈 반사, 안경다리와 캣아이 윤곽을 담당한다. 이 사례는 얼굴 근경, 다인 일관성, 착용 관계와 제품 기하학적 구조를 동시에 시험한다.

모델 및 스타일링 참고	얼굴 디테일 참고	안경 제품 참고

패션 안경 광고 직접 열기 또는 다운로드 제품 광고에서는 프롬프트가 인물 참고와 제품 참고의 역할을 분리하여 명확하게 작성해야 한다: 인물 소재는 얼굴, 메이크업, 체형과 분위기를 제약하고, 제품 소재는 윤곽, 재질, 반사와 착용 위치를 제약한다. 이는 두루뭉술하게 “안경 광고 하나 생성”이라고 쓰는 것보다 더 안정적이다.

텍스트-비디오 생성

텍스트 항목이 하나뿐인 경우 텍스트-비디오 생성이다. 창의안, 스크립트 또는 숏 설명에서 직접 화면을 생성하기에 적합하다. 프롬프트는 “주체 + 동작 + 장면 + 카메라 + 조명 + 사운드” 순서로 구성할 수 있다.

curl -X POST 'https://api.acedata.cloud/minimax/videos' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "15 秒电影级香水广告：清晨海岸的黑色礁石上，透明香水瓶被薄雾与海浪环绕。微距展现瓶身水珠和玻璃折射，镜头从产品特写缓慢拉升到广阔海面；银蓝色调，真实自然光，高级克制，结尾定格产品。"
      }
    ],
    "resolution": "2K",
    "duration": 15,
    "ratio": "16:9"
  }'

기본 동기 모드는 생성 완료 후 전체 작업을 반환한다:

{
  "task": {
    "id": "f5977217-ed2c-40da-adbe-93d08235618f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": { "url": "https://cdn.acedata.cloud/minimax/f5977217.mp4" },
    "resolution": "2K",
    "duration": 15,
    "ratio": "16:9"
  }
}

요청에 "async": true를 추가하면 인터페이스는 즉시 반환한다:

{
  "task_id": "f5977217-ed2c-40da-adbe-93d08235618f",
  "trace_id": "trace_7f8c2b1a"
}

첫 프레임 이미지-비디오 생성

이미지를 first_frame으로 표시하면 모델은 해당 화면에서 생성하기 시작한다. 포스터, 제품 이미지, 캐릭터 설정 이미지와 사진 작품을 자연스럽게 움직이게 하기에 적합하다.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "人物自然呼吸并看向窗外，衣角被微风吹动，镜头缓慢推进"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.acedata.cloud/b1c82e4937.png"
      },
      "role": "first_frame"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

마지막 프레임 및 시작·끝 프레임 비디오

last_frame만 제공하면 모델이 지정된 화면까지 자연스럽게 생성할 수 있습니다. first_frame과 last_frame을 동시에 제공하면 시작점과 종점을 명확하게 제어할 수 있습니다. 전환, 형태 변화, 성장 과정 또는 제품 전후 비교에 적합합니다.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "女孩从童年自然成长为青年，时间流逝平滑，人物始终位于画面中央"
    },
    {
      "type": "image_url",
      "image_url": { "url": "YOUR_FIRST_FRAME_URL" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "YOUR_LAST_FRAME_URL" },
      "role": "last_frame"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

첫 프레임과 마지막 프레임의 크기 및 가로세로 비율은 가능한 한 일치해야 하며, 피사체 위치, 구도 및 조명의 차이가 너무 크지 않아야 합니다. 이렇게 하면 자연스러운 전환을 더 쉽게 얻을 수 있습니다.

멀티모달 참조 기반 비디오 생성

참조 소재는 조합하여 사용할 수 있습니다. 참조 이미지는 캐릭터 또는 제품 외관을 제어하고, 참조 비디오는 동작과 카메라 워크를 제어하며, 참조 오디오는 대사 음색, 음악 또는 편집 리듬을 제어합니다. 프롬프트에서 각 유형의 소재가 무엇을 제어해야 하는지 명확히 설명해야 하며, 소재만 업로드하고 연관 관계를 제공하지 않는 것을 피해야 합니다.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "保持参考人物的五官、发型与服装一致，按照参考视频中的表演动作完成时尚短片；镜头节奏跟随参考音频，近景突出自然面部表情"
    },
    {
      "type": "image_url",
      "image_url": { "url": "YOUR_CHARACTER_IMAGE_URL" },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": { "url": "YOUR_PERFORMANCE_VIDEO_URL" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "YOUR_AUDIO_URL" },
      "role": "reference_audio"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

콜백 알림

callback_url을 전달하면 비동기 모드가 자동으로 활성화됩니다. 생성 인터페이스는 즉시 task_id와 trace_id를 반환하며, 작업 완료 후 해당 주소로 최종 결과를 POST합니다. 구조는 작업 조회 응답과 동일합니다. 콜백의 최종 상태는 succeeded, failed 또는 cancelled입니다. 콜백을 사용하더라도 task_id를 저장하는 것이 좋습니다. 이를 통해 능동적으로 조회하거나 누락된 알림을 보완할 수 있습니다.

일반적인 오류

HTTP 상태 코드	의미	처리 권장 사항
`400`	매개변수 오류 또는 소재 조합이 유효하지 않음	필수 필드, `role`, 소재 수량 및 형식을 확인
`401`	Token 누락 또는 유효하지 않음	`Authorization: Bearer ...`를 확인
`402`	잔액 또는 한도가 부족함	콘솔에서 공용 잔액을 충전
`422`	콘텐츠 보안 검사를 통과하지 못함	프롬프트 또는 소재를 조정한 후 다시 제출
`429`	요청이 너무 빈번함	지수 백오프 후 재시도; 작업 폴링은 약 10초 간격 권장
`500`	서비스를 일시적으로 사용할 수 없음	요청 정보를 보관하고 나중에 재시도

동기 응답의 task.status: succeeded는 비디오가 생성되었음을 의미하며, 비동기 확인은 작업이 대기열에 들어갔음을 의미할 뿐입니다. 작업이 최종적으로 성공한 경우에만 과금되며, 작업 조회 자체는 무료이고 중복 차감되지 않습니다.

H3 Max

MiniMax-H3-Max는 480P 또는 768P, 5–15초의 정수 길이를 지원합니다. 오디오 입력은 추가 과금되지 않으며, 처음 2장의 이미지는 무료이고 초과분은 장당 과금됩니다. 참조 비디오는 실제 입력 길이를 기준으로 과금됩니다. 이 모델은 2K를 지원하지 않습니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

MiniMax H3 비디오 생성 API 연동 가이드

신청 절차

인터페이스 개요

적합한 시나리오

호출 절차

최상위 요청 파라미터

content 콘텐츠 항목 파라미터

소재 사양 및 수량 제한

프로덕션급 역량 시연

고급 브랜드 단편: 인물, 제품 및 브랜드 자산의 통일

실사 세로형 단편 드라마: 얼굴 일관성과 감정 연기

패션 안경 광고: 얼굴 디테일과 제품 구조 유지

텍스트-비디오 생성

첫 프레임 이미지-비디오 생성

마지막 프레임 및 시작·끝 프레임 비디오

멀티모달 참조 기반 비디오 생성

콜백 알림

일반적인 오류

H3 Max

​신청 절차

​인터페이스 개요

​적합한 시나리오

​호출 절차

​최상위 요청 파라미터

​content 콘텐츠 항목 파라미터

​소재 사양 및 수량 제한

​프로덕션급 역량 시연

​고급 브랜드 단편: 인물, 제품 및 브랜드 자산의 통일

​실사 세로형 단편 드라마: 얼굴 일관성과 감정 연기

​패션 안경 광고: 얼굴 디테일과 제품 구조 유지

​텍스트-비디오 생성

​첫 프레임 이미지-비디오 생성

​마지막 프레임 및 시작·끝 프레임 비디오

​멀티모달 참조 기반 비디오 생성

​콜백 알림

​일반적인 오류

​H3 Max

신청 절차

인터페이스 개요

적합한 시나리오

호출 절차

최상위 요청 파라미터

content 콘텐츠 항목 파라미터

소재 사양 및 수량 제한

프로덕션급 역량 시연

고급 브랜드 단편: 인물, 제품 및 브랜드 자산의 통일

실사 세로형 단편 드라마: 얼굴 일관성과 감정 연기

패션 안경 광고: 얼굴 디테일과 제품 구조 유지

텍스트-비디오 생성

첫 프레임 이미지-비디오 생성

마지막 프레임 및 시작·끝 프레임 비디오

멀티모달 참조 기반 비디오 생성

콜백 알림

일반적인 오류

H3 Max