MiniMax H3 (Hailuo-03) API 接入文档

使用 VezAPI 密钥接入 MiniMax H3 (Hailuo-03)。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

MiniMax H3 图生视频

POST/api/v1/jobs/createTask

模型标识： minimax-h3/image-to-video

参数	类型	说明与限制
`model` 必填	`string`	生成任务的模型名称。用于 MiniMax H3 图生视频。可选值：`"minimax-h3/image-to-video"` 默认：`"minimax-h3/image-to-video"`
`callBackUrl` 可选	`string`	任务完成后的回调地址。
`input` 必填	`object`
`input.prompt` 必填	`string`	视频生成提示词，长度为 1 至 7000 个字符。 `minLength: 1` `maxLength: 7000`
`input.first_frame_url` 可选	`string`	首帧图片 URL。注意：首尾帧必须二选一。可公开访问的 HTTP(S) 地址；支持 JPG、JPEG、PNG、WEBP、HEIC、HEIF 格式；单张图片不超过 30 MB，图片边长需在 256 至 5760 像素之间，宽高比需在 0.4 至 2.5 之间。
`input.last_frame_url` 可选	`string`	尾帧图片 URL，可选，可单独传，图片限制同 first_frame_url。首帧、尾帧至少传一个。
`input.duration` 必填	`integer`	生成视频时长，支持 4 至 15 秒的整数值。可选值：`4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15` 默认：`6` `minimum: 4` `maximum: 15`
`input.resolution` 可选	`string`	视频分辨率。可选值：`"768P", "2K"` 默认：`"2K"`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-h3/image-to-video",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "Let the character in the scene turn around naturally and smile, camera slowly pushing forward",
    "first_frame_url": "https://example.com/input.png",
    "last_frame_url": "https://example.com/input.png",
    "duration": 6
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	Response message, error description upon failure
`data` 必填	`object`
`data.taskId` 必填	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

MiniMax H3 参考生视频

POST/api/v1/jobs/createTask

模型标识： minimax-h3/reference-to-video

参数	类型	说明与限制
`model` 必填	`string`	生成任务的模型名称。用于 MiniMax H3 参考生视频。可选值：`"minimax-h3/reference-to-video"` 默认：`"minimax-h3/reference-to-video"`
`callBackUrl` 可选	`string`	任务完成后的回调地址。
`input` 必填	`object`
`input.prompt` 必填	`string`	视频生成提示词，长度为 1 至 7000 个字符。 `minLength: 1` `maxLength: 7000`
`input.reference_image_urls` 可选	`array`	参考图片 URL 数组。最多支持 9 张。可公开访问的 HTTP(S) 地址；支持 JPG、JPEG、PNG、WEBP、HEIC、HEIF 格式；单张图片不超过 30 MB，图片边长需在 256 至 5760 像素之间，宽高比需在 0.4 至 2.5 之间。reference_image_urls 与 reference_video_urls 至少传一个。 `maxItems: 9`
`input.reference_video_urls` 可选	`array`	参考视频 URL 数组。最多支持 3 个。支持 MP4、MOV；视频编码支持 H.264、H.265；单个文件不超过 50 MB；单段时长为 2 至 15 秒，所有参考视频合计时长不超过 15 秒；视频边长需在 256 至 5760 像素之间，宽高比需在 0.4 至 2.5 之间，帧率需在 23.976 至 60 之间。reference_image_urls 与 reference_video_urls 至少传一个。 `maxItems: 3`
`input.reference_audio_urls` 可选	`array`	参考音频 URL 数组。最多支持 3 个。支持 WAV、MP3；单个文件不超过 15 MB；单段时长为 2 至 15 秒，所有参考音频合计时长不超过 15 秒。reference_audio_urls 不能单独传入，必须同时传入 reference_image_urls 或 reference_video_urls。 `maxItems: 3`
`input.aspect_ratio` 可选	`string`	视频画面比例。默认使用 adaptive，也可以指定具体比例。可选值：`"adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"` 默认：`"adaptive"`
`input.duration` 必填	`integer`	生成视频时长，支持 4 至 15 秒的整数值。可选值：`4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15` 默认：`6` `minimum: 4` `maximum: 15`
`input.resolution` 可选	`string`	视频分辨率。可选值：`"768P", "2K"` 默认：`"2K"`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-h3/reference-to-video",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "Generate a continuous cinematic video referencing the characters, actions, and scenes in the input material",
    "reference_image_urls": [
      "https://example.com/input.png"
    ],
    "reference_video_urls": [
      "https://example.com/input.png"
    ],
    "reference_audio_urls": [
      "https://example.com/input.png"
    ],
    "aspect_ratio": "adaptive",
    "duration": 6
  }
}'

返回值与错误

HTTP 200

参数	类型	说明与限制
`code` 必填	`integer`	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 必填	`string`	响应消息，失败时的错误描述
`data` 必填	`object`
`data.taskId` 必填	`string`	可以使用任务 ID 与“获取任务详细信息”端点一起查询任务状态。

MiniMax H3 文生视频

POST/api/v1/jobs/createTask

模型标识： minimax-h3/text-to-video

参数	类型	说明与限制
`model` 必填	`string`	生成任务的模型名称。用于 MiniMax H3 文生视频。可选值：`"minimax-h3/text-to-video"` 默认：`"minimax-h3/text-to-video"`
`callBackUrl` 可选	`string`	任务完成后的回调地址。
`input` 必填	`object`
`input.prompt` 必填	`string`	视频生成提示词，长度为 1 至 7000 个字符。 `minLength: 1` `maxLength: 7000`
`input.aspect_ratio` 必填	`string`	视频画面比例。文生视频必填，不支持 adaptive。可选值：`"21:9", "16:9", "4:3", "1:1", "3:4", "9:16"`
`input.duration` 必填	`integer`	生成视频时长，支持 4 至 15 秒的整数值。可选值：`4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15` 默认：`6` `minimum: 4` `maximum: 15`
`input.resolution` 可选	`string`	视频分辨率。可选值：`"768P", "2K"` 默认：`"2K"`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-h3/text-to-video",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "A cat walking slowly on the beach at sunset, cinematic shot",
    "aspect_ratio": "16:9",
    "duration": 6
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	Response message, error description upon failure
`data` 必填	`object`
`data.taskId` 必填	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。