> ## 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 비디오 생성

* 모델 이름은 `MiniMax-H3`로 고정됩니다
* 텍스트 비디오, 시작/종료 프레임, 이미지·비디오·오디오 복합 참조를 지원합니다
* 출력은 `2K`, 길이는 `4-15`초입니다
* 비동기 API는 통합 `generation.task` 형식을 반환합니다

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

## 인증

<ParamField header="Authorization" type="string" required>`Authorization: Bearer YOUR_API_KEY`를 전송하세요.</ParamField>

## 요청 파라미터

<ParamField body="model" type="string" default="MiniMax-H3" required>`MiniMax-H3`로 고정됩니다.</ParamField>
<ParamField body="prompt" type="string" required>비디오 설명이며 최대 `7000`자입니다.</ParamField>
<ParamField body="duration" type="integer" default={5}>`4-15`초 정수입니다.</ParamField>
<ParamField body="resolution" type="string" default="2K">현재 `2K`만 지원합니다.</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`를 지원합니다.
  텍스트 비디오에서는 `adaptive`를 사용할 수 없습니다. 프레임 모드는 입력 이미지에 자동 맞춤되며 참조 모드는 기본적으로 `adaptive`입니다.
</ParamField>

<ParamField body="image_urls" type="string[]">
  호환용 이미지 URL입니다. 1장은 시작 프레임, 2장은 시작/종료 프레임, 3-9장은 참조 이미지로 처리됩니다. 신규 연동에는 `image_with_roles`를 권장합니다.
</ParamField>

<ParamField body="image_with_roles" type="array">
  `url`과 `role`을 가진 이미지 배열입니다. role은 `first_frame`(최대 1), `last_frame`(최대 1), `reference_image`(최대 9)입니다.
  JPG, JPEG, PNG, WebP, HEIC, HEIF, 최대 `30 MB`, 각 변 `256-5760 px`, 비율 `0.4-2.5`를 지원합니다.
</ParamField>

<ParamField body="video_with_roles" type="array">
  최대 `3`개의 참조 비디오입니다. 각 항목은 `url`과 `role: reference_video`를 포함합니다. MP4/MOV, 최대 `50 MB`, 각각 `2-15`초, 합계 `15`초까지 지원합니다.
  <Note>ToAPIs가 실제 비디오 길이를 읽어 과금합니다. 클라이언트가 계산한 길이 필드는 보내지 마세요.</Note>
</ParamField>

<ParamField body="audio_with_roles" type="array">
  최대 `3`개의 참조 오디오입니다. 각 항목은 `url`과 `role: reference_audio`를 포함합니다. WAV/MP3, 최대 `15 MB`, 각각 `2-15`초, 합계 `15`초까지 지원합니다.
  <Warning>최소 하나의 참조 이미지 또는 참조 비디오가 함께 필요합니다.</Warning>
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>AIGC 워터마크 추가 여부입니다.</ParamField>
<ParamField body="client_business_id" type="string">주문 ID와 같은 클라이언트 비즈니스 ID입니다.</ParamField>
<ParamField body="callback_url" type="string">ToAPIs 작업 완료 콜백입니다. [Webhook](/docs/ko/api-reference/webhooks/task-webhooks)을 참고하세요.</ParamField>

## 모드 및 제한

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

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

## 예시

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "비디오1의 동작과 카메라 리듬을 따르고 오디오1의 목소리로 대사를 말한다",
  "duration": 5,
  "resolution": "2K",
  "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"}
  ]
}
```

## 응답

<ResponseField name="id" type="string">ToAPIs 작업 ID입니다.</ResponseField>
<ResponseField name="object" type="string">항상 `generation.task`입니다.</ResponseField>
<ResponseField name="model" type="string">항상 `MiniMax-H3`입니다.</ResponseField>
<ResponseField name="status" type="string">`queued`, `in_progress`, `completed`, `failed`.</ResponseField>
<ResponseField name="progress" type="integer">`0-100` 진행률입니다.</ResponseField>
<ResponseField name="created_at" type="integer">Unix 생성 시각(초)입니다.</ResponseField>

<Note>[비디오 작업 상태 조회](../../tasks/video-status)를 폴링하세요. 완료 URL은 `result.data[0].url`에 있습니다.</Note>

<RequestExample>
  ```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"}]
    }'
  ```
</RequestExample>

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