# MiniMax 视频接口

<a id="minimax"></a>

<a id="minimax-视频接口"></a>

## 接口说明

兼容 New API Hailuo 插件

New API 的 Hailuo Video 插件可以直接接入本站。接口地址填写 `https://xiatuai.com`（不加 /v1 或 /v2），密钥使用本站 API Key。model 填写本站模型目录或 `/v1/models` 返回的实际模型 ID，例如 `minimax-h3-optimized`。v1、v2 均使用本站模型配置，查询结果保留本站模型 ID。

Hailuo Video 1.2.0 使用本站模型 ID 时会选择 v1 接口，可用于文生视频、首尾帧和主体参考。多模态 content\[\] 可直接请求本站 v2 接口；该版本插件仅为名称 MiniMax-H3 自动选择 v2，经它使用 v2 需调整插件的接口选择逻辑，model 仍填写本站模型 ID。

POST`/v1/video_generation`v1 创建：prompt、first\_frame\_image、last\_frame\_image、subject\_reference

GET`/v1/query/video_generation?task_id=TASK_ID`v1 查询：Queueing / Processing / Success / Fail；成功返回 file\_id

GET`/v1/files/retrieve?file_id=FILE_ID`文件信息，返回 file.download\_url

GET`/v1/files/download?file_id=FILE_ID`携带 API Key 下载 MP4，也支持 HEAD

POST`/v2/video_generation`H3 创建：content\[\]、duration、resolution、ratio

GET`/v2/query/video_generation/TASK_ID`H3 查询：task.status；成功结果位于 task.content.url

 **MiniMax H3 · 创建任务**  `POST /v2/video_generation`

```bash
curl 'https://xiatuai.com/v2/video_generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-h3-optimized",
  "content": [
    {
      "type": "text",
      "text": "海浪轻拍沙滩，镜头缓慢推进"
    }
  ],
  "duration": 6,
  "resolution": "768P",
  "ratio": "16:9"
}'
```

<a id="h3-reference-prompt"></a>

### H3 参考视频与提示词引用

`minimax-h3-optimized` 支持图片、视频、音频组合参考。当前目录配置最多 9 张参考图、3 段参考视频、3 段参考音频；实际可用数量、格式和上传限制以所选模型目录为准。参考视频可用于说明动作、运镜、剪辑节奏或需要编辑的原视频。

选择工作台的“普通参考素材”，上传素材后，点击“图片1”“视频1”“音频1”或在提示词中输入 `@` 选择素材。工作台会把中文引用转换为下面的 H3 标签，并自动关联尚未提及的素材。首尾帧模式不使用这套引用，也不能混入参考视频或音频。

 素材 | H3 提示词标签 | 用途示例 |
| --- | --- | --- |
 第一张参考图 | `<Picture 1>` | 人物外貌、服装、场景、画面风格 |
 第一段参考视频 | `<Video 1>` | 动作、镜头运动、剪辑节奏、视频编辑 |
 第一段参考音频 | `<Audio 1>` | 音色、音乐风格、节奏；需搭配图片或视频 |

三类素材分别从 1 编号，对应各自数组中的顺序；例如第一张图片和第一段视频分别是 `<Picture 1>` 与 `<Video 1>`。标签区分大小写，单词和数字之间保留空格。手写 API 提示词请直接使用 H3 标签；工作台里的 `@图片1` 是编辑辅助写法。

 **标签必须配合实际素材。** 仅在提示词里写视频标签或网址不会加载视频；请同时提交对应媒体字段。删除已引用素材后，工作台会提示失效引用，需要修正后再生成。

### 图片外观 + 视频动作示例

```
保持 <Picture 1> 中人物的外貌和服装，参考 <Video 1> 的动作、运镜和剪辑节奏，将场景改为傍晚的海边。
```

以下通过本站 `POST /v2/video_generation` 同时提交人物图和动作视频。替换媒体地址和密钥；如果修改素材或参数，请更换幂等标识。已受理任务只查询原任务，不要因等待超时重复创建。

```bash
curl 'https://xiatuai.com/v2/video_generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: h3-reference-001' \
  -d '{
  "model": "minimax-h3-optimized",
  "content": [
    {
      "type": "text",
      "text": "保持 <Picture 1> 中人物的外貌和服装，参考 <Video 1> 的动作、运镜和剪辑节奏，将场景改为傍晚的海边。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/person.jpg"
      }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "url": "https://example.com/motion.mp4"
      }
    }
  ],
  "duration": 6,
  "resolution": "768P",
  "ratio": "16:9"
}'
```

使用本站通用 `POST /v1/videos` 时，文本放在 `prompt`，媒体分别放在 `reference_images`、`reference_videos`、`reference_audios`，并设置 `reference_mode="asset"`；不要把这套顶层字段与 v2 的 `content[]` 混用。[查看本地视频上传示例](https://xiatuai.com/docs.md?page=video#video-reference-upload)。

创建返回 `{"task_id":"任务ID"}`。v2 查询状态为 `queued / running / succeeded / failed`，成功后直接下载 `task.content.url`，保留完整查询参数。v1 返回 `base_resp.status_code`，0 表示成功。查询与文件信息需要 Bearer API Key；结果链接自带临时凭证，最长有效 24 小时，过期后查询返回失败。

H3 优化版支持 4–15 整数秒、768P；720P 按原有兼容规则对应 768P。接口兼容不会增加模型能力，480P、2K 或未启用的 Hailuo 模型仍会被拒绝。v1 默认 6 秒，v2 默认 5 秒；分辨率省略时使用模型默认档位。

v2 的 `content[]` 支持 text、image\_url、video\_url、audio\_url。图片 role 为 first\_frame、last\_frame 或 reference\_image，视频和音频分别为 reference\_video、reference\_audio；首尾帧与素材参考互斥。图像参考支持公网地址、Data URI 或 Base64；视频、音频遵循模型素材限制。adaptive 根据第一张参考图选择最接近的支持比例；纯视频参考请显式填写 ratio。尾帧需要首帧，纯音频参考不支持。

可传 `Idempotency-Key` 防止重复创建和扣费。失败沿用本站退款和积分流水规则。暂不支持 callback\_url、水印、提示词优化或快速预处理；对应布尔选项可省略或设为 false，开启时会明确报错。未测量的输入时长和 token 用量不会伪造返回。