视频生成 2K Ultra HD 原生有声音频 4~15 秒任意时长

MiniMax H3 (海螺视频生成大模型)

MiniMax 海螺 H3 是新一代全形态一体化视频大模型：文生视频、首尾帧连续生视频、参考生视频、以及多模态全能参考（参考图 + 参考视频 + 参考音频任意组合）一个模型全包，直接输出最高 2K 分辨率的高清有声视频。

全形态一体接入

无需调用多个不同接口，通过单一统一模型标识 minimax-h3 即可灵活切换文生、首尾帧或全模态参考。

原生音画协同生成

直接生成带有匹配音效与环境声轨的高清视频，可上传参考音频驱动节奏与意境氛围。

接入准备与请求规范

使用所有接口均需携带 Authorization 认证头与指定网关地址。

主网关 Base URL 默认推荐

https://ai.lingyuai.top

统一请求头 (Headers)

请求头	类型	必选	示例值 / 格式说明
Authorization	String	必填	`Bearer YOUR_API_KEY` 或使用 `x-api-key: YOUR_API_KEY`
Content-Type	String	必填 (POST)	`application/json`

计费规则与扣费保障

MiniMax H3 模型按秒计费、下单即扣清，包含任务失败自动退款兜底机制

SEC

按秒计费模式

根据请求参数设定的 duration (4~15秒) 精确按秒扣费。任务成功创建即冻结相应扣费，无需等待长时间结算。

RES

分辨率档位系数

768P 为高性价比档位，出片最快；2K 超高清直出单价约为 768P 的 1.6 倍。若包含参考视频，输入秒数也按该档位单价计入。

BACK

失败自动全额退款

任何原因导致任务到达 failed 终态时，平台立即自动全额退回扣减额度（返回体中 refunded: true），无资产损失风险。

素材费用说明：参考音频输入完全免费，不计入时长或费用；参考视频（2~15秒）将按其自身视频时长与所选分辨率单价计费。

POST /v1/videos

创建 MiniMax H3 视频生成异步任务 (New API 规范)

异步生成

向该接口提交生成参数与素材，调用成功后会立即返回任务标识 id（或 task_id）。随后可通过状态查询接口 GET /v1/videos/{task-id} 轮询直至终态。

请求体示例 (JSON Body)

{
  "model": "minimax-h3",
  "prompt": "湖面波光粼粼，一只白鹭缓缓掠过水面，镜头向前平稳推拉，电影质感光影",
  "params": {
    "mode": "shouweizhen",
    "duration": "5",
    "resolution": "768P",
    "aspect_ratio": "16:9",
    "images": [
      "https://example.com/start_frame.jpg"
    ]
  }
}

创建任务响应 (Response 200 OK - New API 规范)

{
  "id": "123456",
  "object": "video",
  "model": "minimax-h3",
  "status": "queued",
  "created": 1776412800,
  "task_id": "123456"
}

GET /v1/videos/{task-id}

轮询查询视频生成任务状态与结果 (New API 标准端点)

查询端点说明：

1. New API 标准端点：GET /v1/videos/{task-id}（路径参数传入任务 ID，返回标准视频任务状态及输出结果）。

2. 建议轮询间隔：建议每 3~5 秒 查询一次。视频任务通常需要 30 秒至 2 分钟完成。

状态轮询返回示例 (任务成功终态 - New API 规范)

{
  "id": "123456",
  "object": "video",
  "model": "minimax-h3",
  "status": "succeeded",
  "progress": 100,
  "created": 1776412800,
  "finished_at": 1776412845,
  "video_url": "https://cos.lingkeai.vip/outputs/2026/video_123456.mp4",
  "data": [
    {
      "url": "https://cos.lingkeai.vip/outputs/2026/video_123456.mp4"
    }
  ],
  "state": "succeed",
  "is_final": true
}

请求参数详细说明 (Request Parameters)

POST /v1/videos 请求体的参数规格对照表

1. 顶层参数 (Top-Level)

参数名	类型	必选	说明
model	string	必填	模型标识，固定填入 `minimax-h3`（或 `MiniMax-H3`）。
prompt	string	必填	提示词，描述画面主体、镜头运动、光影、氛围及动作细节。建议包含具体的镜头运镜指令。
params	object	必填	模型专用参数对象，详见下表。

2. params 对象详细字段

字段名	类型	必选	可选值 / 默认值	详细说明
mode	enum	可选	`shouweizhen` `cankaosheng`	生成模式： • `shouweizhen`（首尾帧）：上传 1~2 张图分别做首帧/尾帧； • `cankaosheng`（参考生）：上传参考图、参考视频、参考音频； • 若不填且未传素材，自动执行文生视频。
duration	string / int	必填	`"4"` ~ `"15"` (秒)	视频生成时长，支持 4 到 15 秒之间的整数秒。按秒计费。
resolution	enum	必填	`768P` / `1080P` / `2K` / `4K`	输出分辨率： • `768P`：性价比高，出片速度快； • `2K`：超高清直出，单价更高（约为 768P 的 1.6 倍）。
aspect_ratio	enum	可选	`adaptive` (默认) `16:9`, `9:16`, `1:1` `4:3`, `3:4`, `21:9`	画面宽高比。`adaptive` 为自适应，由传入的参考素材自动计算最匹配的画幅比例。
images	array[string]	可选	最多 2 张 URL	首尾帧图片：仅适用于 `mode="shouweizhen"`。第 1 张为首帧，第 2 张为尾帧。单张 ≤ 20MB。
image_url	array[string]	可选	0 ~ 9 张 URL	参考生模式图片：仅适用于 `mode="cankaosheng"`。支持多张主体/风格参考图，模型将融合主体特征。
video_url	array[string]	可选	0 ~ 3 个 URL	参考生模式视频：参考动作/运镜。时长 2~15 秒，按参考视频时长额外按秒计费。
audio_url	array[string]	可选	0 ~ 3 段 URL	参考生模式音频：时长 ≤15s。音频输入免费，仅作节奏风格参考，成片由模型原生生成声轨。

3. 素材上传限制与格式标准

图片限制 (Images)

• 支持格式：jpg, jpeg, png, webp
• 单文件体积：≤ 20 MB
• 分辨率限制：最小边 ≥ 300 px
• 宽高比区间：0.4 ~ 2.5 之间

参考视频 (Video)

• 支持格式：mp4, mov
• 单文件体积：≤ 50 MB
• 时长限制：2 ~ 15 秒
• 帧率区间：23.976 ~ 60 fps
• 音轨编码：aac, mp3

参考音频 (Audio)

• 支持格式：wav, mp3, m4a
• 单文件体积：≤ 20 MB
• 时长限制：最长 ≤ 15 秒
• 费用：免费（不收取额外 token/秒费）

多语言代码调用示例

支持纯文本生成、首尾帧过渡、多模态参考生等多样化场景

cURL 示例

生成成功响应示例 (Response 200 OK - completed)

状态：status=completed / progress=100

{
  "completed_at": 1792163966,
  "created_at": 1792163684,
  "id": "task_Iuxg5rgRkLPGolW6TkHHGALeXqcMJ2u2",
  "model": "MiniMax-H3",
  "object": "video",
  "progress": 100,
  "status": "completed",
  "url": "https://tos.lingkeai.vip/uploads/2026.10/16/20261016231914_18df0b9f03fe05d520df.mp4",
  "video_url": "https://tos.lingkeai.vip/uploads/2026.10/16/20261016231914_18df0b9f03fe05d520df.mp4"
}

任务生命周期与状态定义

轮询响应中的 state 字段枚举及是否属于终态（is_final）对照

状态标识 (state)	状态名称	终态 (is_final)	业务含义与处理建议
pending	等待中	false	任务已创建，等待系统分发。继续保持轮询。
queued	排队中	false	GPU 算力队列排队中。继续保持轮询。
processing	生成中	false	视频正在渲染中，通常消耗 30~90 秒。继续保持轮询。
succeed	生成成功	true	最终成功状态。从 `video_url` 读取成片永久下载地址，终止轮询。
failed	生成失败	true	任务失败，系统自动回滚额度（`refunded=true`），从 `fail_reason` 查看具体错误原因。终止轮询。

常见 HTTP 异常状态码与排障对照表

HTTP 状态	错误类型 (type)	常见触发原因	排查与解决方案
400	invalid_request_error	素材尺寸或格式不合规（如宽高比超出 0.4~2.5 区间、单图>20MB、duration 不在 4~15s 内）。	核对参数规格；确保图片最小边 ≥ 300px，视频为 2~15s MP4/MOV。
401	authentication_error	缺少 Authorization 头，或 API Key 格式错误、已被停用。	请求头中填入 `Bearer sk-xxx` 或使用 `x-api-key: sk-xxx`。
402	insufficient_balance	账户剩余额度不足以支付预扣款（时长 × 分辨率秒费）。	请前往平台控制台充值后再重试。
429	rate_limit_exceeded	并发请求数超限或 QPS 超过分配频次。	增加指数退避重试（Backoff），或降低轮询频率至 3~5 秒。
500	api_error	GPU 算力集群瞬时负载波动或网络抖动。	系统已自动退款，可直接发起重试。

在线请求体生成器 & 调试配置

选择参数即时生成完整 JSON 请求体及 cURL 命令，方便直接拷贝测试

API Key 模拟演示模式

输入您的有效 API Key 即可直接发起真实在线视频生成调试；留空则进入全流程模拟演示。

接口 Base URL

提示词 (Prompt)

生成模式 (mode)

视频时长 (duration)

分辨率 (resolution)

宽高比 (aspect_ratio)

首尾帧图片 URL (最多2张，每行一个)