튜토리얼

MiniMax H3 API 튜토리얼: 텍스트 투 비디오, 첫/마지막 프레임 및 멀티모달 레퍼런스

텍스트 투 비디오부터 첫/마지막 프레임과 멀티모달 레퍼런스까지, MiniMax H3의 세 가지 워크플로, 소재 경계 및 프로덕션 연동 방식을 이해합니다.

Aug 27, 2026

MiniMax H3는 MiniMax의 범용 멀티모달 비디오 생성 모델입니다. 텍스트, 이미지, 비디오, 오디오 소재를 이해하고 네이티브 사운드가 포함된 짧은 비디오를 생성합니다. HiAPI로 연동할 때 모델 ID는 minimax-h3로 고정되며, 이미지, 비디오, 오디오 모델 모두 동일한 비동기 작업 인터페이스를 사용합니다.

한 문장의 프롬프트로 짧은 비디오 하나만 만들려면 prompt만 전달하면 됩니다. 상품 외형, 브랜드 화면 또는 샷의 시작과 끝이 더 중요하다면 H3의 첫/마지막 프레임 및 멀티모달 레퍼런스 모드가 더 유용합니다. 현재 모델은 4~15초 출력, 네이티브 2K, 그리고 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 등의 화면비를 지원합니다. 구체적인 사용 가능 옵션은 MiniMax H3 모델 페이지와 API 파라미터 문서를 기준으로 하세요.

MiniMax H3로 해결하기 좋은 문제

화면, 동작, 사운드의 관계를 동시에 제어해야 하는 짧은 비디오 작업에 특히 적합합니다. 예를 들어 상품 페이지용으로 카메라 무빙이 있는 쇼케이스 영상을 만들거나, 브랜드 소재의 동일한 시각적 분위기를 이어가거나, 레퍼런스 비디오의 리듬, 레퍼런스 이미지의 주체, 레퍼런스 오디오를 함께 새 샷에 담아낼 수 있습니다.

이커머스, 광고, 제품 팀에게 H3의 가치는 단순히 '이미지를 움직이게 하는 것'이 아닙니다. 레퍼런스 소재가 있을 때는 바뀌면 안 되는 내용을 명확히 적는 것이 핵심입니다. 예를 들어 제품 형태, Logo 위치, 주체 정체성, 카메라 앵글, 조명 등입니다. 반대로 변해야 하는 내용은 따로 설명합니다. 예를 들어 동작, 배경, 카메라 푸시 또는 대사입니다. 그래야 이후 검수에서 어느 부분이 어긋났는지 알 수 있습니다.

하나의 모델, 세 가지 대표 워크플로

워크플로	적합한 시나리오	핵심 입력
텍스트 투 비디오	스크립트, 스토리보드 또는 한 줄 아이디어로 새 화면 생성	`prompt`
첫/마지막 프레임 제어	샷 시작과 종료의 제품 상태 또는 장면 변화 제어	`first_frame_image`, 선택 사항 `last_frame_image`
멀티모달 레퍼런스 비디오	상품, 인물, 샷 리듬 또는 오디오 소재를 동시에 참조	`image_urls`, `video_urls`, `audio_urls`

첫/마지막 프레임 제어와 멀티모달 레퍼런스는 서로 다른 모드이며 한 번의 요청에 섞을 수 없습니다. 마지막 프레임을 사용할 때는 반드시 첫 프레임도 함께 제공해야 합니다. 멀티모달 레퍼런스는 이미지 최대 5장, 비디오 최대 3개, 오디오 최대 3개를 전달할 수 있으며, 오디오는 단독 입력이 불가능하고 최소한 레퍼런스 이미지나 레퍼런스 비디오를 함께 제공해야 합니다. 레퍼런스 비디오와 오디오는 개별 구간이 2~15초이며, 합계가 15초를 넘지 않아야 합니다.

먼저 텍스트 투 비디오로 최소 작업을 실행해 보기

아래는 5초, 16:9 제품 샷 예시입니다. 작업 생성에 성공했다는 것은 서버가 요청을 접수했다는 의미일 뿐이며, 응답의 data.taskId로 이후 상태를 조회합니다.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "input": {
      "prompt": "一只哑光深蓝色咖啡杯放在浅灰石桌上。镜头从中景缓慢推进，晨光从左侧照入，杯身保持不动，背景虚化，无文字。",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9",
      "watermark": false
    }
  }'

로컬 디버깅에서는 GET /v1/tasks/{taskId}로 결과를 조회할 수 있습니다. 프로덕션 환경에서는 요청 최상위에 callback.url을 설정하고, 자체 서비스에서 taskId 기준으로 멱등 처리를 하는 것이 더 적합합니다. 작업이 종료 상태에 도달한 뒤 status를 판단하세요. success이면 output[].url을 다운로드하고, fail이면 오류 정보에 따라 입력을 수정하며 동일한 무효 요청을 무작정 재전송하지 마세요.

레퍼런스 소재를 의미 있게 사용하는 방법

첫/마지막 프레임은 '샷이 A에서 B로 이동하는' 작업에 적합합니다. 예를 들어 신제품 런칭 영상이 꺼진 스탠드 조명에서 시작해 따뜻한 빛이 책상을 비추는 상태로 끝나는 경우입니다. 이때 첫 프레임은 시작점을, 마지막 프레임은 도착점을 고정하고, 프롬프트는 중간에 일어나는 동작, 카메라 무빙, 조명 변화만 설명하면 됩니다.

멀티모달 레퍼런스는 지속적인 브랜드 또는 캐릭터 제어에 더 적합합니다. 상품 대표 이미지는 image_urls에, 샷 리듬 레퍼런스는 video_urls에, 음악이나 분위기 레퍼런스는 audio_urls에 넣을 수 있습니다. 프롬프트에는 각 소재의 역할을 반드시 명시해야 합니다. 예를 들어 "레퍼런스 이미지의 가방 외형과 금속 버클 위치를 유지하고, 레퍼런스 비디오의 횡방향 푸시인 리듬을 따르며, 조용한 제품 쇼케이스 영상을 생성"처럼 작성합니다.

모든 소재를 한꺼번에 넣지 마세요. 레퍼런스가 하나 늘어날 때마다 모델이 이해해야 할 제약이 늘어납니다. 먼저 주체 이미지 한 장으로 외형 보존을 검증한 뒤 카메라나 오디오 레퍼런스를 추가하면 문제를 더 쉽게 찾을 수 있습니다.

프롬프트에 담아야 할 정보

재사용 가능한 비디오 프롬프트는 보통 네 부분으로 구성됩니다. 주체, 동작, 카메라, 사운드 또는 환경입니다. 주체는 바뀌면 안 되는 시각 정보를 명확히 하고, 동작은 발생하는 이벤트를 설명하며, 카메라는 앵글과 움직임을 묘사하고, 사운드는 대사, 환경음, 음악 분위기의 유무를 설명합니다.

예를 들어 제품 광고를 만들 때 이렇게 작성할 수 있습니다. "레퍼런스 이미지의 흰색 이어폰 케이스, 오렌지색 외장, NOMA 마크는 그대로 유지합니다. 카메라는 책상 중경에서 천천히 푸시인하고, 이어폰 케이스가 열리며 두 이어폰은 원래 위치에 머뭅니다. 창가의 자연광, 낮은 환경음, 내레이션 없음, 추가 텍스트 없음." 이는 "멋진 이어폰 광고를 만들어 줘"라고만 쓰는 것보다 검수하기 훨씬 쉽습니다.

H3를 프로덕션 워크플로에 넣기 전에

먼저 세 가지 사례로 소규모 검증을 진행하는 것을 권장합니다. 순수 텍스트 투 비디오 하나, 첫/마지막 프레임 제어 하나, 멀티모달 레퍼런스 비디오 하나입니다. 각각 입력 소재, 출력 길이, 상태 전이, 실패 정보, 산출물 URL, 최종 청구 내역을 기록하세요. 각 모드가 여러분의 제품에서 안정적으로 동작함을 확인한 뒤 배치 생성으로 확장하세요.

가격은 출력 초수와 현재 등급에 따라 계산되며, 페이지에 단가를 고정해 명시하지 않습니다. 제출 전에 MiniMax H3 실시간 모델 페이지에서 현재 가격을 확인하세요. 라이브 이후에는 작업 기록과 계정 청구 내역을 기준으로 합니다. 비동기 작업, 콜백, 오류 문제 해결에 대해서는 MiniMax H3 연동 튜토리얼을 참고하세요.