---
description: "Grok 与 MiniMax-H3 视频生成接口，Vega 模型另见专页。"
---

# 视频生成

本页有三套并列的接口，按需三选一：

- [Grok 视频](#grok-视频)：`grok-imagine-video-1.5`，预占 + 按实际结算。
- [MiniMax-H3 视频](#minimax-h3-视频)：提交时按声明秒数一次结清。
- [Vega 视频](./api-videos-vega.md)：腾讯 Vega 视频模型（`vega-1.0-lite` / `vega-1.0-pro` / `vega-1.5-pro`），预冻结 + 完工实结，详见单开页。

## Grok 视频

`grok-imagine-video-1.5` 使用异步任务接口。提交成功后保存 `request_id`，轮询任务状态，完成后通过内容端点下载视频。

### 支持能力

#### 生成模式

| 模式 | 请求字段 | 说明 |
|------|----------|------|
| 文生视频 | `prompt` | 根据文字描述生成视频 |
| 单图生视频 | `prompt` + `image` | 将一张图片作为起始画面生成视频 |
| 参考图生视频 | `prompt` + `reference_images` | 使用最多 7 张图片引导视频内容与风格 |

`image` 与 `reference_images` 不能同时使用。

#### 视频时长

支持 `1` 至 `15` 秒的整数时长，默认生成 `8` 秒。

#### 分辨率

| 值 | 说明 |
|----|------|
| `480p` | 标清，默认值 |
| `720p` | 高清 |

#### 画面比例

| 值 | 常见用途 |
|----|----------|
| `16:9` | 横屏视频，默认值 |
| `9:16` | 竖屏视频、短视频 |
| `1:1` | 正方形内容 |
| `4:3` | 传统横屏画面 |
| `3:4` | 竖版画面 |
| `3:2` | 横版摄影比例 |
| `2:3` | 竖版摄影比例 |

### 提交生成

> `POST https://oneapi.zaiwenai.com/v1/videos/generations`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 固定为 `grok-imagine-video-1.5` |
| `prompt` | string | 是 | 视频内容描述或运动指令 |
| `duration` | integer | 否 | `1` 至 `15` 秒，默认 `8` |
| `resolution` | string | 否 | `480p` 或 `720p`，默认 `480p` |
| `aspect_ratio` | string | 否 | 支持上方列出的 7 种比例，默认 `16:9` |
| `image` | object | 否 | 单图生视频，格式为 `{"url":"https://..."}` |
| `reference_images` | array | 否 | 参考图列表，最多 7 张，每项格式为 `{"url":"https://..."}` |

#### 文生视频

```bash
curl https://oneapi.zaiwenai.com/v1/videos/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A paper airplane glides through a quiet library",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

#### 单图生视频

```bash
curl https://oneapi.zaiwenai.com/v1/videos/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "The camera slowly pushes forward and the leaves move in the wind",
    "image": {"url": "https://example.com/scene.jpg"},
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'
```

#### 参考图生视频

```bash
curl https://oneapi.zaiwenai.com/v1/videos/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "Create a cinematic scene using the character and clothing in the references",
    "reference_images": [
      {"url": "https://example.com/character.jpg"},
      {"url": "https://example.com/clothing.jpg"}
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

提交成功返回 HTTP `202`：

```json
{
  "request_id": "video_0123456789abcdef",
  "model": "grok-imagine-video-1.5",
  "status": "pending",
  "progress": 0
}
```

### 查询状态

> `GET https://oneapi.zaiwenai.com/v1/videos/{request_id}`

```bash
curl https://oneapi.zaiwenai.com/v1/videos/video_0123456789abcdef \
  -H "Authorization: Bearer $YOUR_API_KEY"
```

任务处理中返回 HTTP `202`。任务完成后返回 HTTP `200`：

```json
{
  "request_id": "video_0123456789abcdef",
  "model": "grok-imagine-video-1.5",
  "status": "done",
  "progress": 100,
  "usage": {
    "cost": 2.45,
    "currency": "CNY"
  },
  "video": {
    "url": "/v1/videos/video_0123456789abcdef/content",
    "duration": 5
  }
}
```

`status` 可能为：

| 状态 | 说明 |
|------|------|
| `pending` | 等待或正在生成 |
| `running` | 正在生成 |
| `processing` | 正在处理生成结果 |
| `done` | 已完成，可以下载 |
| `failed` | 生成失败 |

### 下载视频

> `GET https://oneapi.zaiwenai.com/v1/videos/{request_id}/content`

下载端点需要 API Key，并支持 HTTP `Range` 请求：

```bash
curl -L https://oneapi.zaiwenai.com/v1/videos/video_0123456789abcdef/content \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  --output result.mp4
```

任务仅对创建它的 API Key 所属用户可见。

### 计费说明

视频费用根据实际调用动态计算，主要受以下因素影响：

- 生成时长：视频越长，费用通常越高。
- 输出分辨率：`720p` 的费用通常高于 `480p`。
- 图片输入：使用单图或参考图会产生额外费用，图片数量也会影响最终费用。

提交任务时会先预占预计费用。任务成功后按实际生成结果结算，多余的预占金额会自动退回；任务失败则释放全部预占金额。最终人民币费用可在任务结果的 `usage.cost` 和平台调用记录中查看。

## MiniMax-H3 视频

任务制接口：提交返回 `task_id`，轮询到 `completed` 后用内容端点下载。
与 Grok 接口的区别：提交成功即按声明秒数计费一次（无预占），查询与下载不计费；
任务状态保存在上游。

### 支持的模型

| 模型 ID | 分辨率 | 单价 |
|---------|--------|------|
| `minimax-h3-768p` | 768P | 0.50 元/秒 |
| `minimax-h3-2k` | 2K | 0.80 元/秒 |

### 提交生成

> `POST https://oneapi.zaiwenai.com/v1/videos/std/generations`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 上方模型 ID 之一 |
| `prompt` | string | 是 | 视频内容描述，最多 7000 字符 |
| `seconds` | integer | 是 | `4` 至 `15` 秒 |
| `ratio` | string | 否 | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`，缺省上游默认 |
| `reference_images` | array | 否 | 参考图 URL 列表，最多 5 张 |
| `reference_videos` | array | 否 | 参考视频 URL 列表，最多 3 个 |
| `reference_audios` | array | 否 | 参考音频 URL 列表，最多 3 个 |

```bash
curl https://oneapi.zaiwenai.com/v1/videos/std/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-768p",
    "prompt": "Aerial view of ocean waves at sunset, cinematic lighting",
    "seconds": 5
  }'
```

### 参考素材生成

三组参考素材都是 URL 字符串数组，按此格式传入：

```bash
curl https://oneapi.zaiwenai.com/v1/videos/std/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-768p",
    "prompt": "The people in the picture are performing contemporary dance",
    "seconds": 4,
    "reference_images": [
      "https://example.com/dancer1.png",
      "https://example.com/dancer2.png"
    ],
    "reference_videos": [
      "https://example.com/street-dance.mp4"
    ],
    "reference_audios": [
      "https://example.com/rhythm.mp3"
    ]
  }'
```

提交成功返回 HTTP `202`：

```json
{
  "id": "task_8tsRBVOr1X0lueC6AjhMwgtM1laIMyrt",
  "object": "video",
  "model": "minimax-h3-768p",
  "status": "queued",
  "progress": 0
}
```

### 查询状态

> `GET https://oneapi.zaiwenai.com/v1/videos/std/generations/{task_id}`

```bash
curl https://oneapi.zaiwenai.com/v1/videos/std/generations/task_8tsRBVOr1X0lueC6AjhMwgtM1laIMyrt \
  -H "Authorization: Bearer $YOUR_API_KEY"
```

`status` 为 `queued` / `in_progress` 时继续轮询（建议间隔 20 秒以上），
`completed` 后下载，`failed` 查看原因。查询不计费。

### 下载视频

> `GET https://oneapi.zaiwenai.com/v1/videos/std/generations/{task_id}/content`

支持 HTTP `Range` 请求，下载不计费：

```bash
curl -L https://oneapi.zaiwenai.com/v1/videos/std/generations/task_8tsRBVOr1X0lueC6AjhMwgtM1laIMyrt/content \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  --output result.mp4
```

### 计费说明

- 提交成功按 `ceil(seconds) × 所选模型单价` 计费一次（如 5 秒 768P 计 2.50 元）。
- 查询与下载不产生费用；提交失败（余额不足、参数错误、上游拒单）不计费。

## Vega 视频

已移至单开页 [Vega 视频生成](./api-videos-vega.md)。