# MiniMax 视频生成
> 文生视频、首帧、首尾帧、多模态参考
> 参考图、参考视频、参考音频可以同时使用
> 提示词里可用方括号写运镜指令
`POST /v1/videos`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
> **Note:** 
> 提交成功只返回任务 ID，不含视频本身。拿成片用 `task_id` 轮询[获取任务状态](../tasks/status.html)，成片地址在 `result.videos[0].url`，该地址约 24 小时后过期，请及时转存。
- `model` (string / 必填) — 模型 ID，取值见下方模型列表。
- `prompt` (string / 必填) — 画面描述。所有模式都必填，包括图生视频与参考生视频。 H3 上限 7000 字符，Hailuo 2.3 上限 2000 字符。
- `duration` (integer / 可选) — 时长，单位秒。 - `MiniMax-H3`：4 到 15，默认 `5` - `MiniMax-Hailuo-2.3`：`6` 或 `10`，默认 `6` - `MiniMax-Hailuo-02`：`5` 或 `10`，默认 `5`
- `resolution` (string / 可选) — 输出分辨率。 - `MiniMax-H3`：`2K`、`768P`，默认 `2K` - `MiniMax-Hailuo-2.3`：`768p`、`1080p`，默认 `768p` - `MiniMax-Hailuo-02`：`512p`、`768p`、`1080p`，默认 `768p`
- `aspect_ratio` (string / 可选) — 输出画幅，取值 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。 别名 `size`、`ratio`。图生视频会忽略该字段，改用输入图片比例。
- `first_frame_image` (string / 可选) — 首帧图片地址，公网 URL 或 Base64 data URI。传入即进入图生视频。 与参考类字段互斥。
- `last_frame_image` (string / 可选) — 尾帧图片地址，可与 `first_frame_image` 组合成首尾帧过渡。 与参考类字段互斥。
- `image_urls` (string[] / 可选) — 多模态参考图，H3 最多 9 张。 该字段下的图片一律按参考图处理，不会因为数量变成首尾帧。
- `video_urls` (string[] / 可选) — 参考视频，H3 最多 3 段。
- `audio_urls` (string[] / 可选) — 参考音频，H3 最多 3 段。不能单独使用，必须至少配一张参考图或一段参考视频。
- `image_with_roles` (object[] / 可选) — 带角色的图片数组，每项含 `url` 与 `role`。 `role` 取值 `first_frame`、`last_frame`、`reference_image`，也可用简写 `first`、`last`、`reference`。
- `prompt_optimizer` (boolean / 可选) — 自动改写提示词，默认 `true`。
- `fast_pretreatment` (boolean / 可选) — 缩短提示词优化耗时，画质略有损失，默认 `false`。
- `watermark` (boolean / 可选) — 是否添加 AIGC 水印，默认 `false`。别名 `aigc_watermark`。
- `webhook` (string / 可选) — 任务终态回调地址。不要使用官方的 `callback_url`，该字段保留给内部使用。
- `nsfw_check` (boolean / 可选) — 为 `true` 时先做内容审查，默认 `false`。
## 模式判定
只传提示词与通用字段是文生视频。
传 `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。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `MiniMax-H3` | 当前旗舰，最高 2K，支持图、视频、音频三类参考 |
| `MiniMax-H3-max` | H3 的高配版 |
| `MiniMax-Hailuo-2.3` | 支持首帧与首尾帧，1080p 限 6 秒 |
| `MiniMax-Hailuo-2.3-Fast` | 快速版，必须传 `first_frame_image` |
| `MiniMax-Hailuo-02` | 上一代，512p 到 1080p 三档 |
## 使用限制
- 1080p 与 10 秒不能组合，1080p 只支持 6 秒
- 参考音频不能单独使用
- 请求体不超过 64MB，大文件请用公网地址而不是 Base64
- 图片单张不超过 30MB，边长 256 到 5760 像素，宽高比 0.4 到 2.5
- 参考视频单段 2 到 15 秒，合计不超过 15 秒，单段不超过 50MB
- 参考音频每段 2 到 15 秒，合计不超过 15 秒，单段不超过 15MB
## 响应
提交成功返回统一的受理结构：
```json
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
- `code` (integer / 总是返回) — 状态码，`200` 表示任务已受理。
- `data` (array / 总是返回) — 本次提交的任务列表，逐项提交时按顺序排列。
- `data[].status` (string / 总是返回) — 受理状态，提交成功时为 `submitted`。
- `data[].task_id` (string / 总是返回) — 任务 ID，用它轮询结果。
## 错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
内容安全审查不通过时返回 422，同样不扣费。
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 查询任务
`GET /v1/tasks/{task_id}` 返回任务进度与结果，`status` 为 `completed` 时成片地址在 `result.videos[0].url`，元素带 `expires_at` 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。`status` 取值 `pending`、`processing`、`completed`、`failed`、`cancelled`，以状态判定完成，不要依赖 `progress`。
失败任务自动退回费用，`error.message` 给出原因。
**文生视频{Text to video}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-H3",
  "prompt": "一只猫咪在草地上奔跑，阳光明媚，慢动作",
  "duration": 6,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}'
```
**文生视频{Text to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "MiniMax-H3",
  "prompt": "一只猫咪在草地上奔跑，阳光明媚，慢动作",
  "duration": 6,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生视频{Text to video}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "MiniMax-H3",
  "prompt": "一只猫咪在草地上奔跑，阳光明媚，慢动作",
  "duration": 6,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}),
});
console.log(await res.json());
```
**200 文生视频{Text to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**首帧{First frame}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "人物缓缓转身，看向远处的海面",
  "first_frame_image": "https://example.com/person.jpg",
  "duration": 6,
  "resolution": "768p"
}'
```
**首帧{First frame}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "人物缓缓转身，看向远处的海面",
  "first_frame_image": "https://example.com/person.jpg",
  "duration": 6,
  "resolution": "768p"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**首帧{First frame}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "人物缓缓转身，看向远处的海面",
  "first_frame_image": "https://example.com/person.jpg",
  "duration": 6,
  "resolution": "768p"
}),
});
console.log(await res.json());
```
**200 首帧{First frame}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**首尾帧{First and last frame}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "城市从白天过渡到夜晚",
  "first_frame_image": "https://example.com/day.jpg",
  "last_frame_image": "https://example.com/night.jpg",
  "duration": 6
}'
```
**首尾帧{First and last frame}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "城市从白天过渡到夜晚",
  "first_frame_image": "https://example.com/day.jpg",
  "last_frame_image": "https://example.com/night.jpg",
  "duration": 6
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**首尾帧{First and last frame}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "城市从白天过渡到夜晚",
  "first_frame_image": "https://example.com/day.jpg",
  "last_frame_image": "https://example.com/night.jpg",
  "duration": 6
}),
});
console.log(await res.json());
```
**200 首尾帧{First and last frame}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**多模态参考{Multimodal reference}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-H3",
  "prompt": "参考图中的角色在参考视频的街道上行走，配乐跟随参考音频的节奏",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "duration": 8,
  "resolution": "2K"
}'
```
**多模态参考{Multimodal reference}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "MiniMax-H3",
  "prompt": "参考图中的角色在参考视频的街道上行走，配乐跟随参考音频的节奏",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "duration": 8,
  "resolution": "2K"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多模态参考{Multimodal reference}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "MiniMax-H3",
  "prompt": "参考图中的角色在参考视频的街道上行走，配乐跟随参考音频的节奏",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "duration": 8,
  "resolution": "2K"
}),
});
console.log(await res.json());
```
**200 多模态参考{Multimodal reference}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```