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

# MiniMax-H3-Max 동영상 생성

>  - MiniMax 동영상 생성 V2 고속 버전, 비동기 작업 제출
- 텍스트→동영상 및 첫 프레임 / 마지막 프레임 / 첫·마지막 프레임 이미지→동영상 지원
- 768P / 480P, 5~15초, 오디오 포함 동영상 지원
- 2K, 중간 프레임, 멀티모달 참조 생성은 지원하지 않음 

<Info>
  **모델 선택:** 속도가 중요하고 텍스트→동영상 또는 첫/마지막 프레임 제어만 필요하면 `MiniMax-H3-Max`를 사용하세요. 2K, 중간 프레임, 참조 이미지·동영상·오디오가 필요하면 [MiniMax-H3](/ko/api-reference/videos/minimax-h3/generation)를 사용하세요.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "MiniMax-H3-Max",
      "prompt": "비 내리는 네온 거리에서 트렌치코트를 입은 탐정이 뒤돌아본다. 카메라가 천천히 다가가고 노면의 반사가 흔들린다.",
      "duration": 5,
      "resolution": "768P",
      "aspect_ratio": "16:9"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/v1/videos/generations",
      headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
      json={
          "model": "MiniMax-H3-Max",
          "prompt": "비 내리는 네온 거리에서 탐정이 뒤돌아보고 카메라가 천천히 다가간다.",
          "duration": 5,
          "resolution": "768P",
          "aspect_ratio": "16:9",
      },
  )
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "요청 매개변수가 올바르지 않습니다",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "인증에 실패했습니다. API 키를 확인하세요.",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "계정 잔액이 부족합니다",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## 인증

<ParamField header="Authorization" type="string" required>
  모든 엔드포인트에 Bearer Token 인증이 필요합니다. [API 키 페이지](https://apimart.ai/keys)에서 키를 받으세요.

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 모델 선택

| 기능          | `MiniMax-H3`           | `MiniMax-H3-Max`           |
| ----------- | ---------------------- | -------------------------- |
| 해상도         | `2K` / `768P`, 기본 `2K` | `768P` / `480P`, 기본 `768P` |
| 길이          | 4\~15초                 | 5\~15초                     |
| 텍스트→동영상     | 지원                     | 지원                         |
| 첫 / 마지막 프레임 | 지원                     | 지원                         |
| 중간 프레임      | 지원                     | 미지원                        |
| 멀티모달 참조     | 이미지, 동영상, 오디오          | 미지원                        |
| 입력 이미지 요금   | 처음 5장 무료               | 무료                         |

<Warning>
  `MiniMax-H3-Max`는 2K를 지원하지 않으며 결과를 [Regeneration](/ko/api-reference/videos/minimax-h3/regeneration)의 원본 작업으로 사용할 수 없습니다.
</Warning>

## 생성 모드

요청 필드로 모드가 자동 결정됩니다. `mode` 필드를 보내지 마세요.

| 모드           | 조건                                                                    | 동작                       |
| ------------ | --------------------------------------------------------------------- | ------------------------ |
| 텍스트→동영상(T2V) | `prompt`와 공통 필드만 전달                                                   | 텍스트에서 생성                 |
| 이미지→동영상(I2V) | `first_frame_image` / `last_frame_image` 또는 `image_with_roles`의 해당 역할 | 첫 프레임, 마지막 프레임 또는 둘 다 제어 |

<Warning>
  이 모델은 `image_urls`, `video_urls`, `audio_urls` 및 `image_with_roles[].role = "reference_image"`를 지원하지 않습니다. 참조 미디어를 전달하면 작업 생성과 과금 전에 HTTP 400을 반환합니다.
</Warning>

## 요청 매개변수

<ParamField body="model" type="string" required>
  고정값: `MiniMax-H3-Max`. 대소문자를 구분하지 않으며 `minimax-h3-max`도 허용됩니다.
</ParamField>

<ParamField body="prompt" type="string" required>
  비어 있지 않은 동영상 설명입니다. 모든 모드에서 필수이며 최대 `7000`자입니다.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  동영상 길이(초). `5`\~`15`의 정수이며 기본값은 `5`입니다. 4초는 지원하지 않습니다.
</ParamField>

<ParamField body="resolution" type="string" default="768P">
  출력 해상도: `768P`(기본) 또는 `480P`.

  <Warning>
    `2K`, `1440P`, `2048P`는 지원하지 않습니다. 잘못된 값은 HTTP 400을 반환하며 자동으로 낮은 해상도로 변경되지 않습니다.
  </Warning>
</ParamField>

<ParamField body="aspect_ratio" type="string">
  출력 화면비. `size`와 `ratio` 별칭도 사용할 수 있습니다.

  T2V 값: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.

  * T2V에서 생략하거나 `adaptive` 사용: `16:9`로 대체
  * I2V: 입력 이미지로 결정되며 이 필드는 무시
</ParamField>

<ParamField body="first_frame_image" type="string">
  동영상 첫 프레임으로 사용할 공개 이미지 URL.
</ParamField>

<ParamField body="last_frame_image" type="string">
  마지막 프레임으로 사용할 공개 이미지 URL. 단독 또는 `first_frame_image`와 함께 사용할 수 있습니다.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  `first_frame_image` / `last_frame_image` 대신 사용할 수 있는 역할 기반 이미지 배열.

  <Expandable title="image_with_roles 항목">
    <ResponseField name="url" type="string" required>
      공개 이미지 URL
    </ResponseField>

    <ResponseField name="role" type="string" required>
      지원 역할:

      * `first_frame`, 별칭 `first` / `start`
      * `last_frame`, 별칭 `last` / `end_frame` / `tail`
    </ResponseField>
  </Expandable>

  역할당 최대 1장만 허용되며 `role`은 비워 둘 수 없습니다.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  AIGC 워터마크 추가 여부. 별칭: `aigc_watermark`.
</ParamField>

<ParamField body="webhook" type="string">
  작업이 성공 또는 실패 상태로 종료되면 알림을 받습니다.

  <Note>
    MiniMax의 `callback_url` 대신 `webhook`을 사용하세요. `callback_url`은 게이트웨이 내부용입니다.
  </Note>
</ParamField>

## 지원하지 않는 매개변수

다음 값은 작업 생성 및 과금 전에 HTTP 400을 반환합니다.

| 매개변수 / 값                                      | 이유                                  |
| --------------------------------------------- | ----------------------------------- |
| `image_urls`                                  | 참조 이미지로 처리되지만 이 모델은 참조 이미지를 지원하지 않음 |
| `image_with_roles[].role = "reference_image"` | 첫·마지막 프레임만 지원                       |
| `video_urls` / `video_url`                    | 참조 동영상 미지원                          |
| `audio_urls` / `audio_url`                    | 참조 오디오 미지원                          |
| `resolution: "2K"`                            | `768P`와 `480P`만 지원                  |
| `duration: 4` 또는 `15` 초과                      | 5\~15초만 지원                          |

<Tip>
  참조 미디어, 2K, 중간 프레임 또는 4초 동영상에는 [MiniMax-H3](/ko/api-reference/videos/minimax-h3/generation)를 사용하세요.
</Tip>

## 이미지 제한

전체 요청 본문은 64 MB 이하여야 합니다. 공개 URL을 사용하고 Base64는 사용하지 마세요.

| 항목     | 제한                                    |
| ------ | ------------------------------------- |
| 형식     | JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| 파일당    | ≤ 30 MB                               |
| 너비와 높이 | 256\~5760 px                          |
| 화면비    | 0.4\~2.5                              |
| 수량     | 첫 프레임 1장, 마지막 프레임 1장, 총 2장            |

## 예시

### 첫 프레임 이미지→동영상

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "김이 피어오르며 카메라가 천천히 다가간다.",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "480P"
}
```

### 첫·마지막 프레임 이미지→동영상

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "아침에서 일몰로 천천히 전환된다.",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8,
  "resolution": "768P"
}
```

## 작업 조회

제출 시 `task_id`가 반환됩니다. [작업 상태](/ko/api-reference/tasks/status)를 5\~10초마다 조회하고 클라이언트 제한 시간은 15분으로 설정하세요.

| `status`     | 의미                                  |
| ------------ | ----------------------------------- |
| `pending`    | 제출됨 또는 대기 중                         |
| `processing` | 생성 중                                |
| `completed`  | 동영상 URL은 `result.videos[0].url`에 있음 |
| `failed`     | `error.message` 확인, 자동 환불           |

<Note>
  생성된 동영상 URL은 보통 약 24시간 후 만료됩니다. 즉시 다운로드해 보관하세요.
</Note>

## 요금

총비용 = 초당 단가 × 동영상 길이. 첫·마지막 프레임 이미지는 무료입니다.

| 항목       | 단가               |
| -------- | ---------------- |
| 768P 동영상 | **\$0.075 / 초**  |
| 480P 동영상 | **\$0.0495 / 초** |
| 입력 이미지   | **무료**           |

제출 시 예상 금액을 선점합니다. 실패한 작업은 전액 자동 환불되며 최종 금액은 작업 응답의 `cost`를 기준으로 합니다.

## 오류

| 상황                        | 결과               |
| ------------------------- | ---------------- |
| 비어 있거나 7000자를 넘는 `prompt` | 400, 작업 없음       |
| `duration`이 5\~15 범위 밖    | 400, 작업 없음       |
| 지원하지 않는 `resolution`      | 400, 작업 없음       |
| 참조 미디어                    | 400, 작업 없음       |
| 잘못되거나 중복된 이미지 역할          | 400, 작업 없음       |
| 잔액 부족                     | 402              |
| 콘텐츠 안전 거부                 | 422              |
| 요청 제한                     | 429, 지수 백오프로 재시도 |

생성 중 실패하면 `status = failed`와 `error.message`가 반환되고 자동 환불됩니다.

## Response

<ResponseField name="code" type="integer">
  응답 상태 코드, 성공 시 200
</ResponseField>

<ResponseField name="data" type="array">
  초기 작업 상태와 작업 ID를 포함한 제출 결과

  <Expandable title="배열 항목">
    <ResponseField name="status" type="string">
      초기값은 `submitted`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      진행 상태와 결과 조회에 사용하는 고유 ID
    </ResponseField>
  </Expandable>
</ResponseField>