> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/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 共用统一提交与查询接口 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://gccai.heqingsong.uk/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"
    }'
  ```

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

  url = "https://gccai.heqingsong.uk/v1/videos/generations"

  payload = {
      "model": "MiniMax-H3",
      "prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
      "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://gccai.heqingsong.uk/v1/videos/generations";

  const payload = {
    model: "MiniMax-H3",
    prompt: "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    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://gccai.heqingsong.uk/v1/videos/generations"

      payload := map[string]interface{}{
          "model":        "MiniMax-H3",
          "prompt":       "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
          "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://gccai.heqingsong.uk/v1/videos/generations";

          String payload = """
          {
            "model": "MiniMax-H3",
            "prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
            "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://gccai.heqingsong.uk/v1/videos/generations";

  $payload = [
      "model" => "MiniMax-H3",
      "prompt" => "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
      "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://gccai.heqingsong.uk/v1/videos/generations")

  payload = {
    model: "MiniMax-H3",
    prompt: "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    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://gccai.heqingsong.uk/v1/videos/generations")!

  let payload: [String: Any] = [
      "model": "MiniMax-H3",
      "prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
      "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://gccai.heqingsong.uk/v1/videos/generations";

          var payload = @"{
              ""model"": ""MiniMax-H3"",
              ""prompt"": ""一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜"",
              ""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>
  所有接口均需要使用 Bearer Token 进行认证

  获取 API Key：

  访问 [API Key 管理页面](https://gccai.heqingsong.uk/keys) 获取您的 API Key

  使用时在请求头中添加：

  ```
  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` 时，必须至少再配一个参考图或参考视频。
</Warning>

## 请求参数

### 通用字段

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

  <Warning>
    **必须显式传递 `model` 字段。** 已接入海螺系列的客户端将 `model` 改为 `MiniMax-H3` 即可使用本模型。
  </Warning>
</ParamField>

<ParamField body="prompt" type="string" required>
  视频内容描述，**任何场景都必填且不能为空**，单条 ≤ **7000** 字符

  建议详细描述场景、主体、动作、风格等，以获得更好的生成效果。

  示例：`"一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜"`
</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">
  任务到达终态（成功 / 失败）时，本服务主动推送到该地址

  <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`）— 首帧（图生视频）
      * `last_frame`（也接受 `last`）— 尾帧（图生视频）
      * `reference_image`（也接受 `reference`）— 参考图（多模态参考）
    </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                                        |
| 时长            | 单段 2 \~ 15 s；**总时长 ≤ 15 s**                |
| 宽高 / 长宽比 / 帧率 | 256 \~ 5760 px / 0.4 \~ 2.5 / 23.976 \~ 60 |

### 音频（仅多模态参考场景）

| 项   | 限制                      |
| --- | ----------------------- |
| 格式  | WAV、MP3                 |
| 单文件 | ≤ 15 MB                 |
| 个数  | ≤ 3                     |
| 时长  | 单段 2 \~ 15 s；总时长 ≤ 15 s |

## 参数约束

以下约束违反时请求将被拒绝并返回 **400**（敏感内容可能返回 **422**），且 **不产生计费**：

| 参数             | 约束                                                   |
| -------------- | ---------------------------------------------------- |
| `prompt`       | 任何场景必填且非空，≤ 7000 字符                                  |
| `duration`     | 仅接受 `4` \~ `15` 的整数                                  |
| `resolution`   | 仅 `2K`                                               |
| `aspect_ratio` | 见「宽高比规则」；文生不传时回落 `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">
      任务唯一标识符，用于查询任务状态和结果
    </ResponseField>
  </Expandable>
</ResponseField>

## 请求示例

### 场景 1：文生视频

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
  "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": "镜头从清晨缓慢过渡到日落",
  "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": "角色说话：Follow the wind, live free. Leave worries behind, enjoy the moment，音色参考音频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": "镜头从清晨缓慢过渡到日落",
  "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`。使用 [获取任务状态](/cn/api-reference/tasks/status) 接口查询生成进度和结果。

  建议每 **5 \~ 10 秒**轮询一次，客户端超时建议设为 **15 分钟**。成功后 `result.videos[0].url` 为 mp4 地址；视频 URL 约 **24 小时**有效，请及时转存。任务失败时会自动退款。
</Note>