Hailuo / Video Generation

Hailuo 视频生成

Hailuo 是 MiniMax 的视频生成模型系列，适合文生视频、图生视频、首尾帧过渡和主体参考创作。Hailuo 使用异步任务接口提交请求，再轮询任务状态和结果视频。

可用模型

调用时在 model 字段填写控制台开放的模型名。当前 Hailuo 系列开放以下模型：

模型	说明	常见能力
`MiniMax-Hailuo-2.3`	Hailuo 2.3 高质量视频生成模型。	文生视频、图生视频、首尾帧、主体参考；常用 768p 和 1080p。
`MiniMax-Hailuo-2.3-Fast`	Hailuo 2.3 Fast，侧重更快生成和成本效率。	图生视频和常见参考创作；常用 768p 和 1080p。
`MiniMax-Hailuo-02`	Hailuo 02 视频生成模型。	文生视频、图生视频、首尾帧、主体参考；支持 512p、768p 和 1080p 档位。

具体可调用能力以模型广场、控制台模型权限和接口返回为准。未开放或未配置价格的规格会被拒绝，不会按默认价格兜底调用。

固定规格

Hailuo 不是任意秒数线性计费的视频接口。当前按固定规格生成和结算，计费项由 resolution.duration 组成，例如 768p.6s。

模型	可用规格	说明
`MiniMax-Hailuo-2.3`	`768p.6s`、`768p.10s`、`1080p.6s`	高质量生成，10 秒规格仅用于 768p。
`MiniMax-Hailuo-2.3-Fast`	`768p.6s`、`768p.10s`、`1080p.6s`	快速生成，10 秒规格仅用于 768p。
`MiniMax-Hailuo-02`	`512p.6s`、`512p.10s`、`768p.6s`、`768p.10s`、`1080p.6s`	覆盖更多低分辨率和高分辨率组合。

如果传入未配置组合，例如 1080p.10s，接口会返回参数或价格配置错误。请按模型广场展示的规格选择 resolution 和 duration。

接口和能力

能力	接口	用途	关键参数
文生视频	`POST /v1/video/generations`	只通过文字提示词生成视频。	`model`、`prompt`、`duration`、`resolution`
图生视频	`POST /v1/video/generations`	基于首帧图片生成视频。	`image` 或 `images[0]`、`prompt`、`duration`、`resolution`
首尾帧	`POST /v1/video/generations`	指定开始画面和结束画面，生成中间过渡。	`images[0]`、`images[1]`，或 `metadata.first_frame_image`、`metadata.last_frame_image`
主体参考	`POST /v1/video/generations`	通过参考主体图片约束人物或角色一致性。	`metadata.subject_reference`

图片 URL 必须能被服务端公网访问，不能使用本机地址、内网地址、需要登录的地址或已过期签名地址。也可以传 Base64 图片，但请求体会更大。

常用参数

参数	可用值	说明
`prompt`	文本	视频内容、主体动作、镜头、风格和限制条件。建议写清楚主体、动作、场景和镜头运动。
`duration`	`6`、`10`	目标视频规格秒数。不是所有模型和分辨率都支持 10 秒。
`resolution` / `size`	`512p`、`768p`、`1080p`	输出清晰度和计费项的一部分。大小写不敏感。
`image`	图片 URL 或 Base64	单图图生视频的首帧图片。
`images`	图片数组	`images[0]` 作为首帧，`images[1]` 作为尾帧。传两张图时按首尾帧处理。
`task_type`	`text2video`、`image2video`、`first_last_frame`、`subject_reference`	可选。通常平台会根据图片和 metadata 自动识别能力，显式传入可以让日志更清楚。
`metadata.prompt_optimizer`	`true` / `false`	是否使用提示词优化。是否生效以所选模型支持为准。
`metadata.fast_pretreatment`	`true` / `false`	是否启用快速预处理。是否生效以所选模型支持为准。
`metadata.aigc_watermark`	`true` / `false`	是否添加 AIGC 水印。具体行为以上游模型为准。

计费说明

Hailuo 按固定规格视频结算，不按任意秒数乘以每秒单价。一次成功任务会按命中的 resolution.duration 计费项扣费；失败、安全审核失败或上游未成功生成的任务会按平台规则退回或结算为 0。

日志字段	示例	说明
`billing_item`	`512p.6s`	本次命中的固定规格。
`billing_units`	`1`	按 1 个视频规格结算。
`billing_unit_video`	`1`	表示该任务是按视频规格计费，不是按秒线性计费。

具体金额以控制台模型广场和价格页展示为准。不同模型、分辨率和时长规格价格不同，例如同一分辨率的 6 秒和 10 秒不是同一个计费项。

文生视频示例

curl "https://youlai.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "黄昏城市天台，一位创作者打开笔记本电脑，镜头缓慢推进，真实电影感",
    "duration": 6,
    "resolution": "768p",
    "task_type": "text2video"
  }'

图生视频示例

curl "https://youlai.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-02",
    "prompt": "保持画面主体和光照一致，让湖面出现轻微波纹，镜头缓慢向前移动",
    "image": "https://example.com/first-frame.jpg",
    "duration": 6,
    "resolution": "512p",
    "task_type": "image2video"
  }'

首尾帧示例

首尾帧仍使用通用视频任务接口。传入两张图片时，第一张作为起始帧，第二张作为结束帧。

curl "https://youlai.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "从第一张图自然过渡到结束姿态，动作连贯，光照一致",
    "images": [
      "https://example.com/start.jpg",
      "https://example.com/end.jpg"
    ],
    "duration": 6,
    "resolution": "768p",
    "task_type": "first_last_frame"
  }'

主体参考示例

主体参考适合保持人物或角色一致。当前建议只传单个清晰主体图片，人物完整、无遮挡、背景简单时稳定性更好。

curl "https://youlai.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "让参考人物在明亮工作室中自然转身并向镜头微笑，电影感灯光",
    "duration": 6,
    "resolution": "768p",
    "task_type": "subject_reference",
    "metadata": {
      "subject_reference": [
        {
          "type": "character",
          "image": ["https://example.com/character.jpg"]
        }
      ]
    }
  }'

查询任务结果

提交成功后会返回平台任务 ID。使用同一任务查询接口加上任务 ID 轮询结果，直到任务进入成功或失败状态。

curl "https://youlai.ai/v1/video/generations/TASK_ID" \
  -H "Authorization: Bearer sk-xxxxxxxx"

字段	说明
`data.task_id`	平台任务 ID。
`data.status`	任务状态，常见为排队、处理中、成功或失败。
`data.progress`	任务进度。
`data.result_url`	任务成功后的结果视频 URL。
`data.quota`	本次任务扣费额度。
`data.fail_reason`	任务失败原因，例如素材不可访问、模型不支持该规格或安全审核失败。

也可以使用 GET /v1/videos/{task_id} 获取 OpenAI Video 风格的查询响应。

排障建议

问题	处理方式
400 参数错误	确认模型名、`resolution` 和 `duration` 是否属于当前模型的固定规格。
素材不可访问	确认图片 URL 在公网可访问，且没有登录、签名过期、防盗链或证书问题。
首尾帧没有生效	使用 `images` 传两张图，或在 `metadata` 中显式传 `first_frame_image` 与 `last_frame_image`。
主体参考失败	换用主体清晰、完整、无遮挡的参考图，并确认 `subject_reference` 结构正确。
费用高于预期	检查是否使用更高分辨率或 10 秒规格；Hailuo 6 秒和 10 秒是不同计费项。