minimax · 生成
提交异步视频任务;任务查询路径和响应格式因模型而异。
/v1/video/generations查看候选模型 ID
没有符合条件的模型。请调整筛选或重置。
| 模型 ID | 厂商 | 类型 | 说明 | 上下文窗口 | 最大输出 Token | 媒体规格 | 价格 | 状态 |
|---|---|---|---|---|---|---|---|---|
MiniMax-H3 | minimax | 视频 | 通过 content 文本项创建视频任务;图片与多模态输入格式见 H3 官方参考。 | — | — | 查看规格型号: 生成方式:文生视频、图生视频、视频编辑;时长:4–15 秒(整数,H3 官方规格);分辨率:768P / 2K(H3 官方规格);音频生成:支持;宽高比:文生视频:21:9、16:9、4:3、1:1、3:4、9:16 | 查看价格型号: $0.0689 币种:USD;计价单位:秒起;页面折扣:9.5折;资料日期:2026-09-28 登录页面参考价 登录模型广场展示价,含页面折扣;以当前账户价格和账单为准。 | — |
按公开标签归类,并补充模型广场资料;— 表示暂无明确资料。左右滑动查看完整表格。
Headers请求头
左右滑动查看完整参数表
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
Authorization | string | 必填 | 平台 API Key,使用 Bearer 认证。 | |
Content-Type | string | 必填 | 请求体编码格式。 |
Request Body请求体
application/json左右滑动查看完整参数表
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
model | string | 必填 | 平台模型 ID,大小写需完全一致。此页仅说明 MiniMax-H3。 可选值 MiniMax-H3 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
content | array | 必填 | 输入内容数组。每次请求必须包含一个非空 text 项;纯文本场景只含一个 text 项。图片、视频、音频为官方多模态参考,平台组合支持见补充说明。 | — | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | string | 必填 | 内容项类型,决定填写 text 或同名媒体对象。 可选值 textimage_urlvideo_urlaudio_url | — | ||||||||||
text | string | 可选 | 条件必填:type=text 时必填,且不能为空,最长 7000 字符。媒体项不填写 text;每个请求必须包含一个文本项。 | — | ||||||||||
image_url | object | 可选 | 条件必填:type=image_url 时提供同名对象;不能直接填写字符串。 | — | ||||||||||
| ||||||||||||||
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
url | string | 必填 | 该媒体对象中的素材地址。平台映射待确认;官方格式和限制见折叠补充。 | — |
video_url条件必填:type=video_url 时提供同名对象;不能直接填写字符串。
content[].video_url 的子字段 1
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
url | string | 必填 | 该媒体对象中的素材地址。平台映射待确认;官方格式和限制见折叠补充。 | — |
audio_url条件必填:type=audio_url 时提供同名对象;不能直接填写字符串。
content[].audio_url 的子字段 1
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
url | string | 必填 | 该媒体对象中的素材地址。平台映射待确认;官方格式和限制见折叠补充。 | — |
role媒体用途。单张首帧图片可省略并默认为 first_frame;首尾帧分别填写 first_frame、last_frame;参考素材填写对应 reference_*。首尾帧与参考场景互斥。
first_framelast_framereference_imagereference_videoreference_audioresolutionH3 输出分辨率,保留官方大写写法;最终尺寸以生成文件为准。
768P2Kduration生成时长(秒),必填,取整数 4–15。
ratio条件必填:纯文本 content 仅含 text 时必填具体比例,不能使用 adaptive。官方图生视频按图片自适应,传入其他比例也按 adaptive 处理;参考生视频可省略并默认 adaptive,也可指定具体比例。
adaptive21:916:94:31:13:49:16使用说明
- 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 判断视频完成。
查看创建与查询响应字段
左右滑动查看完整参数表
| 字段 | 类型 | 说明 |
|---|---|---|
| 创建:id / task_id | string | 返回的任务 ID。保存 task_id,后续只查询此任务。 |
| 创建:object / model | string | 对象类型 video 与模型 MiniMax-H3。 |
| 创建:status / progress | string / number | 受理响应为 queued、0,表示已排队,尚未生成完成。 |
| 创建:created_at | integer | 创建时间,Unix 秒级时间戳。 |
| 查询:code / message | string | 查询请求的业务状态与说明;code=success 不等于视频已经生成成功。 |
| 查询:data.task_id | string | 所查询任务的 ID。 |
| 查询:data.status | string | 任务状态,例如 NOT_START、IN_PROGRESS、SUCCESS。SUCCESS 表示生成成功。 |
| 查询:data.progress | string | 百分比进度,例如 100%;与创建响应的数字类型不同。 |
| 查询:data.fail_reason | string | 任务失败原因;成功时可为空字符串。 |
| 查询:data.result_url | string | 成功后的视频下载地址,及时下载或转存。此地址不需要携带平台 Authorization。 |
| 查询:data.submit_time / start_time / finish_time | integer | 提交、开始与结束的 Unix 秒级时间戳;未开始或未结束时可为 0。 |
| 查询:data.data.task | object | 返回中保留的 H3 原生任务对象;平台解析优先使用外层 data.status / data.result_url。 |
| 查询:data.data.task.resolution / duration / ratio | string / integer / string | 原生返回的分辨率档位、秒数与比例,例如 2K、5、16:9;最终媒体规格以文件为准。 |
| 查询:data.data.task.usage | object | 原生用量字段,包含 total_seconds、output_seconds、total_tokens 等;费用以平台账户账单为准。 |
响应示例保留字段结构;任务 ID、账户信息与视频地址已替换为占位值。
MiniMax-H3 官方多模态参数与限制
以下依据官方创建文档整理,仅说明 MiniMax-H3 的原生格式。图片、多模态输入、原生媒体地址形式和可选回调的平台映射待确认。
content 输入组合
每次请求须包含一个非空 type=text 项,text 最长 7000 字符。以下仅为 content JSON 参数片段,不含模型、接口地址或鉴权,不能直接作为完整平台请求。https://example.com/… 是需替换的公开素材地址占位符。
首帧图片
{
"content": [
{
"type": "text",
"text": "镜头缓慢推进,保持主体外观一致。"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/first-frame.png"
},
"role": "first_frame"
}
]
}首尾帧图片
{
"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"
}
]
}多模态参考
{
"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,也可指定具体比例。
官方输入媒体限制
左右滑动查看完整参数表
| 输入 | 格式 | 限制 |
|---|---|---|
| 图片 image_url | JPG / 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_url | string | 可选 | 官方原生任务状态回调地址。服务端先发送含 challenge 的验证请求,需在 3 秒内原样返回;验证后 POST 状态更新,正文结构与官方查询响应一致。平台回调映射待确认。 | — |
aigc_watermark | boolean | 可选 | 官方原生 AIGC 标识水印开关。平台透传规则待确认。 |
任务与响应范围
官方原生创建返回 task_id,查询返回 task 包装;官方成功视频地址为 task.content.url,状态为 queued / running / succeeded / failed / cancelled。平台查询包装在 data 中,读取 data.status 与 data.result_url。
官方查询仅支持近 7 天任务;这一原生保留期不代表平台的结果保留政策。视频地址可能有时效,完成后及时下载或转存。
创建、轮询与获取结果
创建请求只提交一次,并立即保存响应中的任务 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 -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()