创建 MiniMax-H3 视频生成任务

该接口提交一个 MiniMax-H3 异步视频任务，支持文生视频、首帧/尾帧图生视频和多模态参考生成。请求字段遵循 MiniMax-H3 V2 的任务结构；本站使用 PinduCloud Token 和公开任务 ID。

请求

POST https://video.pinducloud.com.cn/hailuo/v2/video_generation

文生视频示例：

curl --request POST "$BASE_URL/hailuo/v2/video_generation" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "一座灯塔立在雾海中，镜头缓慢向前推进"}
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

顶层参数

字段	类型	必填	取值或范围	说明
model	string	是	MiniMax-H3	路由固定使用 MiniMax-H3
content	array	是	多模态内容数组	必须包含一个非空 text 项
resolution	string	是	768P、2K	输出分辨率
duration	integer	是	4~15	输出时长，单位秒
ratio	string	否	`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`	画面比例
callback_url	string	否	HTTP/HTTPS 地址，且服务端必须能访问	状态变化回调地址
aigc_watermark	boolean	否	true / false	是否添加 AIGC 标识水印，默认 false

纯文本请求未传 ratio 时默认为 16:9；包含图片或视频时默认为 adaptive；仅包含音频参考时未传 ratio 仍默认为 16:9。显式使用 adaptive 时必须有图片、视频或音频媒体。图生视频的比例由输入图像决定，传入其他比例可能会被忽略；多模态参考场景可以明确指定比例。

表中列出的是本站支持并发送给 H3 服务的参数。Seedance 专用的 frames、 service_tier、draft、draft_task 和 output_format 不属于 H3 视频生成请求，本站不会把它们转换成 duration 或 resolution；调用时不要传入这些字段。

content 结构

type	必填字段	可用 role	说明
text	text	无	所有场景至少一个非空文本提示词
image_url	image_url.url	first_frame、last_frame、reference_image	图像输入
video_url	video_url.url	reference_video	多模态参考视频
audio_url	audio_url.url	reference_audio	多模态参考音频

URL 可以使用公网 URL、mm_file://FILE_ID（已登记的文件）或小体积 Base64 data URI。JSON 请求体上限为 64 MB；大文件使用公网 URL或已存在的文件引用。 URL 必须能被服务端读取，本站不会把本地磁盘路径转换成公网地址。

输入场景组合

场景	推荐组合	约束
文生视频	text	纯文本时不能使用 adaptive
首帧图生视频	text + 一项 image_url	role=first_frame，单图也可省略 role
尾帧图生视频	text + 一项 image_url	role=last_frame
首尾帧图生视频	text + 两项 image_url	分别使用 first_frame、last_frame
多模态参考	text + 参考图/视频/音频	至少一项 reference_*

帧图场景与多模态参考场景互斥。出现任一 reference_image、reference_video 或 reference_audio 时，不能再传 first_frame 或 last_frame。

媒体限制

图片

JPG、JPEG、PNG、WEBP、HEIC、HEIF。
单文件不超过 30 MB，宽高均在 256~5760 像素，宽高比在 [0.4, 2.5]。
首帧最多 1 张、尾帧最多 1 张，参考图最多 9 张。

参考视频

仅多模态参考场景使用，容器为 MP4 或 MOV。
视频编码支持 H.264/AVC、H.265/HEVC，音频编码支持 AAC、MP3。
单个不超过 50 MB，最多 3 个；单段 2~15 秒，所有参考视频总时长不超过 15 秒。
宽高均为 256~5760 像素，宽高比 [0.4, 2.5]，帧率 [23.976, 60]。

参考音频

WAV 或 MP3，单文件不超过 15 MB，最多 3 段。
单段 2~15 秒，所有参考音频总时长不超过 15 秒。

请求示例

首帧图生视频

curl --request POST "$BASE_URL/hailuo/v2/video_generation" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "镜头对焦背景人物，并让拉面碗上升起更多蒸汽"},
      {
        "type": "image_url",
        "image_url": {"url": "https://cdn.example.com/input.png"},
        "role": "first_frame"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive"
  }'

多模态参考视频

curl --request POST "$BASE_URL/hailuo/v2/video_generation" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "角色说：Follow the wind, live free. 音色参考音频 1"},
      {
        "type": "video_url",
        "video_url": {"url": "https://cdn.example.com/reference.mp4"},
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {"url": "https://cdn.example.com/reference.mp3"},
        "role": "reference_audio"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive"
  }'

回调地址

callback_url 用于接收异步任务状态通知。创建接口检查地址的类型和基本格式，不以回调地址的可达性作为受理前提。接口返回任务 ID 仅表示生成请求已受理，不表示回调地址验证成功或通知已送达。

接收端收到包含 challenge 的验证请求时，应以 JSON 原样返回该值，例如收到 {"challenge":"value"} 时返回相同对象。该验证属于回调流程，与创建接口的请求受理分开处理。

回调服务需公网可达，并处理重复、乱序通知：已记录终态后，不应被较早的 queued 或 running 覆盖。回调失败不等于生成失败，最终结果与本站结算状态通过查询任务确认；保留轮询作为回调丢失时的补充。

成功响应

{
  "task_id": "task_gateway_h3_01"
}

任务创建成功只表示任务已受理，视频产物需通过查询接口读取。

请求​

顶层参数​

content 结构​

输入场景组合​

媒体限制​

图片​

参考视频​

参考音频​

请求示例​

首帧图生视频​

多模态参考视频​

回调地址​

成功响应​

请求