> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # MiniMax H3 비디오 생성 API 연동 가이드 > Minimax API guide - Ace Data Cloud 본 문서에서는 MiniMax H3 비디오 생성 API의 연동 및 사용 방법을 소개합니다. 이 인터페이스는 텍스트-비디오 생성, 첫/마지막 프레임 제어 및 멀티모달 참조 비디오 생성을 지원하며, 통합된 V2 멀티모달 `content` 구조를 사용하여 작업을 생성합니다. ## 신청 절차 MiniMax H3 비디오 생성 API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 발급받아 보관해 두세요. ![](https://cdn.acedata.cloud/dvc3cg.jpg) 아직 로그인하거나 가입하지 않은 경우, 로그인 페이지로 자동 이동하여 가입 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다. **하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 공용 잔액을 충전할 수 있습니다. > 📘 전체 문서: [MiniMax H3 비디오 생성 API →](https://platform.acedata.cloud/documents/minimax-videos-integration) Token은 환경 변수로 저장하고, 소스 코드에 작성하거나 버전 저장소에 커밋하지 않는 것을 권장합니다: ```bash theme={null} 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](https://platform.acedata.cloud/documents/minimax-tasks-integration)를 통해 상태와 완성 영상을 가져옵니다. * **비동기 콜백**：선택 사항이며, `callback_url`을 통해 최종 작업 결과를 수신합니다. 생성 모드를 선택하기 위해 `action`을 전달할 필요가 없으며, 인터페이스가 `content` 내 소재의 유형과 `role`에 따라 용도를 자동으로 판단합니다. ## 적합한 시나리오 | 시나리오 | 입력 조합 | 일반적인 용도 | | - | - | - | | 텍스트-비디오 생성 | 텍스트 | 광고 크리에이티브, 스토리보드 사전 시각화, 숏폼 비디오, 분위기 샷 | | 첫 프레임 이미지-비디오 생성 | 텍스트 + 첫 프레임 이미지 | 상품 이미지, 포스터, 인물 사진 또는 일러스트를 자연스럽게 움직이게 함 | | 마지막 프레임 / 첫·마지막 프레임 비디오 | 텍스트 + 마지막 프레임, 또는 텍스트 + 첫 프레임 + 마지막 프레임 | 오프닝과 엔딩, 전환, 성장 변화 및 전후 비교 제어 | | 멀티모달 참조 비디오 생성 | 텍스트 + 참조 이미지 / 비디오 / 오디오 | 캐릭터와 제품의 일관성 유지, 동작, 카메라 워크, 음색 또는 편집 리듬 재현 | ## 호출 절차 기본적으로 `async`를 전달하지 않으면 `/minimax/videos`는 생성 완료까지 대기한 후 전체 `task`를 직접 반환합니다. 즉시 연결을 해제해야 하는 경우 `async: true` 또는 `callback_url`을 전달하세요: 1. 즉시 응답의 `task_id`와 `trace_id`를 저장합니다. 2. 콜백을 구성하지 않은 경우 약 10초마다 `/minimax/tasks`를 호출하여 한 번씩 조회합니다. 3. `task.status`가 `succeeded`로 변경되면 `task.content.url`에서 비디오를 가져옵니다. 4. 상태가 `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 참고 | | - | - | | 검은색 핸드백 제품 참고 | 브랜드 Logo 참고 |