MiniMax H3 Text-to-Video API
minimax/h3/text-to-videoMiniMax H3 Text-to-Video 可根据提示词生成固定 2K 视频。描述主体、动作、镜头移动、光线和画面风格,再选择 5–15 秒时长及画面比例。
输入
输出
已就绪继续使用
REST API
快速开始
用三个步骤完成第一次调用。先运行短示例,确认接口返回 task_id,再获取生成的视频。
连接 Vidgo API
创建 API Key,将它安全保存在服务端,并通过 Authorization 请求头以 Bearer Token 发送。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer VIDGO_API_KEY
提交一个生成任务
选择一种语言并运行短示例。提交成功会立即返回 task_id,不会等待视频生成完成。
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "minimax/h3/text-to-video",
"input": {
"prompt": "一名骑行者穿过雨夜城市,镜头在她身旁平稳跟拍。",
"duration": 5,
"resolution": "2K",
"aspect_ratio": "16:9"
}
}'等待并获取结果
使用返回的 task_id 查询同一个任务,直到状态变为 finished 或 failed;成功后读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}当状态为 not_started 或 running 时,建议约每 2 秒轮询一次;到达 finished 或 failed 后停止。成功时从 data.files[].file_url 读取视频地址;长任务可逐步延长间隔,也可在提交请求顶层添加 callback_url 异步接收最终结果。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-08-22T10:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}完整可运行示例
理解上面的三步流程后再展开。这里把提交、轮询、终态处理和结果读取合并在一个脚本中。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "minimax/h3/text-to-video",
"input": {
"prompt": "一名骑行者穿过雨夜城市,镜头在她身旁平稳跟拍。",
"duration": 5,
"resolution": "2K",
"aspect_ratio": "16:9"
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数
model 与可选 callback_url 位于请求顶层,所有生成参数放入 input。接口会拒绝不支持的媒体字段;请勿传入下方未列出的字段。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | 必须为 minimax/h3/text-to-video。 |
| callback_url | string (URL) | 否 | — | 用于接收最终异步结果的公开 HTTP(S) 地址;使用轮询时可省略。 |
| input | object | 是 | — | 下方模型生成参数的容器。 |
| input.prompt | string | 是 | — | 去除首尾空白后为 1–2,000 个字符;不接受任何源素材字段。 |
| input.duration | integer | 否 | 5 | 生成时长,必须是 5–15 的整数秒。 |
| input.resolution | string | 否 | 2K | 固定输出分辨率,唯一可接受值为 2K。 |
| input.aspect_ratio | string | 否 | — | 可选 21:9、16:9、4:3、1:1、3:4 或 9:16,不接受 adaptive。 |
响应字段
提交响应会立即返回任务标识;随着任务推进,状态响应会补充进度、输出文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 应用层结果码,成功响应使用 0 或 200。 |
| message | string | 存在时返回便于阅读的响应或错误信息。 |
| data.task_id | string | 任务标识,用于拼接状态查询地址。 |
| data.status | string | 当前状态:not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间,采用日期时间格式。 |
| data.progress | number | 上游提供进度时返回的完成百分比。 |
| data.files[] | array | 任务成功后返回的生成文件列表。 |
| data.files[].file_url | string | 生成视频的公开访问地址。 |
| data.files[].file_type | string | 生成文件类型,例如 video。 |
| data.files[].watermark_url | string | null | 存在水印版本时返回对应地址。 |
| data.error_message | string | null | status 为 failed 时的失败详情。 |
任务生命周期
not_started 与 running 属于非终态;finished 与 failed 是两种终态,收到任意终态后都应停止轮询。
not_started任务已被接受,正在等待开始。
running视频正在生成,继续使用同一个 task_id 查询。
finished生成成功,从 data.files[].file_url 读取视频地址。
failed生成因错误终止,读取 data.error_message,不再继续轮询。
轮询与错误处理
- 认证失败401 表示 Bearer API Key 缺失或无效,修正凭证后再重试。
- 参数校验400 表示请求无效,应读取响应信息并修正对应字段。
- 轮询间隔初始建议约每 2 秒查询一次,长任务应逐步延长间隔。
- 终态处理仅在 not_started 或 running 时继续查询;遇到 finished 或 failed 立即停止。
- 回调方式提供 callback_url 可异步接收最终结果;否则使用状态查询接口。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 仅文本 | 提示词定义完整场景,不接受任何源媒体。 |
| 输出 | 视频 | MiniMax H3 Text-to-Video API 返回一个异步视频生成任务。 |
| 分辨率 | 2K | 分辨率固定,不会改变积分费率。 |
| 时长 | 5–15 秒 | 必须使用整数秒,默认值为 5 秒。 |
| 画面比例 | 6 种固定比例 | 支持 21:9、16:9、4:3、1:1、3:4 和 9:16,不接受 adaptive。 |
| 计费基础 | 每秒 21 积分 | 请求费用只取决于生成时长。 |
相关模型
MiniMax H3 文生视频 API 常见问题
什么是 MiniMax H3 Text-to-Video API?
MiniMax H3 Text-to-Video 是 MiniMax 推出的文字驱动视频生成模型。你只需在提示词中描述场景、动作和镜头运动,即可得到 5–15 秒整数时长的固定 2K 视频,适合无需源素材的概念镜头、广告与社交短片。
如何调用 MiniMax H3 Text-to-Video API?
使用 Bearer API Key 向 /api/generate/submit 发送 POST 请求,将 model 设为 minimax/h3/text-to-video,并把生成参数放入 input。接口会立即返回 task_id;API 页签提供可运行的 cURL、JavaScript 和 Python 示例,完整字段定义见 https://docs.vidgo.ai/api-manual/video-series/minimax-h3-text-to-video。
MiniMax H3 Text-to-Video 如何计费?
API 按生成时长计费,每秒消耗 21 积分。生成 5 秒、10 秒和 15 秒视频分别消耗 105、210 和 315 积分。提交前,运行按钮会显示按当前时长计算的美元价格。
MiniMax H3 Text-to-Video 接受哪些输入?
核心输入包括 prompt、duration、resolution 和 aspect_ratio。prompt 长度为 1–2,000 个字符,duration 可选 5–15 秒整数,resolution 固定为 2K,且 MiniMax H3 Text-to-Video API 不接受源媒体。上方参数表列出了字段要求、默认值和六种可用画面比例。
如何获取生成的视频?
使用返回的 task_id 轮询 GET /api/generate/status/{task_id},直到状态变为 finished 或 failed。任务完成后从 data.files[].file_url 读取视频地址;也可以在提交请求中加入 callback_url,异步接收最终结果。
应该选择哪个 MiniMax H3 API 模式?
场景完全由提示词定义时选择 Text-to-Video;需要首帧和可选尾帧时选择 Image-to-Video;需要多张图片、视频或音频共同引导时选择 Reference-to-Video。










