MiniMax H3 Max

MiniMax H3 Max 是高速视频生成模型，支持纯文本 T2V 和首/尾帧 I2V。通过标准异步任务接口可生成 5–15 秒的 480p 或 768p 视频。

模型与端点

使用模型名 minimax-h3-max 调用：

POST https://api.aivideoapi.ai/v1/videos/generations

计费

只按生成的输出视频计费，输入图片免费。

分辨率	价格
`480p`	12.7 积分/秒
`768p`	19.23 积分/秒

5 秒 480p 请求消耗 5 × 12.7 = 63.5 积分；5 秒 768p 请求消耗 5 × 19.23 = 96.15 积分。文生视频和图生视频价格相同，输入图片不会增加费用。

提交前会预扣积分。已确认失败的任务只退款一次。如果请求可能已被生成服务接收，但没有取得权威响应，任务会保持 pending 并保留预扣积分等待核对，避免错误退款。

请求体

字段	类型	必填	说明
`model`	string	是	固定为 `minimax-h3-max`
`input`	object	是	下表中的生成参数
`callback_url`	string	否	接收任务完成或失败回调

Input 参数

字段	类型	必填	说明
`prompt`	string	是	非空提示词，最长 7000 字符
`generation_type`	string	否	省略时为文生视频；图生视频使用 `first_and_last_frames`
`image_urls`	string[]	条件必填	文生视频时忽略；首尾帧模式需要 1–2 个公网 HTTP(S) 图片 URL
`resolution`	string	否	`480p` 或 `768p`，默认 `768p`
`duration`	integer	否	5–15 秒，默认 `5`
`aspect_ratio`	string	否	文生视频使用固定比例；首尾帧模式始终跟随输入图片
`watermark`	boolean	否	是否添加 AIGC 水印，默认 `false`

不支持 video_urls、audio_urls、omni_reference、2k 和 4 秒时长。

生成模式

纯文本 T2V

省略 generation_type。支持 21:9、16:9、4:3、1:1、3:4 和 9:16，默认 16:9；纯文本模式不接受 adaptive。

省略 generation_type 时，即使传入 image_urls，也可以包含任意数量的字符串项，但所有图片都会被忽略：不校验、不下载、不转存、不发送给生成服务，也不参与计费。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-max",
    "input": {
      "prompt": "高速电影感跟拍镜头穿过夜晚霓虹城市",
      "resolution": "768p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

首/尾帧 I2V

将 generation_type 设为 first_and_last_frames。传 1 张图时作为首帧，传 2 张图时分别作为首帧和尾帧。输出比例始终由图片决定，因此任何其他合法 aspect_ratio 都会被忽略并归一化为 adaptive。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-max",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "镜头向前推进，日光逐渐照亮房间",
      "generation_type": "first_and_last_frames",
      "image_urls": [
        "https://example.com/first.png",
        "https://example.com/last.png"
      ],
      "resolution": "480p",
      "duration": 8
    }
  }'

首尾帧图片必须使用公网 HTTP(S) URL。上游素材限制为 JPG、JPEG、PNG、WEBP、HEIC 或 HEIF；单文件不超过 30 MB；宽高均为 256–5760 像素；宽高比为 0.4–2.5。

创建响应

创建成功后返回平台任务 ID。保存 data.taskId，用于后续查询任务：

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1"
  }
}

查询任务

使用创建响应中的 taskId 查询任务：

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态流转为 pending → processing → completed 或 failed。

等待提交

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "pending",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "estimated_seconds": 300
}

生成中

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "processing",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "progress": null
}

已完成

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-max",
  "credits_consumed": 96.15,
  "created_at": 1788066000,
  "completed_at": 1788066120,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/08/30/example.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Max",
      "resolution": "768p",
      "duration": 5,
      "ratio": "16:9"
    }
  },
  "usage": {
    "total_seconds": 5,
    "input_seconds": 0,
    "output_seconds": 5,
    "input_image_count": 0
  }
}

output.urls 包含生成的视频地址。usage 仅在生成服务返回用量数据时出现；其中的输入用量不会增加 H3 Max 的用户积分费用。

已失败

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

credits_consumed 表示任务最终实际消耗的积分。任务处理期间以及已确认失败并退款后，该字段为 0；已完成任务显示实际消耗积分。已确认失败的任务只退款一次。

GET /v1/tasks/{taskId} 是任务状态的权威来源。本模型不支持取消任务。

成功任务可能包含 usage.total_seconds、usage.input_seconds、usage.output_seconds 和 usage.input_image_count。这些字段只表示媒体用量；用户积分始终只按请求的输出时长和分辨率计算，不收取输入图片费用。

回调 (Callback)

创建任务时传入 callback_url，平台会在任务进入 completed 或 failed 终态时，向该地址发送 POST 请求：

{
  "model": "minimax-h3-max",
  "callback_url": "https://your-server.com/webhook",
  "input": {
    "prompt": "高速电影感跟拍镜头穿过夜晚霓虹城市",
    "resolution": "768p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }
}

请求头

Header	说明
`Content-Type`	`application/json`
`X-Event`	`task.completed` 或 `task.failed`
`X-Task-Id`	平台任务 ID
`X-Timestamp`	Unix 时间戳（秒）

完成回调

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-max",
  "credits_consumed": 96.15,
  "created_at": 1788066000,
  "completed_at": 1788066120,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/08/30/example.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Max",
      "resolution": "768p",
      "duration": 5,
      "ratio": "16:9"
    }
  },
  "usage": {
    "total_seconds": 5,
    "input_seconds": 0,
    "output_seconds": 5,
    "input_image_count": 0
  }
}

失败回调

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "minimax-h3-max",
  "credits_consumed": 0,
  "created_at": 1788066000,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

回调 body 与查询任务接口的对应终态响应一致。接收端应返回任意 2xx 状态码确认成功；如果地址不可达或返回非 2xx，平台会最多投递 3 次：首次立即发送，失败后约 3 分钟和 10 分钟重试。

即使所有回调均失败，也可以继续使用 GET /v1/tasks/{taskId} 查询最终状态。更多请求头和重试说明参见回调指南。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。