# MiniMax-H3 API

`MiniMax-H3` 使用 MiniMax V2 的请求和任务响应格式，提供视频生成能力。Base URL 为 `https://api.seedance.nz`，鉴权使用本站 API Key：`Authorization: Bearer <API_KEY>`。从 MiniMax V2 客户端迁移时，替换 Base URL 和 API Key，并按下面的能力范围调整请求。

机器可读定义：[OpenAPI JSON](minimax-h3-openapi.json)。完整指南和接口定义可从 `/docs/minimax-h3-api.md` 和 `/docs/minimax-h3-openapi.json` 下载。

## 能力与兼容范围

| 项目 | 本接口 |
| --- | --- |
| 模型名称 | `MiniMax-H3`，区分大小写 |
| 文生视频 | 支持，至少一个非空 `text` 内容项；拼接后提示词最多 10000 字符 |
| 参考素材视频 | 最多 9 张参考图片、3 条参考音频、3 条参考视频，可组合使用 |
| 独立驱动音频 | 额外 1 条 `drive_audio`，与 3 条参考音频分开计数 |
| 分辨率 | `480P` / `768P` / `1080P`，也接受小写 |
| 时长 | 普通请求整数 4–15 秒；含驱动音频请求整数 4–60 秒 |
| 输出 | 一个视频 URL；最终文件应由调用方及时保存 |
| 首帧、尾帧、首尾帧 | 支持单独 `first_frame`、单独 `last_frame` 或同时提供两者，按专用关键帧模式执行 |
| 混合关键帧与参考素材 | 支持关键帧与参考图、音频、视频或驱动音频组合；各类上限独立计数，属于本服务扩展 |
| 2K、MiniMax-H3-Max、Context-IR、视频再生成 | 不属于此模型接口 |

官方当前 MiniMax-H3 的分辨率范围是 `768P` / `2K`、时长为 4–15 秒。本服务的 `480P`、`1080P`、`drive_audio`、`audio_control`、视频起始偏移、`2:3` / `3:2` 比例、混合关键帧与参考素材及长驱动音频任务属于扩展。参考站 H3 Gateway 的 `/v1/videos`、`target`、`conditions`、OSS 预签名 PUT 是另一套 SPI，不能直接作为本接口请求体。

## 价格

按提交请求的输出时长计费，标准零售价如下。参考图片、音频、视频不另加输入费用。

| 分辨率 | 元/秒 | 5 秒 | 10 秒 | 15 秒 | 60 秒驱动音频 |
| --- | ---: | ---: | ---: | ---: | ---: |
| 480P | 0.15 | 0.75 | 1.50 | 2.25 | 9.00 |
| 768P | 0.30 | 1.50 | 3.00 | 4.50 | 18.00 |
| 1080P | 0.45 | 2.25 | 4.50 | 6.75 | 27.00 |

1080P 保留工作流原生对齐尺寸：16:9 输出 1920×1088，其他比例短边同样为 1088 像素。

提交时预扣，任务失败释放相应预扣额度。删除已完成任务的记录不会退款；取消请求返回错误时，原任务继续执行和结算。账户实际价格以控制台适用的分组及折扣为准。

## 接口

| 方法 | 路径 | 成功响应 |
| --- | --- | --- |
| POST | `/v2/video_generation` | `{"task_id":"..."}` |
| GET | `/v2/query/video_generation/{task_id}` | `{"task":{...}}` |
| GET | `/v2/query/video_generation` | `{"items":[...],"total":1}` |
| DELETE | `/v2/video_generation/{task_id}` | `{"task_id":"...","action":"deleted","status":"deleted"}` |
| POST | `/v1/files/upload` | 本站通用素材上传接口，返回 URL 后填入内容项 |

所有任务操作都使用当前 API Key 对应的账户和租户权限。任务 ID 不等于访问授权。已有 `/v1/video/generations` 入口继续提供本站通用视频协议；MiniMax V2 客户端请使用本节的 `/v2/` 路径。

## 创建任务

请求头：`Content-Type: application/json`。

| 字段 | 类型 | 要求 |
| --- | --- | --- |
| `model` | string | 必填，`MiniMax-H3` |
| `content` | array | 必填，至少一个非空 `text` 项；多段文字按顺序拼接，总计不超过 10000 字符 |
| `resolution` | string | 必填，`480P`、`768P` 或 `1080P` |
| `duration` | integer | 必填，普通 4–15；有 `drive_audio` 时 4–60 |
| `ratio` | string | 纯文本必填；参考请求省略时采用 `16:9`；关键帧请求可自适应，见下文 |
| `audio_control` | object | 可选扩展，包含 `mode`、`denoise_strength`、`add_drive_as_reference` |
| `callback_url` | string | 可选 HTTPS 地址，仅 443 端口；省略则通过查询接口轮询 |

支持的固定比例依次为 `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`9:16`、`16:9`、`21:9`，其中 `2:3`、`3:2` 是扩展比例。纯文本请求必须填写比例。参考请求省略时采用 `16:9`，显式传 `adaptive` 或 `auto` 会报错；这与官方参考模式默认 `adaptive` 不同。关键帧请求可指定固定比例，或省略/使用 `adaptive`（也接受扩展别名 `auto`）读取首帧图比例，仅有尾帧时读取尾帧，并选择 最接近的固定画幅；任务结果返回实际采用的比例。本服务会执行关键帧请求指定的固定比例，而官方会忽略它并使用自适应，因此这部分行为有差异。

内容项格式：

```json
{"type":"text","text":"电影感镜头，人物向镜头挥手。"}
```

```json
{"type":"image_url","image_url":{"url":"https://example.com/person.jpg"},"role":"reference_image"}
```

```json
{"type":"video_url","video_url":{"url":"https://example.com/motion.mp4"},"role":"reference_video"}
```

```json
{"type":"audio_url","audio_url":{"url":"https://example.com/voice.wav"},"role":"reference_audio"}
```

```json
{"type":"audio_url","audio_url":{"url":"https://example.com/dialogue.wav"},"role":"drive_audio"}
```

参考图片必须明确使用 `reference_image`。省略图片角色时按官方规则等同 `first_frame`；省略音频/视频角色时分别等同 `reference_audio` / `reference_video`。本服务允许首帧、尾帧与参考图片、参考音频、参考视频及驱动音频混用，按实际内容自动选择混合模式，无需填写 `task_type`。关键帧最多各 1 张，额外参考图最多 9 张，其他类别也按各自上限独立计数。这是本服务扩展；官方 V2 将关键帧与参考素材定义为互斥场景。

参考视频内容项还支持扩展字段 `start_time_seconds`（非负秒数，默认 0），放在 `role` 同级；服务按 24 FPS 换算起始帧。例如 2.5 秒对应跳过 60 帧。图片和音频不提供这个裁剪参数。

### 文生视频

```bash
export API_KEY='YOUR_API_KEY'
export BASE_URL='https://api.seedance.nz'

curl "$BASE_URL/v2/video_generation" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [{"type":"text","text":"航拍薄雾中的山谷，晨光穿过树梢，镜头平稳前进。"}],
    "resolution": "480P",
    "duration": 5,
    "ratio": "16:9"
  }'
```

HTTP 200 表示已接受任务，不表示视频已完成：

```json
{"task_id":"task_example"}
```

### 首帧、尾帧与首尾帧

```json
{
  "model":"MiniMax-H3",
  "content":[
    {"type":"text","text":"人物从首帧姿态自然转身，平稳过渡至尾帧构图。"},
    {"type":"image_url","image_url":{"url":"https://example.com/start.jpg"},"role":"first_frame"},
    {"type":"image_url","image_url":{"url":"https://example.com/end.jpg"},"role":"last_frame"}
  ],
  "resolution":"768P",
  "duration":5,
  "ratio":"adaptive"
}
```

省略尾帧项即为首帧生成；省略首帧项即为尾帧生成。首帧和尾帧最多各一张，角色决定用途，不依赖它们在数组中的顺序。自适应会选择最接近输入图的固定比例，而不是保证任意比例的原尺寸输出。

### 多模态参考

```json
{
  "model":"MiniMax-H3",
  "content":[
    {"type":"text","text":"保持参考图人物的外貌，参考视频中的镜头运动，使用参考音频的声音风格。"},
    {"type":"image_url","image_url":{"url":"https://example.com/person.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/voice.wav"},"role":"reference_audio"}
  ],
  "resolution":"768P",
  "duration":10,
  "ratio":"16:9"
}
```

### 驱动音频与声音参考

`reference_audio` 提供声音参考；`drive_audio` 提供目标音频驱动。音色参考不等于强制按照音频逐字对口型。需要按台词生成时，在文字提示中同时写出明文台词。

```json
{
  "model":"MiniMax-H3",
  "content":[
    {"type":"text","text":"参考图中的人物正对镜头，口型跟随 <Audio 1>，说：<d>[中文] 今天的天气真好。</d>"},
    {"type":"image_url","image_url":{"url":"https://example.com/person.jpg"},"role":"reference_image"},
    {"type":"audio_url","audio_url":{"url":"https://example.com/dialogue.wav"},"role":"drive_audio"}
  ],
  "resolution":"480P",
  "duration":5,
  "ratio":"16:9",
  "audio_control":{"mode":"lock_source","denoise_strength":0,"add_drive_as_reference":true}
}
```

| `audio_control.mode` | 语义 |
| --- | --- |
| `lock_source` | 保留驱动音频；需要 `drive_audio` |
| `remix_source` | 基于驱动音频重新生成音轨；需要 `drive_audio` |
| `reference_only` | 驱动音频只作为参考；需要 `drive_audio`，`add_drive_as_reference` 省略时为 true，显式 false 会报错 |
| `native` | 生成原生音轨；也可提供驱动音频，但不会锁定原音轨，是否作为参考由 `add_drive_as_reference` 决定 |

有驱动音频时缺省使用 `lock_source`，无驱动音频时缺省使用 `native`。`denoise_strength` 范围 0–1，用于调节 `remix_source` 的音轨重生成；`lock_source` 的有效值固定为 0，其他模式缺省 0.35。`add_drive_as_reference` 决定是否把驱动音频同时提供为声音参考；有驱动且为非 native 模式时默认 true，native 模式默认 false。显式 0 和 false 会保留。希望驱动台词同时使用另一条参考声音时，可以设置：

```json
{"audio_control":{"mode":"remix_source","denoise_strength":0.35,"add_drive_as_reference":false}}
```

`seed`、`num_inference_steps`、`flow_shift`、`audio_flow_shift` 和 `quality` 等不是当前开放参数。旧参考网关的 seed 仅记录和校验，没有控制 采样器，本服务不将它表述为可复现性控制。

## 查询结果

```bash
curl "$BASE_URL/v2/query/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "task":{
    "id":"task_example",
    "model":"MiniMax-H3",
    "status":"succeeded",
    "created_at":1788500000,
    "updated_at":1788500080,
    "content":{"url":"https://example.com/generated-video.mp4"},
    "resolution":"480P",
    "duration":5,
    "ratio":"16:9",
    "task_type":"generation",
    "modality":"video",
    "usage":{"amount":0.75,"currency":"CNY"}
  }
}
```

状态为 `queued`、`running`、`succeeded`、`failed` 或 `cancelled`。时间戳单位为 Unix 秒。成功读取 `task.content.url`，无需调用旧版 `file_id` 文件检索接口；进行中的任务不会包含成功视频 URL。失败查看 `task.error.code` / `task.error.message`。

`duration` 表示请求用于计费的输出时长。工作流按 24 FPS、`17n+5` 帧对齐，输出播放时长可能略长；费用仍按请求秒数计算。

任务完成最终结算后，`task.usage.amount` 与 `task.usage.currency` 才会出现。`amount` 与用户实际扣费完全一致，不是提交时的预扣金额；失败或取消任务完成退款后返回 `0`。响应不会暴露预扣额、内部结算 token 或上游供应商成本字段。任务尚未完成最终结算时省略整个 `usage` 字段。

建议每 5–10 秒查询一次；遇到查询 429 或暂时性 5xx 时退避重试查询。创建请求超时不代表任务未创建，本接口未承诺参考站 SPI 的 `request_id` 幂等行为，不应无条件重发生成请求。

网关按固定顺序使用主、备用两组上游凭据。仅在未获得任务编号且上游明确拒绝受理时切换一次备用凭据：HTTP 401、402、403、429，或响应中非零的明确业务错误码。已返回任务编号后始终查询原任务，任务运行失败不会重新创建；网络超时、5xx 或无效 JSON 无法确认是否受理，也不会自动换凭据重发。两次均被拒绝时返回最后一次错误，只有容量限制归类为 429。

如果网关已经尝试提交，但收到超时（包括 HTTP 408）或 5xx 等不确定结果，错误响应可带 `X-Task-Id` 和 `Retry-After: 5`。正文仍为 V2 错误格式，不另加 `task_id`。保存该响应头的公共任务 ID 并查询，网关会暂时保留任务记录和预扣，公开状态为 `queued`，后台尝试关联 bridge 已保存的任务。此时 `queued` 不表示上游一定尚未运行。只有 bridge 能按公共任务 ID 找回记录时才能恢复；不保证在 任务已受理、但 bridge 未保存 任务 ID 的情况下自动找回。未收到公共任务 ID 时，不要推断提交失败或盲目重提。明确拒绝的参数、授权、额度或容量类 4xx（不含上述提交超时）不走此恢复路径，并释放相应预扣。

### Python 完整调用示例

安装 `requests`，设置环境变量 `API_KEY`；此示例只提交一次，查询失败不会重新创建付费任务。

```python
import os
import time
import requests

base = os.environ.get("BASE_URL", "https://api.seedance.nz").rstrip("/")
headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
payload = {
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "晨光中的森林，镜头缓慢前进。"}],
    "resolution": "480P", "duration": 5, "ratio": "16:9",
}
created = requests.post(f"{base}/v2/video_generation", headers=headers,
                        json=payload, timeout=60)
if created.ok:
    task_id = created.json()["task_id"]
else:
    task_id = created.headers.get("X-Task-Id")
    if not task_id:
        created.raise_for_status()
    print("提交结果待确认，仅查询已有任务：", task_id)
print("task_id:", task_id)  # 保存此 ID，之后可恢复查询
deadline = time.monotonic() + 1800
delay = 10
while time.monotonic() < deadline:
    time.sleep(delay)
    try:
        response = requests.get(f"{base}/v2/query/video_generation/{task_id}",
                                headers=headers, timeout=30)
    except requests.RequestException:
        delay = min(delay * 2, 60)
        continue
    if response.status_code == 429 or response.status_code >= 500:
        delay = min(delay * 2, 60)
        continue
    response.raise_for_status()
    try:
        task = response.json()["task"]
    except (ValueError, KeyError) as exc:
        raise RuntimeError(f"查询响应无效；保留任务 ID {task_id}") from exc
    delay = 10
    if task["status"] == "succeeded":
        print("video URL:", task["content"]["url"])
        print("actual charge:", task["usage"]["amount"], task["usage"]["currency"])
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error", task))
else:
    raise TimeoutError(f"本地等待超时，任务可能仍在执行：{task_id}")
```

## 列表与删除

```bash
curl "$BASE_URL/v2/query/video_generation?page_num=1&page_size=20&filter.model=MiniMax-H3&filter.status=succeeded" \
  -H "Authorization: Bearer $API_KEY"
```

查询最近 7 天的任务。使用 `page_num` / `page_size` 分页，本网关默认第 1 页、每页 10 条；页码范围 1–10000，每页 1–100 条。支持 `filter.status`、重复的 `filter.task_ids`（最多 100 个）、`filter.model`、`filter.task_type`。本模型的 `filter.task_type` 为 `generation`。返回 `items` 数组和符合条件的 `total`。

```bash
curl -X DELETE "$BASE_URL/v2/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

已成功、失败或已取消的记录可以删除；允许删除已取消记录是本服务扩展。删除只隐藏公开记录，不重复退款。正在运行的任务不能删除。排队任务的取消只有在上游确认可取消时才能成功；该接口无法确认取消时返回错误，原任务仍有效，也不会提前退款。不能把客户端停止轮询当作任务取消。

## 回调

设置 `callback_url` 后，网关先发送包含 `challenge` 的验证请求；回调服务须在 3 秒内以 HTTP 200 返回同值的 JSON `challenge`（也接受纯文本同值）。验证成功后通知任务终态，正文与查询接口的 `{"task":{...}}` 格式一致，并附带 `X-MiniMax-Task-Id` 请求头。终态通知收到任意 2xx 即视为送达，最多尝试 5 次，失败后的等待间隔依次为 1、2、4、8 分钟；可能重复投递，请按任务 ID 和终态幂等消费。查询接口仍是状态和最终结果的依据。

与官方所有状态变化的推送不同，本实现不承诺每个排队/运行中间状态都有回调。禁止把 API Key 放进回调 URL。

## 素材

媒体 HTTP(S) URL 必须能由服务端直接读取。可以先使用本站已有的 `POST /v1/files/upload` 获取临时 URL，再填入 `image_url.url` / `audio_url.url` / `video_url.url`。图片和音频也可使用标准 `data:<mime>;base64,...`，服务校验后转为临时 URL；不接受裸 Base64、本机路径或浏览器 `blob:` URL。大文件建议先上传。

```bash
curl "$BASE_URL/v1/files/upload" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'file=@/path/to/person.png'
```

```json
{"url":"https://example.com/temporary-person.png","file_type":"image","size":3490,"expires_in":86400}
```

上传为 `multipart/form-data`，字段名 `file`；通用上传限制单文件不超过 50 MB，临时 URL 约 24 小时有效。上传成功不代表素材已满足生成模型的全部约束。

参考视频每条应为 2–15 秒；按 24 FPS 解码后必须为 48–360 帧，起始偏移后的素材也须满足此范围。这约束输入参考视频，不限制带驱动音频的输出时长。使用兼容的常见格式：图片 JPEG/PNG/WebP、音频 MP3/WAV、视频 MP4。实际解码和媒体约束由上游工作流检查；无法读取或解析的素材会使请求或任务失败。不要把其他 MiniMax 官方模型的最大尺寸/文件大小保证直接套用到此 服务。

## 错误

HTTP 错误使用 MiniMax V2 风格的外层 envelope，`http_code` 为字符串：

```json
{
  "type":"error",
  "error":{"type":"bad_request_error","message":"invalid request parameters","http_code":"400"},
  "request_id":"request_example"
}
```

参数错误应修正后再提交；401 检查本站 API Key，402 检查额度，429 按响应提示退避，5xx 先查询已有任务。任务自身失败出现在 HTTP 200 的 `task.error` 中，与请求失败的 envelope 不同。

## 官方协议参考

- [创建视频任务](https://platform.minimax.io/docs/api-reference/video-generation-v2-create)
- [查询任务](https://platform.minimax.io/docs/api-reference/video-generation-v2-query)
- [任务列表](https://platform.minimax.io/docs/api-reference/video-generation-v2-list)
- [取消或删除任务](https://platform.minimax.io/docs/api-reference/video-generation-v2-delete)

这些链接用于核对协议；实际可调用范围以本页的能力、参数和扩展说明为准。