MiniMax H3 Fast

MiniMax H3 Fast 是原生多模态视频模型，支持文生视频、首尾帧视频，以及使用图片、视频和音频的多模态参考生成。通过 AI Video API 的统一异步任务接口，支持生成 5–15 秒的 480p 视频。

模型

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

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

计费

仅按请求的输出视频秒数收费。输入图片、参考视频和参考音频全部免费，第 6–9 张参考图片也不额外收费。

分辨率	输出视频	输入素材
`480p`	11.68 积分/秒	免费

仅开放 480p，默认分辨率也是 480p。

请求体

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

Input 参数

字段	类型	必填	说明
`prompt`	string	是	非空视频提示词，最长 7000 字符
`generation_type`	string	否	`omni_reference`（默认）或 `first_and_last_frames`
`image_urls`	string[]	否	公网 HTTP(S) 图片 URL；参考模式最多 9 张，首尾帧模式 1–2 张
`video_urls`	string[]	否	最多 3 个公网 MP4/MOV URL；每段 2–15 秒，合计不超过 15 秒
`audio_urls`	string[]	否	最多 3 个公网 MP3/WAV URL；每段 2–15 秒，合计不超过 15 秒，且不可作为唯一参考素材
`resolution`	string	否	仅支持 `480p`，也是默认值
`duration`	integer	否	支持输出 5–15 秒，默认 `5`；API 时长规则见下文
`aspect_ratio`	string	否	`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；文生默认 `16:9`，参考默认 `adaptive`
`watermark`	boolean	否	是否添加 MiniMax AIGC 水印，默认 `false`

本接口只接受公网 HTTP(S) 素材 URL，不支持 mm_file:// 和 Data URI。

参数约束

宽高比 `aspect_ratio`

公开参数 aspect_ratio 会映射到 MiniMax 上游的 ratio。可用值为 adaptive、21:9、16:9、4:3、1:1、3:4、9:16，但不同生成模式的规则不同：

生成场景	如何识别	是否必填	约束
文生视频	不传 `image_urls`、`video_urls`、`audio_urls`	否	默认 `16:9`，可使用固定比例 `21:9`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`；不能使用 `adaptive`
首尾帧视频	`generation_type=first_and_last_frames`	否	始终按 `adaptive` 处理，输出比例由输入图片决定；即使传入其他合法比例也会被忽略
多模态参考视频	`omni_reference` 且至少包含一种参考素材	否	默认 `adaptive`，也可以显式指定任一固定比例

文生视频省略 aspect_ratio 时使用 16:9；显式传入 adaptive 会返回参数错误。

生成模式与素材组合

每个请求都必须包含非空 prompt，按字符计数，最长 7000 个字符。
duration 必须是正整数。文档支持范围和 Playground 控件范围为 5–15 秒；API 会将任意正整数原值透传，包括 4 或 16，不限制或截断至该区间。超出支持范围能否生成，以生成服务的实际结果为准；估价使用相同的请求时长。
first_and_last_frames 必须提供 1–2 张图片：image_urls[0] 为首帧，存在时 image_urls[1] 为尾帧；不能同时提供视频或音频。
omni_reference 最多支持 9 张参考图片、3 个参考视频和 3 个参考音频。
音频不能作为唯一参考素材；使用 audio_urls 时，必须同时提供至少一张图片或一个视频。
首尾帧模式与多模态参考模式互斥，不能在同一请求中混用首尾帧、参考视频或参考音频。
resolution 仅支持 480p，默认也是 480p。watermark 必须是布尔值，默认 false。

输入媒体限制

以下文件属性由 MiniMax 上游校验；本平台会先校验 URL、数量及参考视频时长。素材不符合上游要求时，任务可能在提交时被拒绝或进入失败状态。

素材	格式与编码	单文件大小	尺寸与比例	数量与时长
图片	JPG、JPEG、PNG、WEBP、HEIC、HEIF	≤ 30 MB	宽高均为 256–5760 px；宽/高为 0.4–2.5	首帧最多 1 张、尾帧最多 1 张；参考图最多 9 张
视频	MP4、MOV；视频编码 H.264/AVC 或 H.265/HEVC；音频编码 AAC 或 MP3	≤ 50 MB	宽高均为 256–5760 px；宽/高为 0.4–2.5；帧率 23.976–60 fps	最多 3 个；每段 2–15 秒，合计不超过 15 秒
音频	WAV、MP3	≤ 15 MB	—	最多 3 个；每段 2–15 秒，合计不超过 15 秒

MiniMax 上游请求体上限为 64 MB。本平台不接受 Base64，因此请使用无需登录、无防盗链且 MiniMax 服务可直接访问的公网 URL。Playground 上传器当前接受 JPG、PNG 和 WEBP；通过 API URL 传入的其他官方图片格式仍需满足上表限制。

生成模式

文生视频

不传任何媒体数组即可。宽高比默认 16:9；纯文生视频不能使用 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-fast",
    "input": {
      "prompt": "史诗级太空歌剧预告，女舰长望着最后一支舰队跃迁离去",
      "resolution": "480p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

首尾帧视频

将 generation_type 设为 first_and_last_frames。image_urls[0] 是首帧，可选的 image_urls[1] 是尾帧。该模式不能混用视频或音频参考，输出比例跟随输入帧图片。

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-fast",
    "input": {
      "prompt": "镜头缓缓向前推进，晨光逐渐照亮整个房间",
      "generation_type": "first_and_last_frames",
      "image_urls": [
        "https://example.com/first.png",
        "https://example.com/last.png"
      ],
      "resolution": "480p",
      "duration": 5
    }
  }'

多模态参考视频

使用 omni_reference 组合参考图片、视频和音频。音频必须同时配合至少一张参考图片或一个参考视频。不传 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-fast",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "角色使用参考音色说：随风而行，自由生活",
      "generation_type": "omni_reference",
      "image_urls": ["https://example.com/character.png"],
      "video_urls": ["https://example.com/motion.mp4"],
      "audio_urls": ["https://example.com/voice.mp3"],
      "resolution": "480p",
      "duration": 5,
      "aspect_ratio": "adaptive"
    }
  }'

任务生命周期

创建接口返回平台任务 ID：

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

查询任务：

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

状态流转为 pending → processing → completed 或 failed。成功结果使用统一的 output.urls 数组。生成已成功但结果尚在交付时，任务会继续保持 processing，请继续轮询。

任务成功后，如果生成服务提供用量数据，响应顶层的 usage 字段会返回媒体用量：

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "completed",
  "credits_consumed": 175.20,
  "model": "minimax-h3-fast",
  "created_at": 1785685446,
  "completed_at": 1785685956,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/08/02/output_aigc.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Fast",
      "resolution": "480p",
      "duration": 15,
      "ratio": "16:9",
      "task_type": "generation"
    }
  },
  "usage": {
    "total_seconds": 15,
    "input_seconds": 0,
    "output_seconds": 15,
    "input_image_count": 0
  }
}

用量字段	类型	说明
`usage.total_seconds`	number	MiniMax 上报的媒体总秒数
`usage.input_seconds`	number	MiniMax 处理的输入参考视频秒数
`usage.output_seconds`	number	生成的输出视频秒数
`usage.input_image_count`	number	处理的输入图片数量

usage 在任务成功且有用量数据时返回，任务查询响应和 task.completed 完成回调保持一致。该对象仅提供媒体用量信息，输入秒数和图片数量不会追加费用。credits_consumed 为最终用户扣费金额；任务处理中，以及确认失败且退款后，该值为 0。默认账户倍率下，成功的 15 秒请求为 175.20 积分。

回调

创建任务时传入 callback_url，即可接收 task.completed 或 task.failed 通知。回调正文与对应的终态任务查询响应一致，有公开用量时也包含 usage。请返回 2xx 确认接收；回调交付失败时可通过 GET /v1/tasks/{taskId} 获取状态。请求头和重试规则见回调指南。

创建带回调的任务

向 POST /v1/videos/generations 提交以下请求体，任务完成或失败时，平台会向 callback_url 发送 POST 请求：

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

请求头

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

完成回调示例

X-Event: task.completed，以下为默认账户倍率下，5 秒视频生成成功的回调正文：

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "completed",
  "model": "minimax-h3-fast",
  "credits_consumed": 58.40,
  "created_at": 1789171200,
  "completed_at": 1789171320,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/09/12/example.mp4"
    ],
    "metadata": {
      "model": "MiniMax-H3-Fast",
      "resolution": "480p",
      "duration": 5,
      "ratio": "16:9",
      "task_type": "generation"
    }
  },
  "usage": {
    "total_seconds": 5,
    "input_seconds": 0,
    "output_seconds": 5,
    "input_image_count": 0
  }
}

失败回调示例

X-Event: task.failed，回调正文示例：

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "failed",
  "model": "minimax-h3-fast",
  "credits_consumed": 0,
  "created_at": 1789171200,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

回调可能重复送达，请按任务 id 幂等处理。

常见错误码

请求失败时，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 服务返回错误，可能原因：

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

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