MiniMax H3 · MiniMax 格式

创建视频生成任务

提交视频生成任务，立即返回任务 ID，之后用任务 ID 查询结果。请求参数和返回结果与 MiniMax「创建视频生成任务」（视频生成 V2）接口一致。

POSThttps://your-domain/minimax/v2/video_generation

请求示例

curl https://your-domain/minimax/v2/video_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾"}],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9"
  }'

返回结果

{
  "task_id": "video_8f3k2m9x4q1w7e5r0t6y2u4p"
}

请求参数

请求体是 JSON，不超过 64 MB。不认识的参数会被忽略，值为 null 的参数视同不传。

请求体

modelstring必填

模型 ID：MiniMax-H3 或 MiniMax-H3-Max，可用的模型见模型与价格。这个接口只能调用 MiniMax 的模型，其他模型请用OpenAI 格式。

contentobject[]必填

输入给模型的文本和素材，1 到 100 项，其中至少要有一项非空的 text（提示词）。支持以下组合：

只有文本：文生视频；
文本 + 首帧图片：图生视频；
文本 + 尾帧图片，或者首帧 + 尾帧图片：首尾帧；
文本 + 参考图、参考视频、参考音频的任意组合：多模态参考。

首帧、尾帧和参考素材不能混用。各模型支持的生成方式和参考素材的数量上限见模型与价格。

content 的元素

typestring必填

内容类型：text（文本）、image_url（图片）、video_url（视频）或 audio_url（音频）。

textstring

type 为 text 时必填，描述想要生成的视频。有多个 text 时按顺序换行拼接，合计不超过 7000 字。

image_urlobject

type 为 image_url 时必填，写成 {"url": "..."}。url 可以是：

图片的公网链接（http 或 https），不超过 4096 个字符；
Base64 编码，格式为 data:image/<图片格式>;base64,<Base64 编码>，例如 data:image/png;base64,...，单张不超过 10 MB。

支持 jpg、jpeg、png、webp、heic、heif，单张不超过 30 MB。不支持 MiniMax 文件的 mm_file://。

video_urlobject

type 为 video_url 时必填，写成 {"url": "..."}。url 是视频的公网链接（http 或 https），平台会读取视频时长用于计费，所以链接必须能公开下载；不支持 Base64。

每个视频 2 秒以上，最多 3 个，总时长不超过 15 秒。

audio_urlobject

type 为 audio_url 时必填，写成 {"url": "..."}。url 可以是音频的公网链接，或 data:audio/<音频格式>;base64,<Base64 编码>，例如 data:audio/wav;base64,...。

支持 mp3、wav，单个不超过 15 MB，最多 3 个。

rolestring

素材的用途：

图片：first_frame（首帧）、last_frame（尾帧）或 reference_image（参考图）。只有一张图片时可以不填，按首帧处理；有多张图片时每张都要填。
视频：reference_video，可以不填。
音频：reference_audio，可以不填。

resolutionstring

视频分辨率：480P、768P 或 2K，大小写都可以。不传时使用模型的默认分辨率，各模型支持的分辨率见模型与价格。

durationinteger

视频时长，单位秒，需为正整数。不传时使用模型的默认时长，各模型支持的时长见模型与价格。MiniMax 的模型不支持由模型决定时长。

ratiostring

视频宽高比：16:9、9:16、1:1、4:3、3:4 或 21:9。不同生成方式的规则：

文生视频：不传时按模型的默认画幅（16:9）生成。
图生视频、首尾帧：画幅跟随图片，这个参数不生效。
多模态参考：不传时由模型根据素材决定，也可以指定画幅。

extraobject

附加参数，只能包含 prompt_expansion_mode，有其他字段时返回 400。

子字段

prompt_expansion_modestring

提示词优化方式：disabled（不优化）、balanced 或 quality，含义和 MiniMax 相同。不传时按 MiniMax 的默认方式处理。

callback_urlstring

回调地址，http 或 https 链接，不超过 1024 个字符。平台先验证这个地址，通过后任务状态每次变化都会推送任务信息，见回调通知。

aigc_watermarkboolean默认值 false

是否在视频里添加 AIGC 水印。

返回参数

task_idstring

任务 ID，以 video_ 开头。用它查询任务或取消任务。

参数有误、余额不足等情况下，接口直接返回错误，不会创建任务，也不扣费，见错误码。

请求示例

文生视频见右侧的请求示例，下面是其他生成方式的写法。

图生视频

content 里放一张 role 为 first_frame 的图片，视频的画幅跟随图片。

图生视频

curl https://your-domain/minimax/v2/video_generation \
  -H "Authorization: Bearer $MINIMAX_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-frame.png"},
        "role": "first_frame"
      }
    ],
    "resolution": "768P",
    "duration": 6
  }'

使用本地图片

本地图片转成 Base64 编码后放在 url 里，单张不超过 10 MB：

Python

import base64
import os

import requests

with open("first-frame.png", "rb") as f:
    data_url = "data:image/png;base64," + base64.b64encode(f.read()).decode()

body = {
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "女孩抬头看向镜头，微笑着挥手，微风吹起她的头发"}],
    "resolution": "768P",
    "duration": 6
}
body["content"].append({"type": "image_url", "image_url": {"url": data_url}, "role": "first_frame"})

resp = requests.post(
    "https://your-domain/minimax/v2/video_generation",
    headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
    json=body,
)
print(resp.json())

首尾帧

放两张图片，role 分别为 first_frame 和 last_frame。也可以只放一张 last_frame，生成以这张图片结尾的视频。

首尾帧

curl https://your-domain/minimax/v2/video_generation \
  -H "Authorization: Bearer $MINIMAX_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-frame.png"},
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/last-frame.png"},
        "role": "last_frame"
      }
    ],
    "resolution": "768P",
    "duration": 6
  }'

多模态参考

参考图、参考视频和参考音频可以任意组合。只有模型与价格里生成方式有「参考生成」的模型能用，其他模型返回 400（2013）。带参考视频的任务改用「带参考视频」单价，参考视频的时长也计入费用，见计费规则。

多模态参考

curl https://your-domain/minimax/v2/video_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "女孩穿着参考图里的外套在街头行走，镜头运动和参考视频一致，配上参考音频的背景音乐"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/girl.png"},
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/coat.png"},
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {"url": "https://example.com/camera-move.mp4"},
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {"url": "https://example.com/bgm.mp3"},
        "role": "reference_audio"
      }
    ],
    "resolution": "768P",
    "duration": 10,
    "ratio": "16:9"
  }'

提示词优化和水印

用 extra.prompt_expansion_mode 选择提示词优化方式，aigc_watermark 传 true 时视频带 AIGC 水印。

提示词优化和水印

curl https://your-domain/minimax/v2/video_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾"}],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "extra": {"prompt_expansion_mode": "quality"},
    "aigc_watermark": true
  }'

回调通知

创建任务时传了 callback_url，平台按 MiniMax 的方式回调：

验证地址：第一次推送前，平台向回调地址 POST {"challenge": "..."}，回调地址要在 3 秒内返回 HTTP 2xx 和 {"challenge": "<收到的值>"}。验证不通过时，这个任务不再回调。
推送状态：验证通过后，任务状态每次变化，平台都会 POST {"task": {...}}，task 和查询任务返回的 task 相同。

创建带回调的任务

curl https://your-domain/minimax/v2/video_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾"}],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "callback_url": "https://example.com/minimax/callback"
  }'

status	什么时候推送
`queued`	任务提交成功，开始排队
`running`	开始生成
`succeeded`	生成成功，content.url 是视频地址
`failed`	生成失败或超时，error 是失败原因
`cancelled`	任务被取消

推送要在 5 秒内返回 2xx 状态码，否则算发送失败。succeeded、failed、cancelled 发送失败时会再发两次，每次间隔 5 秒；queued、running 只发一次。
回调地址要能从公网访问，内网地址收不到回调。
同一状态可能收到不止一次，请按任务 ID 和 status 去重。没有收到回调时，可以用查询接口确认任务状态。

回调服务示例（Python Flask）

from flask import Flask, request

app = Flask(__name__)


@app.post("/minimax/callback")
def minimax_callback():
    data = request.get_json()
    # 第一次推送前先验证地址：3 秒内原样返回 challenge
    if "challenge" in data:
        return {"challenge": data["challenge"]}

    task = data["task"]
    print(task["id"], task["status"])
    if task["status"] == "succeeded":
        print(task["content"]["url"])
    return {"ok": True}

推送的请求体（任务成功时）

{
  "task": {
    "id": "video_8f3k2m9x4q1w7e5r0t6y2u4p",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1791691200,
    "updated_at": 1791691352,
    "content": {
      "url": "https://your-domain/uploads/videos/2026/10/k3Zq8mVt2LxR9pWa.mp4"
    },
    "resolution": "768P",
    "duration": 6,
    "usage": {
      "input_image_count": 0,
      "input_seconds": 0,
      "output_seconds": 6,
      "total_seconds": 6
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}