> ## 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 / 768P 分辨率，时长 4 ~ 15 秒，带音轨
- 与 MiniMax-Hailuo-02 / MiniMax-Hailuo-2.3 共用统一提交与查询接口 

```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": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    "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": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    "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: "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
  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":       "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
        "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": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
          "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" => "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    "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: "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
  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": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    "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"": ""一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜"",
            ""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);
    }
}
```

```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"
  }
}
```

## 认证

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

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

使用时在请求头中添加：

```
Authorization: Bearer YOUR_API_KEY
```

## 生成模式

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]
>
> **不能只给音频。** 传了 `audio_urls` 时，必须至少再配一个参考图或参考视频。

## 请求参数

### 通用字段

**model** `string` *required*

固定值：`MiniMax-H3`

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

**nsfw\_check** `boolean` (default: false)

是否在提交视频任务前执行内容审核。

* `true`：使用 `omni-moderation-latest` 审核提示词和输入图片
* `false` 或不传：不发起审核请求，不增加审核成本与延迟（默认）

**prompt** `string` *required*

视频内容描述，**任何场景都必填且不能为空**，单条 ≤ **7000** 字符

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

示例：`"一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜"`

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

生成时长（秒）

* 取值范围：`4` \~ `15` 的整数
* 默认值：`5`

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

视频分辨率

可选值：

* `2K`（默认）
* `768P`

**aspect\_ratio** `string`

宽高比。也可用 `size` 或 `ratio` 传，效果相同。

可选具体比例：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`

不同场景下的行为见下方「宽高比规则」。

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

是否添加 AIGC 水印

默认值：`false`

兼容字段名：`aigc_watermark`

**webhook** `string`

任务到达终态（成功 / 失败）时，本服务主动推送到该地址

> [!NOTE]
>
> 请使用 `webhook`，不要传官方的 `callback_url`。`callback_url` 由本服务内部使用，不接受用户传入。

### 图生视频字段

要做**首帧 / 尾帧**图生视频，必须显式指定，不要依赖 `image_urls` 张数推断。

**first\_frame\_image** `string`

首帧图 URL

传入后将以该图片作为视频的**起始画面**。

**last\_frame\_image** `string`

尾帧图 URL

传入后将以该图片作为视频的**结束画面**，可与 `first_frame_image` 组合实现首尾帧控制。

### 多模态参考字段

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

参考图 URL 数组

> [!WARNING]
>
> **`image_urls` 里的图一律按参考图（`reference_image`）处理**，不管传几张。不会按张数自动当成首帧 / 首尾帧。

* 数量：≤ **9**

**video\_urls** `string[]`

参考视频 URL 数组

* 数量：≤ **3**
* 格式与限制见下方「输入媒体限制」

**audio\_urls** `string[]`

参考音频 URL 数组

* 数量：≤ **3**
* 不能单独使用，必须搭配参考图或参考视频

### 通用图片数组（可选写法）

**image\_with\_roles** `object[]`

带角色的图片数组，可替代 `first_frame_image` / `last_frame_image` / `image_urls`。每个元素结构如下：

**image\_with\_roles 元素**

**url** `string` *required*

图片 URL

**role** `string` *required*

图片角色，可选值：

* `first_frame`（也接受 `first`）— 首帧（图生视频）
* `last_frame`（也接受 `last`）— 尾帧（图生视频）
* `reference_image`（也接受 `reference`）— 参考图（多模态参考）

示例（首尾帧）：

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

## 宽高比规则

| 场景 | `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`（默认）或 `768P` |
| `aspect_ratio` | 见「宽高比规则」；文生不传时回落 `16:9` |
| 首尾帧与参考素材 | **互斥**，不能混用 |
| `audio_urls` | 不能单独输入，须搭配参考图或参考视频 |
| 参考图 | ≤ 9 |
| 参考视频 | ≤ 3 |
| 参考音频 | ≤ 3 |
| 参考视频探测失败 | 返回 `input_video_probe_failed`（URL 不可访问或文件损坏），**未扣费** |

## 响应

**code** `integer`

响应状态码，成功时为 200

**data** `array`

返回数据数组

**数组元素**

**status** `string`

任务状态，初始提交时为 `submitted`

**task\_id** `string`

任务唯一标识符，用于查询任务状态和结果

## 请求示例

### 场景 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`。使用 [获取任务状态](https://docs.apimart.ai/cn/api-reference/tasks/status.md) 接口查询生成进度和结果。
>
> 建议每 **5 \~ 10 秒**轮询一次，客户端超时建议设为 **15 分钟**。成功后 `result.videos[0].url` 为 mp4 地址；视频 URL 约 **24 小时**有效，请及时转存。任务失败时会自动退款。


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