MiniMax H3 API 对接文档

适用服务：知梦视频平台当前部署。核对日期：2026-09-10。本文可独立交给外部开发者，调用凭证使用平台发放的 API Key。

这是一份本站接口文档。请使用下列模型名、字段和路径，不要套用其他平台的同名模型示例。文中的素材域名和任务 ID 均为占位示例，需要替换。

1. 接入地址与鉴权

当前接入地址：https://movie.zmoapi.cn

操作	方法与路径	返回内容
创建视频	`POST /v1/videos`	任务 JSON，异步生成
查询任务	`GET /v1/videos/{task_id}`	任务状态及成片 URL
获取成片文件	`GET /v1/videos/{task_id}/content`	视频二进制，须先完成

请求头：

http

Authorization: Bearer YOUR_PLATFORM_API_KEY
Content-Type: application/json

Content-Type 用于提交 JSON；查询和下载无需请求体。
使用平台 API Key，不使用站点登录密码、管理访问令牌或上游密钥。
当前模型分组为 聚合视频；令牌须可用、有足够额度，并允许 minimax-h3 模型及对应分组。
只需普通 Bearer 鉴权；客户端无需设置 New-Api-User、X-Video-Studio 等工作台或管理字段。
BASE_URL 在本文中不包含 /v1，拼接路径时不要变成 /v1/v1/videos。
当前提供的是 HTTP IP 入口；正式接入如需 HTTPS，应使用平台另行确认的 HTTPS 地址，不要自行猜测域名或直接把协议改成 HTTPS。
Key 放在调用方服务端环境变量，前端通过自己的后端调用，避免将 Key 打包到网页或 App 静态资源。

2. 参考素材如何提交

标准流程：调用方上传素材到自己的图床/对象存储 → 获取文件直链 → 将 URL 放进创建请求 → 平台把原 URL 转发给上游。

本站不会把 URL 形式的参考素材重新上传到本站图床或上游。需要区分以下读取行为：

素材	外部 API 收到 URL 后的处理
图片	转发原 URL；当前 API 适配层不下载图片
视频	平台先下载并检查真实格式、时长、尺寸、帧率，用于校验和参考视频计费；随后仍转发原 URL，不重新上传
音频	当前外部 API 适配层转发原 URL；工作台另有音频下载和时长预检，不能把该预检视为外部 API 的保证

参考视频本地预检最多 3 段，共用约 90 秒处理超时。大文件、慢图床、不可访问链接会延长提交响应时间或造成校验失败。

2.1 URL 要求

使用可直接获取原文件的 HTTP/HTTPS URL；优先 HTTPS。
不能使用本机路径、localhost、私网地址、blob: URL、网页分享页或需要登录的链接。
上游要能独立访问 URL；参考视频还必须能被本站服务器访问。仅开发者自己的浏览器能打开并不够。
视频链接需要可直接 GET 得到正常文件；避免登录跳转、防盗链拦截、返回 HTML 的伪直链。
使用签名 URL 时，要覆盖排队、生成和可能重试读取的全过程；建议预留至少 1 小时，并按自身最长等待时间延长。
素材链接的有效期由调用方存储服务决定，和本站成片保留期是两回事。
多次读取同一个 URL 时应返回同一份文件；不要在任务执行中覆盖原文件。

2.2 素材数量与格式

下表给出对接应遵守的能力范围。不要依赖某个入口暂未校验的宽松行为。

素材	对接限制与建议
图片	多参考最多 9 张；首尾帧模式最多 2 张。本站工作台单图上传上限 15 MiB，外部 URL 接口不做同样的本地大小探测；建议按该范围准备素材
视频	最多 3 段；单段 2–15 秒，合计不超过 15 秒；每个文件不超过 50 MiB
视频容器/编码	MP4 或 MOV；H.264 或 H.265；只含一个视频画面轨道
视频尺寸	宽、高各 256–5760 像素，宽高比 0.4–2.5
视频帧率	23.976–60 fps；文件的轨道、帧数、时长元数据须正常
音频	按最多 3 段、单文件 30 MiB、音频合计不超过 15 秒准备；工作台支持 MP3/WAV/M4A/AAC/OGG/FLAC。外部 API 应自行预检这些约束，上游仍可能进一步校验

视频时长按文件实际元数据检查、计费，不能通过自报一个较短时长来覆盖。不要利用边界容差提交超过文档范围的素材。

2.3 不要将工作台上传接口当成公共 API

以下路径是工作台登录会话接口，需要 Cookie，普通视频 API Key 不能直接调用：

/api/video-studio/upload
/api/video-studio/upload-video
/api/video-studio/upload-audio
/api/video-studio/tasks

外部开发者按本文先准备 URL，再调用 /v1/videos。当前 /v1/files 上传未实现，不要假设存在统一文件上传或上传后换取 file_id 的流程。

3. 创建请求参数

推荐使用 JSON，明确填写生成模式、时长、分辨率和画幅。

字段	类型	含义与注意事项
`model`	string	固定 `minimax-h3`
`prompt`	string	视频提示词，非空
`duration`	integer	生成时长，4–15 秒；公开 API 省略时默认 4 秒
`resolution`	string	`768P` 或 `2K`；省略或为空时默认 2K，可能比预期贵
`aspect_ratio`	string	建议显式填写：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`
`generation_mode`	string	`frames`：文生/首尾帧；`references`：多参考
`image_urls`	array of string	按顺序排列的图片直链
`video_urls`	array of string	参考视频直链；请配合 `references`
`audio_urls`	array of string	参考音频直链；请配合 `references`

使用 frames 时，第一张图是起始帧，第二张图是结束帧；纯文生可不传任何素材。使用 references 时，图片均作为参考图片，并可与视频、音频组合；按标准用法至少提供一项素材。

兼容字段说明：

时长兼容 seconds，但推荐只传整数 duration，不要同时传冲突值。
ratio 优先于 aspect_ratio；推荐只传一种画幅字段。省略画幅时会根据内容选择自适应或 16:9。
分辨率还识别 size、output_resolution、size_tier，但这些字段必须一致；有冲突会报错。推荐只传 resolution。
不要把像素尺寸当作通用分辨率值；最稳妥的规范值是 768P 和 2K。
外部 API 请准确写 references。工作台兼容的 multi、multi_reference 不应照搬到外部 API。

3.1 最低档纯文生示例

将以下内容保存为 minimax-text.json：

json

{
  "model": "minimax-h3",
  "generation_mode": "frames",
  "prompt": "清晨，一片绿色树叶上的露珠缓缓滑落，背景是柔和虚化的花园，镜头固定，写实风格。",
  "duration": 4,
  "resolution": "768P",
  "aspect_ratio": "16:9"
}

以下命令假定已在服务端设置环境变量 VIDEO_API_KEY：

bash

BASE_URL="https://movie.zmoapi.cn"
curl --fail-with-body --silent --show-error --max-time 180 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @minimax-text.json \
  --output minimax-create-response.json

提交成功后立即保存响应中的 id，兼容读取 task_id。保存返回的完整 task_...，后续查询和下载始终使用该 ID。

3.2 起始帧与结束帧示例

json

{
  "model": "minimax-h3",
  "generation_mode": "frames",
  "prompt": "镜头平稳运动，让画面自然地从起始状态过渡到结束状态。",
  "duration": 4,
  "resolution": "768P",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://media.example.com/start.jpg",
    "https://media.example.com/end.jpg"
  ]
}

只有起始帧时保留数组第一项。不要在首尾帧请求中混入参考视频。

3.3 图片、视频、音频多参考示例

json

{
  "model": "minimax-h3",
  "generation_mode": "references",
  "prompt": "结合参考图片的环境、参考视频的动作节奏和参考音频的氛围，生成自然连贯的场景。",
  "duration": 4,
  "resolution": "768P",
  "aspect_ratio": "16:9",
  "image_urls": ["https://media.example.com/scene.jpg"],
  "video_urls": ["https://media.example.com/motion.mp4"],
  "audio_urls": ["https://media.example.com/mood.mp3"]
}

上面是结构示例，必须替换为真实可达、符合限制的素材，不能直接使用示例域名。

3.4 关于高级 `content` 写法

本站也支持由调用方直接组织非空 content 数组。但只要提交非空 content，适配器就不再用外层 prompt、image_urls、video_urls、audio_urls 构造上游内容。

不要混用两种写法。 本文统一推荐前面的简化字段。使用 content 时，必须自行在其中完整提供文本和素材及角色，否则可能出现“传了图片但没有生效”或缺少文本的问题。

4. 创建响应、查询与状态

创建成功通常为 HTTP 200，直接返回任务对象，没有工作台的 success / data 外壳。以下为仅保留关键字段的示意：

json

{
  "id": "task_EXAMPLE",
  "task_id": "task_EXAMPLE",
  "status": "queued",
  "progress": 0
}

创建响应的初始状态、进度可能保留上游格式。收到任务 ID 后，以后续 GET 查询判断最终结果，不要求 POST 响应必须立即包含成片 URL。

bash

TASK_ID="task_EXAMPLE"
curl --fail-with-body --silent --show-error --max-time 60 \
  "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $VIDEO_API_KEY"

查询状态	处理方式
`queued`	已排队，继续查询
`in_progress`	生成中，继续查询
`completed`	完成，读取成片 URL，并验证文件可获取
`failed`	终态失败，记录错误信息，停止轮询
缺失或未识别的状态	保留完整响应，稍后查询；不能直接判成功

建议每 10–20 秒查询一次，遇到 429/临时网络或 5xx 错误退避重试 GET。进度可能停留较久，不是精确完成时间；不要仅凭 progress=100 判定成功，失败任务也可能显示 100。

已完成任务的真实公开 API 响应具有以下结构（ID、地址已替换）：

json

{
  "id": "task_EXAMPLE",
  "object": "",
  "model": "MiniMax-H3",
  "status": "completed",
  "progress": 100,
  "content": {"url": "https://media.example.com/result.mp4"},
  "task_id": "task_EXAMPLE",
  "url": "https://media.example.com/result.mp4",
  "result_url": "https://media.example.com/result.mp4",
  "video_url": "https://media.example.com/result.mp4",
  "media_url": "https://media.example.com/result.mp4",
  "output": ["https://media.example.com/result.mp4"]
}

注意：返回模型名可能是 MiniMax-H3，object 可能为空；不要用它们与提交值严格相等作为成功条件。建议依次读取 result_url、video_url、content.url、url、media_url、output[0]。链接也可能是本站相对路径，需要结合 BASE_URL 解析。

4.1 Python 轮询示例：仅查询既有任务，不重复创建

保存为 poll_minimax.py，然后运行 python3 poll_minimax.py task_实际任务ID。使用 Python 标准库，无需安装依赖。

python

import json
import os
import sys
import time
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urljoin
from urllib.request import Request, urlopen

base = os.environ.get("VIDEO_BASE_URL", "https://movie.zmoapi.cn").rstrip("/")
api_key = os.environ["VIDEO_API_KEY"]
task_id = sys.argv[1]
deadline = time.monotonic() + 30 * 60
status_url = base + "/v1/videos/" + quote(task_id, safe="")

while time.monotonic() < deadline:
    request = Request(status_url, headers={"Authorization": "Bearer " + api_key})
    try:
        with urlopen(request, timeout=60) as response:
            task = json.load(response)
    except HTTPError as error:
        if error.code == 429 or 500 <= error.code < 600:
            time.sleep(20)
            continue
        raise RuntimeError(f"查询失败 HTTP {error.code}: " + error.read().decode(errors="replace"))
    except (URLError, TimeoutError):
        time.sleep(20)
        continue

    status = str(task.get("status", "")).lower()
    print(task_id, status, task.get("progress"), flush=True)
    if status == "failed":
        raise RuntimeError("任务失败：" + json.dumps(task.get("error") or task, ensure_ascii=False))
    if status == "completed":
        content = task.get("content") or {}
        content_url = content.get("url") if isinstance(content, dict) else None
        output = task.get("output") or []
        output_url = output[0] if isinstance(output, list) and output else None
        result_url = (task.get("result_url") or task.get("video_url") or content_url
                      or task.get("url") or task.get("media_url") or output_url)
        if isinstance(result_url, str) and result_url:
            print("成片地址：", urljoin(base + "/", result_url))
            break
        # 已完成但 URL 暂缺：继续查询，不重新提交生成。
    time.sleep(15)
else:
    raise TimeoutError("本地等待已结束，任务状态仍待确认；请保存任务 ID，稍后继续查询，勿自动重发 POST。")

这里 30 分钟是示例客户端的等待上限，不是服务保证、任务取消或失败判定。

5. 成片获取与有效期

推荐完成后立即通过成片 URL 保存到调用方自己的存储；也可使用本站文件接口：

bash

curl --fail --silent --show-error --max-time 180 \
  "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $VIDEO_API_KEY" \
  --output minimax-result.mp4

文件接口返回视频二进制，不要当 JSON 解析。失败时检查 HTTP 状态和错误响应。
直接访问外部成片 URL 时，不要附带平台 API Key；平台 Key 只发给本站 API。
成片生成后，本站会将输出视频转存到文件服务，当前保留约 1 小时。这和输入参考素材“不重新上传”是两条独立流程。
任务状态仍为完成，不代表成片链接永久有效；API 也不一定返回 expires_at。拿到链接就及时保存。
工作台创建的任务有“最多 3 次代理下载”限制，即使通过 /v1/videos/{id}/content 下载同一工作台任务，也会计次。
纯 API 创建的任务不套用工作台的 3 次计数限制，但成片一小时保留期仍然有效。
当前主流程按轮询查询。不要假设存在未说明的回调、取消、删除或重新生成接口。

6. 计费与退款

以下是核对日期当前站内 CNY 售价，按默认分组系数 1 说明；后续配置变化以平台账单为准，不代表上游成本或上游余额。

项目	768P	2K
生成视频	¥0.13 / 生成秒	¥0.20 / 生成秒
参考视频附加费	¥0.09 / 参考视频实际秒	¥0.15 / 参考视频实际秒
图片附加费	前 5 张不收图片附加费；第 6–9 张每张 ¥0.05 / 次	同左

当前实现没有单列参考音频附加费。不要将“前 5 张图片免费”理解为整个生成任务免费。

默认分组下：

text

总费用 = 生成时长 × 生成秒价
       + 所有参考视频实际时长之和 × 参考秒价
       + max(图片数量 - 5, 0) × 0.05

示例：生成 4 秒 768P、带 6 秒参考视频和 7 张图片：4 × 0.13 + 6 × 0.09 + 2 × 0.05 = ¥1.16。

参考视频按检测出的实际小数秒数计费，不是先向上取整到整数秒。图片附加费按次收取，不再乘生成时长。客户端估价需保留足够精度，最终以平台账单结算为准。

若账户分组系数不是 1，当前实现仅对基础生成费乘分组系数；图片和参考视频附加费另加，不再乘该系数。平台最终会换算为内部额度最小单位，客户端金额显示应避免过早舍入。

提交时会预扣费用；后台确认任务失败后走退款流程。客户端请求超时、断网或关闭页面，不等于任务失败，也不等于已退费。 不要因为提交响应超时就直接重新 POST，否则可能创建并计费两条任务。

7. 常见问题与坑

现象/错误	原因与处理
费用比预计高	最先检查是否忘了传 `resolution`，默认是 2K；其次检查参考视频和额外图片附加费
`resolution fields conflict`	同时填写了不一致的 `resolution/size/output_resolution/size_tier`；仅保留一致的规范值
提示参考视频不能与起始帧/结束帧混用	使用了图片+视频，却没明确设置 `generation_mode: "references"`
传了素材却没生效	检查是否同时传了非空 `content`，导致简化字段被忽略；也检查 URL 是否真正可达
提示无法读取参考视频	本站会真实下载做预检；检查公网可达性、HTTP 状态、图床响应速度和 50 MiB 限制
视频明明能播放却校验失败	播放器可能宽容，接口还会校验容器、H.264/H.265、单画面轨、帧率、尺寸与时长元数据
401/403 或令牌相关错误	检查 Bearer Key、Key 状态/有效期、IP 限制、模型权限、分组及额度
无可用渠道/模型不可用	先核对 `minimax-h3` 模型名与 `聚合视频` 分组；若一致，将错误和任务/请求 ID 交平台排查
HTTP 200 但没有视频链接	可能只是创建成功，先保存 ID 并轮询；还要检查 `error` 和状态
查询完成但下载失败	检查成片是否过期；若在有效期内仍失败，保留任务 ID 和错误响应，勿直接重生成
文件接口 400/404	可能尚未完成，或任务不存在/不属于当前 Key 所属账户；先核对 ID 和任务状态
文件接口 410/429	工作台任务可能过期或下载次数耗尽；普通 429 也可能是限流，须结合错误体判断
重复收费	不要对创建 POST 使用无条件自动重试；有任务 ID 就恢复 GET 轮询

记录调用时间、任务 ID、HTTP 状态、错误体及响应中可用的请求 ID，有助于排查。不要在日志或报错截图中包含 API Key。

8. 本次验证范围

2026-09-10 已完成一次经工作台进入同一视频 API 转发链路的纯文生测试：4 秒、768P，生成成功并实际播放。站内扣费 ¥0.52；文件实际约 4.46 秒、1344×768，生成耗时约 44 秒。

另已使用 API Bearer 令牌只读验证该任务的 GET /v1/videos/{id} 响应。这里的成功耗时仅为一次样本，不是 SLA；生成文件实际时长/尺寸也可能与请求标签存在容器时长或画幅适配差异。

本文参考素材结构、模式、校验和附加费用依据当前线上代码核对；没有将图片、视频、音频多参考组合逐项重新做付费生成测试。正式接入应先用少量合规素材验证自身图床可达性和所需组合。

MiniMax H3 API 对接文档 ​

1. 接入地址与鉴权 ​

2. 参考素材如何提交 ​

2.1 URL 要求 ​

2.2 素材数量与格式 ​

2.3 不要将工作台上传接口当成公共 API ​

3. 创建请求参数 ​

3.1 最低档纯文生示例 ​

3.2 起始帧与结束帧示例 ​

3.3 图片、视频、音频多参考示例 ​

3.4 关于高级 content 写法 ​

4. 创建响应、查询与状态 ​

4.1 Python 轮询示例：仅查询既有任务，不重复创建 ​

5. 成片获取与有效期 ​

6. 计费与退款 ​

7. 常见问题与坑 ​

8. 本次验证范围 ​

MiniMax H3 API 对接文档

1. 接入地址与鉴权

2. 参考素材如何提交

2.1 URL 要求

2.2 素材数量与格式

2.3 不要将工作台上传接口当成公共 API

3. 创建请求参数

3.1 最低档纯文生示例

3.2 起始帧与结束帧示例

3.3 图片、视频、音频多参考示例

3.4 关于高级 `content` 写法

4. 创建响应、查询与状态

4.1 Python 轮询示例：仅查询既有任务，不重复创建

5. 成片获取与有效期

6. 计费与退款

7. 常见问题与坑

8. 本次验证范围