minimax · 生成

提交异步视频任务;任务查询路径和响应格式因模型而异。

POST/v1/video/generations

异步任务

查看候选模型 ID
模型 ID厂商类型说明上下文窗口最大输出 Token媒体规格价格状态
MiniMax-H3
minimax视频通过 content 文本项创建视频任务;图片与多模态输入格式见 H3 官方参考。——
查看规格

型号:MiniMax-H3

生成方式:文生视频、图生视频、视频编辑;时长:4–15 秒(整数,H3 官方规格);分辨率:768P / 2K(H3 官方规格);音频生成:支持;宽高比:文生视频:21:9、16:9、4:3、1:1、3:4、9:16

查看价格

型号:MiniMax-H3

$0.0689

币种:USD;计价单位:秒起;页面折扣:9.5折;资料日期:2026-09-28

登录页面参考价

登录模型广场展示价,含页面折扣;以当前账户价格和账单为准。

—

按公开标签归类,并补充模型广场资料;— 表示暂无明确资料。左右滑动查看完整表格。

进阶用法与完整流程 · 参数与透传

生成效果示例

Headers请求头

左右滑动查看完整参数表

请求头
参数名类型必填说明默认值 / 示例
Authorizationstring必填

平台 API Key,使用 Bearer 认证。

示例
Bearer YOUR_API_KEY
Content-Typestring必填

请求体编码格式。

示例
application/json

Request Body请求体

application/json

左右滑动查看完整参数表

请求体
参数名类型必填说明默认值 / 示例
modelstring必填

平台模型 ID,大小写需完全一致。此页仅说明 MiniMax-H3。

可选值MiniMax-H3
示例
MiniMax-H3
contentarray必填

输入内容数组。每次请求必须包含一个非空 text 项;纯文本场景只含一个 text 项。图片、视频、音频为官方多模态参考,平台组合支持见补充说明。

—
content[] 的子字段 6
content[] 子字段
参数名类型必填说明默认值 / 示例
typestring必填

内容项类型,决定填写 text 或同名媒体对象。

可选值textimage_urlvideo_urlaudio_url
—
textstring可选

条件必填:type=text 时必填,且不能为空,最长 7000 字符。媒体项不填写 text;每个请求必须包含一个文本项。

—
image_urlobject可选

条件必填:type=image_url 时提供同名对象;不能直接填写字符串。

—
content[].image_url 的子字段 1
content[].image_url 子字段
参数名类型必填说明默认值 / 示例
urlstring必填

该媒体对象中的素材地址。平台映射待确认;官方格式和限制见折叠补充。

—
video_urlobject可选

条件必填:type=video_url 时提供同名对象;不能直接填写字符串。

—
content[].video_url 的子字段 1
content[].video_url 子字段
参数名类型必填说明默认值 / 示例
urlstring必填

该媒体对象中的素材地址。平台映射待确认;官方格式和限制见折叠补充。

—
audio_urlobject可选

条件必填:type=audio_url 时提供同名对象;不能直接填写字符串。

—
content[].audio_url 的子字段 1
content[].audio_url 子字段
参数名类型必填说明默认值 / 示例
urlstring必填

该媒体对象中的素材地址。平台映射待确认;官方格式和限制见折叠补充。

—
rolestring可选

媒体用途。单张首帧图片可省略并默认为 first_frame;首尾帧分别填写 first_frame、last_frame;参考素材填写对应 reference_*。首尾帧与参考场景互斥。

可选值first_framelast_framereference_imagereference_videoreference_audio
—
resolutionstring必填

H3 输出分辨率,保留官方大写写法;最终尺寸以生成文件为准。

可选值768P2K
示例
2K
durationinteger必填

生成时长(秒),必填,取整数 4–15。

示例
5
ratiostring可选

条件必填:纯文本 content 仅含 text 时必填具体比例,不能使用 adaptive。官方图生视频按图片自适应,传入其他比例也按 adaptive 处理;参考生视频可省略并默认 adaptive,也可指定具体比例。

可选值adaptive21:916:94:31:13:49:16
示例
16:9

使用说明

  • MiniMax-H3 使用 content[].text 提供提示词,无需重复填写顶层 prompt;纯文本请求保留一个非空 text 项。
  • 文生视频 ratio 必填且不能为 adaptive;图生与参考生视频的官方条件见参数表和折叠补充。
  • 图片与多模态输入的官方格式见折叠补充;平台映射待确认。
  • 创建受理不等于生成完成。保存任务 ID,通过平台 GET /v1/video/generations/{task_id} 查询同一任务;以任务终态和生成文件核对结果,避免重复创建。
  • 平台查询读取 data.status 与 data.result_url;官方原生查询读取 task.status 与 task.content.url,两者不要混用。
  • 本页视频示例为 2560×1440、24 fps,带 AAC 音轨;请求及原生响应 duration=5,文件时长约 5.167 秒,最终时长以媒体文件为准。

平台任务响应

创建和查询使用不同的响应结构。查询同一个任务,确认 data.status=SUCCESS 后读取 data.result_url;不要只凭 HTTP 200 或 code=success 判断视频完成。

查看创建与查询响应字段

左右滑动查看完整参数表

H3 平台任务响应字段
字段类型说明
创建:id / task_idstring返回的任务 ID。保存 task_id,后续只查询此任务。
创建:object / modelstring对象类型 video 与模型 MiniMax-H3。
创建:status / progressstring / number受理响应为 queued、0,表示已排队,尚未生成完成。
创建:created_atinteger创建时间,Unix 秒级时间戳。
查询:code / messagestring查询请求的业务状态与说明;code=success 不等于视频已经生成成功。
查询:data.task_idstring所查询任务的 ID。
查询:data.statusstring任务状态,例如 NOT_START、IN_PROGRESS、SUCCESS。SUCCESS 表示生成成功。
查询:data.progressstring百分比进度,例如 100%;与创建响应的数字类型不同。
查询:data.fail_reasonstring任务失败原因;成功时可为空字符串。
查询:data.result_urlstring成功后的视频下载地址,及时下载或转存。此地址不需要携带平台 Authorization。
查询:data.submit_time / start_time / finish_timeinteger提交、开始与结束的 Unix 秒级时间戳;未开始或未结束时可为 0。
查询:data.data.taskobject返回中保留的 H3 原生任务对象;平台解析优先使用外层 data.status / data.result_url。
查询:data.data.task.resolution / duration / ratiostring / integer / string原生返回的分辨率档位、秒数与比例,例如 2K、5、16:9;最终媒体规格以文件为准。
查询:data.data.task.usageobject原生用量字段,包含 total_seconds、output_seconds、total_tokens 等;费用以平台账户账单为准。

响应示例保留字段结构;任务 ID、账户信息与视频地址已替换为占位值。

MiniMax-H3 官方多模态参数与限制

以下依据官方创建文档整理,仅说明 MiniMax-H3 的原生格式。图片、多模态输入、原生媒体地址形式和可选回调的平台映射待确认。

content 输入组合

每次请求须包含一个非空 type=text 项,text 最长 7000 字符。以下仅为 content JSON 参数片段,不含模型、接口地址或鉴权,不能直接作为完整平台请求。https://example.com/… 是需替换的公开素材地址占位符。

首帧图片

JSON · 官方 content 参数片段
{
  "content": [
    {
      "type": "text",
      "text": "镜头缓慢推进,保持主体外观一致。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first-frame.png"
      },
      "role": "first_frame"
    }
  ]
}

首尾帧图片

JSON · 官方 content 参数片段
{
  "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"
    }
  ]
}

多模态参考

JSON · 官方 content 参数片段
{
  "content": [
    {
      "type": "text",
      "text": "参考图片1的主体外观、视频1的动作和音频1的声音,生成连贯镜头。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference-image.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/reference-video.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/reference-audio.mp3"
      },
      "role": "reference_audio"
    }
  ]
}

组合与比例规则

  • 首帧/首尾帧与多模态参考互斥;first_frame/last_frame 不可与 reference_image/reference_video/reference_audio 混用。
  • 单张首帧图片的 role 可省略;首尾帧分别标记 first_frame 与 last_frame。参考素材使用对应的 reference_*。
  • 纯文本输入必须指定具体比例:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16,不能用 adaptive。首帧/首尾帧按输入图片自适应;参考生视频默认 adaptive,也可指定具体比例。

官方输入媒体限制

左右滑动查看完整参数表

MiniMax-H3 官方媒体规格
输入格式限制
图片 image_urlJPG / JPEG / PNG / WEBP / HEIC / HEIF单张 ≤30 MB;首帧 ≤1、尾帧 ≤1、参考图 ≤9;宽高各 256–5760 px;宽高比 0.4–2.5。
视频 video_url(仅参考场景)MP4 / MOV;视频 H.264/AVC、H.265/HEVC;音频 AAC、MP3单段 ≤50 MB;≤3 段;每段 2–15 秒,合计 ≤15 秒;宽高各 256–5760 px;宽高比 0.4–2.5;23.976–60 FPS。
音频 audio_url(仅参考场景)WAV / MP3单段 ≤15 MB;≤3 段;每段 2–15 秒,合计 ≤15 秒。

总请求体 ≤64 MB,大文件优先使用公开 URL。官方原生媒体对象的 url 支持公网 URL、mm_file://{file_id} 或对应模态的 Base64 Data URI;这些原生地址形式不代表平台已支持文件映射或 Base64 透传。

官方可选字段

左右滑动查看完整参数表

官方原生可选字段
参数名类型必填说明默认值 / 示例
callback_urlstring可选

官方原生任务状态回调地址。服务端先发送含 challenge 的验证请求,需在 3 秒内原样返回;验证后 POST 状态更新,正文结构与官方查询响应一致。平台回调映射待确认。

—
aigc_watermarkboolean可选

官方原生 AIGC 标识水印开关。平台透传规则待确认。

默认值
false

任务与响应范围

官方原生创建返回 task_id,查询返回 task 包装;官方成功视频地址为 task.content.url,状态为 queued / running / succeeded / failed / cancelled。平台查询包装在 data 中,读取 data.status 与 data.result_url。

官方查询仅支持近 7 天任务;这一原生保留期不代表平台的结果保留政策。视频地址可能有时效,完成后及时下载或转存。

核对日期:2026-10-28。官方创建参数 · 官方任务查询

创建、轮询与获取结果

创建请求只提交一次,并立即保存响应中的任务 ID。以下示例先等待 3 秒,再按 5、10、30 秒的间隔查询,之后保持 30 秒间隔;轮询预算为 600 秒。这些数值是客户端示例策略,不是平台频率限制或生成时长承诺。超时后保留任务 ID,后续继续查询同一任务。HTTP 错误、失败、取消及未知状态会停止本轮轮询。

阶段可能的响应位置处理方式
排队status=queued;data.status=NOT_START;output.task_status=PENDING继续查询已有任务
处理中data.status=IN_PROGRESS;嵌套 status=running继续查询已有任务
成功data.status=SUCCESS;嵌套 status=succeeded / task_status=SUCCEEDED读取结果地址并下载
失败或取消FAILURE / failed / cancelled停止轮询,读取 fail_reason / error
结果地址result_url、content.video_url、output.video_url、task.content.url按返回的 HTTPS URL 下载

先把所选模型的完整 JSON 请求体保存为 video-request.json。模型的时长、分辨率、content 与 metadata 结构各不相同,按本页对应模型填写。查询成功的 code=success 不等于视频任务成功。

展开 Python:一次创建、有界轮询与保存视频
Python
# 安装依赖:python -m pip install requests
import json
import os
import tempfile
import time
from pathlib import Path
from urllib.parse import quote, urlsplit
import requests

BASE_URL = "https://ai.kedang.net"

def normalize_task(payload):
    """读取任务状态;HTTP 200 或 code=success 仅表示查询成功。"""
    if not isinstance(payload, dict):
        raise ValueError("任务响应必须为 JSON 对象")
    if payload.get("error"):
        return {"state": "failed", "url": "", "reason": str(payload["error"])}
    code = payload.get("code")
    if code is not None and str(code).lower() not in ("0", "200", "success", "ok"):
        raise RuntimeError(payload.get("message") or str(code))
    nodes, layer = [payload], [payload]
    for _ in range(5):
        children = []
        for node in layer:
            for key in ("data", "output", "task", "content"):
                if isinstance(node.get(key), dict):
                    children.append(node[key])
        nodes.extend(children)
        layer = children
    # 外层任务状态优先;未提供时再读取嵌套状态。
    raw = next((str(node.get("status") or node.get("task_status")).lower()
                for node in nodes if node.get("status") or node.get("task_status")), "")
    states = {
        "queued": "queued", "pending": "queued", "not_start": "queued", "submitted": "queued",
        "in_progress": "running", "running": "running", "processing": "running",
        "success": "succeeded", "succeeded": "succeeded", "completed": "succeeded",
        "failure": "failed", "failed": "failed", "fail": "failed", "error": "failed", "expired": "failed",
        "cancelled": "cancelled", "canceled": "cancelled",
    }
    url = next((node[key] for node in nodes for key in ("result_url", "video_url", "url")
                if isinstance(node.get(key), str) and node[key]), "")
    reason = next((str(node[key]) for node in nodes for key in ("fail_reason", "error", "message")
                   if node.get(key)), "")
    return {"state": states.get(raw, "unknown"), "url": url, "reason": reason}


def poll_task(task_id, fetch, sleep, monotonic, total_timeout=600):
    """3 / 5 / 10 / 30 秒间隔与 600 秒预算均为客户端示例策略。"""
    if not isinstance(task_id, str) or not task_id:
        raise ValueError("任务 ID 不能为空")
    if total_timeout <= 0:
        raise ValueError("轮询预算必须大于零")
    encoded_id = quote(task_id, safe="")
    deadline = monotonic() + total_timeout
    delays, attempt = (3, 5, 10, 30), 0
    while True:
        remaining = deadline - monotonic()
        if remaining <= 0:
            raise TimeoutError("轮询超时,保留此 ID 后续查询:" + task_id)
        sleep(min(delays[min(attempt, len(delays) - 1)], remaining))
        remaining = deadline - monotonic()
        if remaining <= 0:
            raise TimeoutError("轮询超时,保留此 ID 后续查询:" + task_id)
        payload = fetch(encoded_id, min(30, remaining))
        if monotonic() >= deadline:
            raise TimeoutError("轮询超时,保留此 ID 后续查询:" + task_id)
        task = normalize_task(payload)
        if task["state"] == "succeeded":
            return payload
        if task["state"] in ("failed", "cancelled"):
            raise RuntimeError("任务 " + task_id + ":" + task["state"] + " " + task["reason"])
        if task["state"] not in ("queued", "running"):
            raise RuntimeError("未知任务状态,请按任务 ID 检查响应:" + task_id)
        attempt += 1

def download_video(url, target, headers=None):
    parsed = urlsplit(url)
    if parsed.scheme != "https" or not parsed.netloc:
        raise ValueError("下载地址必须为有效 HTTPS URL")
    target = Path(target)
    temporary = None
    try:
        with requests.get(url, headers=headers or {}, stream=True, timeout=(10, 120)) as response:
            response.raise_for_status()
            mime = response.headers.get("Content-Type", "").split(";", 1)[0].lower()
            if mime and not (mime.startswith("video/") or mime == "application/octet-stream"):
                raise ValueError("下载响应不是视频或二进制文件")
            with tempfile.NamedTemporaryFile(dir=target.parent, delete=False) as file:
                temporary = Path(file.name)
                size = 0
                for chunk in response.iter_content(chunk_size=1024 * 1024):
                    if chunk:
                        file.write(chunk)
                        size += len(chunk)
            if size == 0:
                raise ValueError("下载内容为空")
        temporary.replace(target)
    finally:
        if temporary is not None:
            temporary.unlink(missing_ok=True)
    return target

def main():
    headers = {"Authorization": "Bearer " + os.environ["KEDANG_API_KEY"]}
    # 将所选模型的完整创建请求保存到此 JSON 文件,包含它要求的规格与扩展参数。
    body = json.loads(Path("video-request.json").read_text(encoding="utf-8"))
    if not body.get("model") or body["model"] == "MODEL_ID":
        raise ValueError("请在 video-request.json 中填写账户可用的模型与完整请求参数")
    # 创建只提交一次。网络超时时先核对任务记录,避免重复创建。
    created_response = requests.post(BASE_URL + "/v1/video/generations", headers=headers,
                                     json=body, timeout=(10, 120))
    created_response.raise_for_status()
    created = created_response.json()
    if created.get("error"):
        raise RuntimeError(created["error"])
    data = created.get("data") if isinstance(created.get("data"), dict) else {}
    task_id = created.get("task_id") or created.get("id") or data.get("task_id")
    if not isinstance(task_id, str) or not task_id:
        raise RuntimeError("响应没有任务 ID;保留提交记录,不自动重新创建。")
    Path("video-task-id.txt").write_text(task_id, encoding="utf-8")
    print("任务 ID:", task_id)

    def fetch(encoded_id, timeout):
        response = requests.get(BASE_URL + "/v1/video/generations/" + encoded_id,
                                headers=headers, timeout=timeout)
        response.raise_for_status()
        return response.json()

    result = poll_task(task_id, fetch, time.sleep, time.monotonic, total_timeout=600)
    url = normalize_task(result)["url"]
    if not url:
        raise RuntimeError("任务已成功但缺少结果地址;使用保存的任务 ID 查询。")
    # 返回的媒体 URL 可能在独立域名,下载时不发送平台 Authorization。
    print(download_video(url, "video.mp4"))

if __name__ == "__main__":
    main()