> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax Hailuo H3 비디오 생성

> MiniMax Hailuo H3에서 텍스트, 시작/종료 프레임 및 멀티모달 참조로 2K 또는 768p 비디오 생성

> [!NOTE]
>
> **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 로 바꿔 주세요.

* `MiniMax-H3`, `MiniMax-H3-Max`, `MiniMax-H3-Max-Turbo` 세 모델을 지원합니다
* `MiniMax-H3`와 `MiniMax-H3-Max`는 텍스트 비디오, 시작/종료 프레임, 이미지·비디오·오디오 복합 참조를 지원합니다
* `MiniMax-H3-Max-Turbo`는 텍스트 비디오와 시작/종료 프레임만 지원하며 참조 미디어는 지원하지 않습니다
* 기존 H3는 `2K` / `768p`, `4-15`초를 유지합니다. Max / Max-Turbo는 `480P` / `768P`, `5-15`초를 지원합니다
* 비동기 API는 통합 `generation.task` 형식을 반환합니다

> [!WARNING]
>
> `MiniMax-H3-Max-Turbo`는 `reference_image`, `reference_video`, `reference_audio`를 지원하지 않습니다. 참조 미디어를 보내면 `MiniMax-H3-Max-Turbo does not support reference media` 오류가 반환됩니다. 참조 비디오를 사용하려면 `MiniMax-H3` 또는 `MiniMax-H3-Max`를 선택하세요.

> [!WARNING]
>
> 공개 접근 가능한 미디어 URL을 사용하세요. 프레임 모드와 멀티모달 참조 모드는 함께 사용할 수 없으며, 참조 오디오만 단독으로 입력할 수 없습니다.

## 인증

**Authorization** `string` *required*

`Authorization: Bearer YOUR_API_KEY`를 전송하세요.

## 요청 파라미터

**model** `string` *required* (default: MiniMax-H3)

`MiniMax-H3`, `MiniMax-H3-Max`, `MiniMax-H3-Max-Turbo` 중에서 선택합니다. 멀티모달 참조는 `MiniMax-H3`와 `MiniMax-H3-Max`만 지원합니다. Turbo는 텍스트 비디오와 시작/종료 프레임만 지원합니다.

**prompt** `string` *required*

비디오 설명이며 최대 `7000`자입니다.

**duration** `integer` (default: 5)

`MiniMax-H3`는 `4-15`초, Max / Max-Turbo는 `5-15`초 정수를 지원합니다.

**resolution** `string` (default: 2K)

`MiniMax-H3`는 `2K`와 `768p`, Max / Max-Turbo는 `480P`와 `768P`를 지원합니다.

**aspect\_ratio** `string` (default: 16:9)

`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`를 지원합니다.
텍스트 비디오에서는 `adaptive`를 사용할 수 없습니다. 프레임 모드는 입력 이미지에 자동 맞춤되며 참조 모드는 기본적으로 `adaptive`입니다.
참조 모드는 `MiniMax-H3`와 `MiniMax-H3-Max`만 지원합니다.

**image\_urls** `string[]`

호환용 이미지 URL입니다. 1장은 시작 프레임, 2장은 시작/종료 프레임, 3-9장은 참조 이미지로 처리됩니다. 신규 연동에는 `image_with_roles`를 권장합니다.
3-9장의 참조 이미지 입력은 `MiniMax-H3`와 `MiniMax-H3-Max`만 지원하며 Turbo에서는 사용할 수 없습니다.

**image\_with\_roles** `array`

`url`과 `role`을 가진 이미지 배열입니다. role은 `first_frame`(최대 1), `last_frame`(최대 1), `reference_image`(최대 9)입니다.
`reference_image`는 `MiniMax-H3`와 `MiniMax-H3-Max`만 지원합니다. Turbo에서는 `first_frame`과 `last_frame`만 사용할 수 있습니다.
JPG, JPEG, PNG, WebP, HEIC, HEIF, 최대 `30 MB`, 각 변 `256-5760 px`, 비율 `0.4-2.5`를 지원합니다.

**video\_with\_roles** `array`

`MiniMax-H3`와 `MiniMax-H3-Max`만 지원하며 Turbo에서는 사용할 수 없습니다.
최대 `3`개의 참조 비디오입니다. 각 항목은 `url`과 `role: reference_video`를 포함합니다. MP4/MOV, 최대 `50 MB`, 각각 `2-15`초, 합계 `15`초까지 지원합니다.
\[!NOTE] ToAPIs가 실제 비디오 길이를 읽어 과금합니다. 클라이언트가 계산한 길이 필드는 보내지 마세요.

**audio\_with\_roles** `array`

`MiniMax-H3`와 `MiniMax-H3-Max`만 지원하며 Turbo에서는 사용할 수 없습니다.
최대 `3`개의 참조 오디오입니다. 각 항목은 `url`과 `role: reference_audio`를 포함합니다. WAV/MP3, 최대 `15 MB`, 각각 `2-15`초, 합계 `15`초까지 지원합니다.
\[!WARNING] 최소 하나의 참조 이미지 또는 참조 비디오가 함께 필요합니다.

**watermark** `boolean` (default: false)

AIGC 워터마크 추가 여부입니다.

**client\_business\_id** `string`

주문 ID와 같은 클라이언트 비즈니스 ID입니다.

**callback\_url** `string`

ToAPIs 작업 완료 콜백입니다. [Webhook](https://docs.toapis.com/docs/ko/api-reference/webhooks/task-webhooks.md)을 참고하세요.

## 모드 및 제한

| 모드 | 지원 모델 | 입력 | 비율 |
| - | - | - | - |
| 텍스트 비디오 | 세 모델 모두 | `prompt` | 구체적 비율, 기본 `16:9` |
| 시작/종료 프레임 | 세 모델 모두 | `prompt` + 프레임 이미지 | 자동 `adaptive` |
| 멀티모달 참조 | `MiniMax-H3`와 `MiniMax-H3-Max`만 | `prompt` + 참조 미디어 | 기본 `adaptive` |

아래 참조 미디어 제한은 `MiniMax-H3`와 `MiniMax-H3-Max`에만 적용됩니다.

참조 이미지는 9개, 비디오는 3개, 오디오는 3개, 전체는 12개까지입니다. 프레임 role과 참조 role은 함께 사용할 수 없습니다.

## 예시

참조 미디어 예시는 `MiniMax-H3`를 사용합니다. `model`만 `MiniMax-H3-Max-Turbo`로 바꾸어 사용할 수 없습니다. `MiniMax-H3-Max`를 사용하려면 `resolution`을 `480P` 또는 `768P`로, `duration`을 `5-15`초로 설정하세요.

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "비디오1의 동작과 카메라 리듬을 따르고 오디오1의 목소리로 대사를 말한다",
  "duration": 5,
  "resolution": "768p",
  "aspect_ratio": "adaptive",
  "video_with_roles": [
    {"url": "https://example.com/motion.mp4", "role": "reference_video"}
  ],
  "audio_with_roles": [
    {"url": "https://example.com/voice.mp3", "role": "reference_audio"}
  ]
}
```

## 응답

**id** `string`

ToAPIs 작업 ID입니다.

**object** `string`

항상 `generation.task`입니다.

**model** `string`

항상 `MiniMax-H3`입니다.

**status** `string`

`queued`, `in_progress`, `completed`, `failed`.

**progress** `integer`

`0-100` 진행률입니다.

**created\_at** `integer`

Unix 생성 시각(초)입니다.

> [!NOTE]
>
> [비디오 작업 상태 조회](https://docs.toapis.com/docs/ko/api-reference/tasks/video-status.md)를 폴링하세요. 완료 URL은 `result.data[0].url`에 있습니다.

```bash cURL (텍스트 비디오) theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"model":"MiniMax-H3","prompt":"달 표면의 우주비행사를 카메라가 천천히 비춘다","duration":5,"resolution":"2K","aspect_ratio":"16:9"}'
```

```bash cURL (이미지·비디오·오디오 복합 참조) theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "prompt": "이미지1의 인물을 유지하고 비디오1의 동작과 카메라를 참고하며 오디오1의 목소리로 대사한다",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "adaptive",
    "image_with_roles": [{"url": "https://example.com/person.png", "role": "reference_image"}],
    "video_with_roles": [{"url": "https://example.com/motion.mp4", "role": "reference_video"}],
    "audio_with_roles": [{"url": "https://example.com/voice.mp3", "role": "reference_audio"}]
  }'
```

```json 200 theme={null}
{"id":"vid_01KZ3H3EXAMPLE00000000000","object":"generation.task","model":"MiniMax-H3","status":"queued","progress":0,"created_at":1785729000}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.