> ## 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 動画生成

>  - 非同期処理モード、タスク ID を返して後続の照会に使用
- テキストから動画、画像から動画（先頭フレーム / 末尾フレーム / 先頭+末尾フレーム）、マルチモーダル参照から動画（参照画像 + 参照動画 + 参照音声）をサポート
- 2K ネイティブ出力、長さ 4 〜 15 秒、音声トラック付き
- MiniMax-Hailuo-02 / MiniMax-Hailuo-2.3 と同一の提出・照会 API を共有 

<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",
      "prompt": "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/videos/generations"

  payload = {
      "model": "MiniMax-H3",
      "prompt": "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/videos/generations";

  const payload = {
    model: "MiniMax-H3",
    prompt: "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
    duration: 5,
    resolution: "2K",
    aspect_ratio: "16:9"
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://api.apimart.ai/v1/videos/generations"

      payload := map[string]interface{}{
          "model":        "MiniMax-H3",
          "prompt":       "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
          "duration":     5,
          "resolution":   "2K",
          "aspect_ratio": "16:9",
      }

      jsonData, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  public class Main {
      public static void main(String[] args) throws Exception {
          String url = "https://api.apimart.ai/v1/videos/generations";

          String payload = """
          {
            "model": "MiniMax-H3",
            "prompt": "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
            "duration": 5,
            "resolution": "2K",
            "aspect_ratio": "16:9"
          }
          """;

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer <token>")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api.apimart.ai/v1/videos/generations";

  $payload = [
      "model" => "MiniMax-H3",
      "prompt" => "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
      "duration" => 5,
      "resolution" => "2K",
      "aspect_ratio" => "16:9"
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer <token>",
      "Content-Type: application/json"
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  url = URI("https://api.apimart.ai/v1/videos/generations")

  payload = {
    model: "MiniMax-H3",
    prompt: "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
    duration: 5,
    resolution: "2K",
    aspect_ratio: "16:9"
  }

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request["Authorization"] = "Bearer <token>"
  request["Content-Type"] = "application/json"
  request.body = payload.to_json

  response = http.request(request)
  puts response.body
  ```

  ```swift Swift theme={null}
  import Foundation

  let url = URL(string: "https://api.apimart.ai/v1/videos/generations")!

  let payload: [String: Any] = [
      "model": "MiniMax-H3",
      "prompt": "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9"
  ]

  var request = URLRequest(url: url)
  request.httpMethod = "POST"
  request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
  request.setValue("application/json", forHTTPHeaderField: "Content-Type")
  request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

  let task = URLSession.shared.dataTask(with: request) { data, response, error in
      if let error = error {
          print("Error: \(error)")
          return
      }

      if let data = data, let responseString = String(data: data, encoding: .utf8) {
          print(responseString)
      }
  }

  task.resume()
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          var url = "https://api.apimart.ai/v1/videos/generations";

          var payload = @"{
              ""model"": ""MiniMax-H3"",
              ""prompt"": ""A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work"",
              ""duration"": 5,
              ""resolution"": ""2K"",
              ""aspect_ratio"": ""16:9""
          }";

          using var client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", "Bearer <token>");

          var content = new StringContent(payload, Encoding.UTF8, "application/json");
          var response = await client.PostAsync(url, content);
          var result = await response.Content.ReadAsStringAsync();

          Console.WriteLine(result);
      }
  }
  ```
</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"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": 422,
      "message": "コンテンツ安全審査に不合格です",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "リクエストが多すぎます。しばらくしてから再試行してください",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": 500,
      "message": "サーバー内部エラーです。しばらくしてから再試行してください",
      "type": "server_error"
    }
  }
  ```
</ResponseExample>

## 認証

<ParamField header="Authorization" type="string" required>
  すべてのAPIエンドポイントはBearer Token認証が必要です

  APIキーの取得：

  [APIキー管理ページ](https://apimart.ai/keys)にアクセスしてAPIキーを取得してください

  リクエストヘッダーに追加：

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

## 生成モード

MiniMax-H3 はリクエストフィールドから対応モードへ自動ルーティングします。**`mode` フィールドは不要です**：

| モード                | トリガー条件                                                                                              | 能力                        |
| ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------- |
| **テキストから動画（T2V）**  | `prompt` と共通フィールドのみ                                                                                 | 純テキスト駆動の生成                |
| **画像から動画（I2V）**    | `first_frame_image` / `last_frame_image`（または `image_with_roles` 内の `first_frame` / `last_frame`）を指定 | 先頭フレーム、末尾フレーム、先頭+末尾フレーム制御 |
| **マルチモーダル参照（R2V）** | `image_urls` / `video_urls` / `audio_urls`、または `image_with_roles` 内の `reference_image` を指定          | 参照画像 + 参照動画 + 参照音声        |

<Warning>
  **厳密な相互排他**：画像から動画フィールド（`first_frame_image` / `last_frame_image`、および `image_with_roles` 内の `first_frame` / `last_frame`）とマルチモーダル参照フィールド（`image_urls`、`video_urls`、`audio_urls`、および `image_with_roles` 内の `reference_image`）は同時に指定できません。混在すると **400** が返されます。
</Warning>

<Warning>
  **音声のみは不可。** `audio_urls` を渡す場合は、参照画像または参照動画を少なくとも 1 つ併用する必要があります。
</Warning>

## リクエストパラメータ

### 共通フィールド

<ParamField body="model" type="string" required>
  固定値：`MiniMax-H3`

  <Warning>
    **`model` フィールドは必須で、明示的に渡す必要があります。** すでに海螺（Hailuo）シリーズを統合済みのクライアントは、`model` を `MiniMax-H3` に変更するだけで本モデルを利用できます。
  </Warning>
</ParamField>

<ParamField body="prompt" type="string" required>
  動画コンテンツの説明。**あらゆるシナリオで必須かつ空にできません**。1 リクエストあたり最大 **7000** 文字。

  シーン、主体、動作、スタイルなどを詳しく記述すると、より良い生成結果が得られます。

  例：`"A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work"`
</ParamField>

<ParamField body="duration" type="integer" default="5">
  出力の長さ（秒）

  * 範囲：`4` 〜 `15` の整数
  * デフォルト：`5`
</ParamField>

<ParamField body="resolution" type="string" default="2K">
  動画の解像度

  * 対応値：`2K` のみ（デフォルト）
</ParamField>

<ParamField body="aspect_ratio" type="string">
  アスペクト比。`size` または `ratio` でも同じ効果で渡せます。

  利用可能な比率：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`

  シナリオ別の挙動は下記「アスペクト比ルール」を参照してください。
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  AIGC 透かしを付与するかどうか

  デフォルト：`false`

  互換エイリアス：`aigc_watermark`
</ParamField>

<ParamField body="webhook" type="string">
  タスクが終端状態（成功 / 失敗）に達したとき、本サービスがこの URL へプッシュ通知します

  <Note>
    `webhook` を使用してください。公式の `callback_url` は渡さないでください。`callback_url` は本サービス内部用であり、ユーザーからの指定は受け付けません。
  </Note>
</ParamField>

### 画像から動画フィールド

**先頭 / 末尾フレーム**の画像から動画を行う場合は、役割を明示的に指定してください。`image_urls` の枚数から推測しないでください。

<ParamField body="first_frame_image" type="string">
  先頭フレーム画像の URL

  指定すると、その画像が動画の**開始フレーム**として使用されます。
</ParamField>

<ParamField body="last_frame_image" type="string">
  末尾フレーム画像の URL

  指定すると、その画像が動画の**終了フレーム**として使用されます。`first_frame_image` と組み合わせて先頭+末尾フレーム制御が可能です。
</ParamField>

### マルチモーダル参照フィールド

<ParamField body="image_urls" type="string[]">
  参照画像 URL の配列

  <Warning>
    **`image_urls` 内の画像は枚数に関係なく、すべて参照画像（`reference_image`）として扱われます**。枚数によって先頭 / 先頭+末尾フレームに自動マッピングされることはありません。
  </Warning>

  * 数量：≤ **9**
</ParamField>

<ParamField body="video_urls" type="string[]">
  参照動画 URL の配列

  * 数量：≤ **3**
  * 形式と制限：下記「入力メディア制限」を参照
</ParamField>

<ParamField body="audio_urls" type="string[]">
  参照音声 URL の配列

  * 数量：≤ **3**
  * 単独では使用不可。参照画像または参照動画と併用する必要があります
</ParamField>

### 共通画像配列（任意の書き方）

<ParamField body="image_with_roles" type="object[]">
  役割付き画像配列。`first_frame_image` / `last_frame_image` / `image_urls` の代替として使用できます。各要素の構造：

  <Expandable title="image_with_roles 要素">
    <ResponseField name="url" type="string" required>
      画像 URL
    </ResponseField>

    <ResponseField name="role" type="string" required>
      画像の役割。許可される値：

      * `first_frame`（`first` も可）— 先頭フレーム（I2V）
      * `last_frame`（`last` も可）— 末尾フレーム（I2V）
      * `reference_image`（`reference` も可）— 参照画像（R2V）
    </ResponseField>
  </Expandable>

  例（先頭 + 末尾フレーム）：

  ```json theme={null}
  {
    "image_with_roles": [
      {"url": "https://example.com/start.png", "role": "first_frame"},
      {"url": "https://example.com/end.png", "role": "last_frame"}
    ]
  }
  ```

  例（参照画像）：

  ```json theme={null}
  {
    "image_with_roles": [
      {"url": "https://example.com/char.png", "role": "reference_image"}
    ]
  }
  ```
</ParamField>

## アスペクト比ルール

| シナリオ                      | `aspect_ratio` の挙動                                  |
| ------------------------- | --------------------------------------------------- |
| **テキストから動画**（prompt のみ）   | 具体的な比率が必要。省略または `adaptive` の場合は **`16:9` にフォールバック** |
| **画像から動画**（先頭 / 末尾フレームあり） | 入力画像により決定。渡した値は無視される（常に `adaptive`）                 |
| **マルチモーダル参照**             | 任意。デフォルトは `adaptive`。具体的な比率を明示指定することも可              |

利用可能な具体的比率：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。

## 入力メディア制限

リクエストボディの合計サイズ ≤ **64 MB**。大きなファイルは公開 URL を使用し、**Base64 は使用しないでください**。

### 画像

| 項目           | 制限                                    |
| ------------ | ------------------------------------- |
| 形式           | JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| 単一ファイル       | ≤ 30 MB                               |
| 幅 / 高さ       | 256 〜 5760 px                         |
| アスペクト比（幅/高さ） | 0.4 〜 2.5                             |
| 数量           | 先頭フレーム ≤ 1、末尾フレーム ≤ 1、参照画像 ≤ 9        |

### 動画（マルチモーダル参照のみ）

| 項目             | 制限                                      |
| -------------- | --------------------------------------- |
| 形式             | MP4（`.mp4`）、MOV（`.mov`）                 |
| コーデック          | 動画 H.264/AVC、H.265/HEVC；音声 AAC、MP3      |
| 単一ファイル         | ≤ 50 MB                                 |
| 数量             | ≤ 3                                     |
| 長さ             | 1 クリップあたり 2 〜 15 s；**合計長さ ≤ 15 s**      |
| サイズ / 比率 / FPS | 256 〜 5760 px / 0.4 〜 2.5 / 23.976 〜 60 |

### 音声（マルチモーダル参照のみ）

| 項目     | 制限                             |
| ------ | ------------------------------ |
| 形式     | WAV、MP3                        |
| 単一ファイル | ≤ 15 MB                        |
| 数量     | ≤ 3                            |
| 長さ     | 1 クリップあたり 2 〜 15 s；合計長さ ≤ 15 s |

## パラメータ制約

以下の制約に違反するとリクエストは拒否され **400** が返されます（センシティブコンテンツは **422** の場合あり）。**課金は発生しません**：

| パラメータ          | 制約                                                          |
| -------------- | ----------------------------------------------------------- |
| `prompt`       | あらゆるシナリオで必須かつ非空、≤ 7000 文字                                   |
| `duration`     | `4` 〜 `15` の整数のみ                                            |
| `resolution`   | `2K` のみ                                                     |
| `aspect_ratio` | 「アスペクト比ルール」を参照；T2V で省略時は `16:9` にフォールバック                    |
| 先頭/末尾フレームと参照素材 | **相互排他**、混在不可                                               |
| `audio_urls`   | 単独使用不可。参照画像または参照動画と併用必須                                     |
| 参照画像           | ≤ 9                                                         |
| 参照動画           | ≤ 3                                                         |
| 参照音声           | ≤ 3                                                         |
| 参照動画のプローブ失敗    | `input_video_probe_failed` を返す（URL に到達不可、またはファイル破損）、**未課金** |

## レスポンス

<ResponseField name="code" type="integer">
  レスポンスステータスコード。成功時は 200
</ResponseField>

<ResponseField name="data" type="array">
  レスポンスデータ配列

  <Expandable title="配列要素">
    <ResponseField name="status" type="string">
      タスク状態。初回提出時は `submitted`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      タスクの一意 ID。状態と結果の照会に使用
    </ResponseField>
  </Expandable>
</ResponseField>

## リクエスト例

### ケース 1：テキストから動画

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
  "duration": 6,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}
```

### ケース 2：画像から動画 — 先頭フレーム

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "Pull focus to the people in the background and add more steam to the ramen bowl.",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "2K"
}
```

### ケース 3：画像から動画 — 先頭 + 末尾フレーム

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "Camera slowly transitions from morning light to sunset",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8
}
```

### ケース 4：マルチモーダル参照から動画

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "Character speaks: Follow the wind, live free. Leave worries behind, enjoy the moment. Voice references audio 1",
  "image_with_roles": [
    {"url": "https://cdn.example.com/char.png", "role": "reference_image"}
  ],
  "video_urls": ["https://cdn.example.com/ref_motion.mp4"],
  "audio_urls": ["https://cdn.example.com/ref_voice.mp3"],
  "duration": 5,
  "resolution": "2K"
}
```

### ケース 5：image\_with\_roles で先頭 + 末尾フレームを指定

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "Camera slowly transitions from morning light to sunset",
  "image_with_roles": [
    {"url": "https://cdn.example.com/morning.png", "role": "first_frame"},
    {"url": "https://cdn.example.com/sunset.png", "role": "last_frame"}
  ],
  "duration": 8
}
```

<Note>
  **タスク結果の照会**

  動画生成は非同期タスクで、提出後に `task_id` が返されます。[タスク状態取得](/ja/api-reference/tasks/status) エンドポイントを使用して生成の進捗と結果を照会してください。

  推奨ポーリング間隔：**5 〜 10 秒**ごと。クライアントタイムアウト：**15 分**。成功時、`result.videos[0].url` が mp4 URL です。動画 URL の有効期限は約 **24 時間** — 速やかに保存してください。失敗したタスクは自動的に返金されます。
</Note>