> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flatkey.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax H3 调用指南

> 通过 Flatkey 使用文本或参考素材创建 MiniMax H3 视频任务，轮询任务状态并下载生成结果。

Base URL: `https://router.flatkey.ai`

当你需要文生视频、首尾帧控制，或图片、视频和音频参考时，可以使用 `MiniMax-H3`。所有请求都使用同一套异步流程：创建任务、轮询状态、下载最终 MP4。

<CardGroup cols={2}>
  <Card title="多种输入方式" icon="images">
    使用文本、首尾帧图片或图片、视频、音频参考生成视频。
  </Card>

  <Card title="统一异步流程" icon="video">
    用 `POST /v1/videos` 创建任务，用 `GET /v1/videos/{task_id}` 轮询，再从 `metadata.url` 下载视频。
  </Card>
</CardGroup>

创建任务和查询状态时都要使用以下鉴权头：

```http theme={"dark"}
Authorization: Bearer YOUR_FLATKEY_API_KEY
```

请保护好 API Key，不要把它贴到公开日志、页面或工单中。

## 创建第一个 H3 视频

### 1. 提交文生视频任务

使用 `MiniMax-H3` 模型和文本提示词调用 `POST /v1/videos`。纯文本请求必须显式指定画面比例，并且不能使用 `adaptive`。

<CodeGroup>
  ```bash Bash theme={"dark"}
  curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMax-H3",
      "content": [
        {
          "type": "text",
          "text": "纸船穿过雨后的水洼，电影感微距镜头"
        }
      ],
      "resolution": "768P",
      "duration": 6,
      "ratio": "16:9",
      "aigc_watermark": false
    }'
  ```

  ```powershell Windows PowerShell theme={"dark"}
  curl.exe --fail-with-body -sS https://router.flatkey.ai/v1/videos `
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
    -H "Content-Type: application/json" `
    -d '{
      "model": "MiniMax-H3",
      "content": [
        {
          "type": "text",
          "text": "纸船穿过雨后的水洼，电影感微距镜头"
        }
      ],
      "resolution": "768P",
      "duration": 6,
      "ratio": "16:9",
      "aigc_watermark": false
    }'
  ```
</CodeGroup>

响应会在 `id` 和 `task_id` 中返回公开任务 ID：

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0
}
```

保存返回的 `task_...`。后续查询任务时需要使用它。

### 2. 轮询并下载结果

重复调用 `GET /v1/videos/{task_id}`，直到 `status` 变成 `completed` 或 `failed`。状态变成 `completed` 后，从 `metadata.url` 读取临时下载地址。

<CodeGroup>
  ```bash Bash theme={"dark"}
  TASK_ID="task_3f9a00000000000000000000000000e2"

  curl --fail-with-body -sS \
    "https://router.flatkey.ai/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

  # 重复查询，直到 status 变成 completed。
  # 然后复制响应中的 metadata.url，粘贴到下面。
  VIDEO_URL="PASTE_METADATA_URL_HERE"
  curl --fail --location "$VIDEO_URL" --output minimax-h3.mp4
  ```

  ```powershell Windows PowerShell theme={"dark"}
  $taskId = "task_3f9a00000000000000000000000000e2"

  while ($true) {
    $result = curl.exe --fail-with-body -sS `
      "https://router.flatkey.ai/v1/videos/$taskId" `
      -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" | ConvertFrom-Json
    Write-Host "status: $($result.status)"

    if ($result.status -eq "completed") { break }
    if ($result.status -eq "failed") {
      $result | ConvertTo-Json -Depth 10
      exit 1
    }
    Start-Sleep -Seconds 5
  }

  curl.exe --fail --location $result.metadata.url --output minimax-h3.mp4
  ```
</CodeGroup>

`metadata.url` 是临时下载地址，不需要 Flatkey 鉴权头。任何拿到该地址的人都能在地址失效前访问生成的视频。请把它视为私密信息，不要记录到日志、公开或分享。请尽快下载视频并保存到自己的存储中。重复查询任务不会刷新已经失效的地址。

## 选择输入方式

每个请求都必须包含非空文本。你可以再添加首尾帧或参考素材来控制结果。

| 输入   | `type`      | 必须使用的 `role`               | 数量限制                        |
| ---- | ----------- | -------------------------- | --------------------------- |
| 提示词  | `text`      | 不要设置 `role`                | 所有文本合计最多 7,000 个 Unicode 字符 |
| 首帧   | `image_url` | `first_frame`，也可以省略 `role` | 1 张                         |
| 尾帧   | `image_url` | `last_frame`               | 1 张                         |
| 参考图片 | `image_url` | `reference_image`          | 9 张                         |
| 参考视频 | `video_url` | `reference_video`          | 3 段                         |
| 参考音频 | `audio_url` | `reference_audio`          | 3 段；同时还要提供参考图片或参考视频         |

<Warning>
  不要在同一个请求中混用首尾帧和参考素材。每个 `content` 元素只能包含一种与 `type` 对应的载荷。
</Warning>

### 控制首帧和尾帧

当你希望视频在两张图片之间自然过渡时，使用 `first_frame` 和 `last_frame`。

```bash theme={"dark"}
curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "镜头缓慢拉远，晨雾穿过山谷"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first.jpg" },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/last.jpg" },
        "role": "last_frame"
      }
    ],
    "resolution": "2K",
    "duration": 8,
    "ratio": "adaptive"
  }'
```

### 使用参考素材生成

参考素材可以帮助你保持主体、运动风格或声音一致。参考音频不能作为唯一的媒体输入。

```bash theme={"dark"}
curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "保持人物和运动风格一致，让角色穿过雪中的街道"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/character.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/motion.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "https://example.com/ambience.mp3" },
        "role": "reference_audio"
      }
    ],
    "resolution": "768P",
    "duration": 10,
    "ratio": "adaptive"
  }'
```

## 请求设置

| 字段               | 是否必填    | 支持的值                                                     |
| ---------------- | ------- | -------------------------------------------------------- |
| `model`          | 是       | `MiniMax-H3`                                             |
| `content`        | 是       | 文本，以及可选的首尾帧或参考素材                                         |
| `resolution`     | 是       | `768P` 或 `2K`，区分大小写                                      |
| `duration`       | 是       | `4` 到 `15` 秒之间的整数                                        |
| `ratio`          | 纯文本请求必填 | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；有媒体时可用 `adaptive` |
| `aigc_watermark` | 否       | `true` 或 `false`                                         |

请求包含媒体且省略 `ratio` 时，Flatkey 会使用 `adaptive`。纯文本请求必须显式使用非 `adaptive` 的比例。

## 理解任务结果

| `status`      | 含义                                       |
| ------------- | ---------------------------------------- |
| `queued`      | 任务已创建，正在等待执行。                            |
| `in_progress` | 正在生成视频。`progress` 的范围是 0 到 100。          |
| `completed`   | 视频已生成，可以从 `metadata.url` 下载。             |
| `failed`      | 生成失败。请读取 `error.code` 和 `error.message`。 |

对于 H3 视频响应，通用 usage 字段表示秒数：

* `usage.completion_tokens` 表示生成视频的输出时长。
* `usage.total_tokens` 表示总计费时长，其中包含参考视频输入时长。

这些值的单位是秒，不是语言模型 token。最终费用请以 [Flatkey 控制台](https://console.flatkey.ai/usage-logs/common?lng=zh)中的**用量日志**为准。

## 当前限制

* 不支持 `callback_url`。请轮询任务状态。
* 不支持任务列表、取消、删除、再生成和 remix。
* 不支持 `MiniMax-H3-Context-IR`。
* 处理任务期间，远程素材 URL 必须保持可访问。

| 错误码                        | 检查方法                               |
| -------------------------- | ---------------------------------- |
| `invalid_duration`         | 把 `duration` 设置为 `4` 到 `15`。       |
| `invalid_resolution`       | 使用准确的 `768P` 或 `2K`。               |
| `invalid_ratio`            | 使用支持的比例。纯文本请求不能省略比例或使用 `adaptive`。 |
| `invalid_content`          | 检查提示词、`role`、素材数量和不能混用的输入组合。       |
| `unsupported_callback_url` | 删除 `callback_url`，改为轮询任务。          |