模型说明

MiniMax-H3（Video Generation V2）支持文生视频、图生视频（首尾帧）、多模态参考生视频，以及 H3-Context-IR 提示词增强与 768P→2K 再生成。

功能接口详情

创建视频生成任务

创建视频生成任务。模型依据传入的文本、图片、视频、音频等多模态信息生成视频。本接口为异步接口，创建成功后返回 task_id，需通过查询任务接口轮询任务状态，任务成功后获取生成视频。

请求 URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation

参数名	字段类型	是否必填	描述
Authorization	string	是	`Bearer {YOUR_AK}`
Content-Type	string	是	请求体的媒介类型，请设置为 `application/json`。

请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
content	array	是	-	多模态输入内容数组，描述用于生成视频的信息。每个元素通过 `type` 区分类型（`text` / `image_url` / `video_url` / `audio_url`），并可通过 `role` 标注用途。
resolution	string	是	-	视频分辨率。当前可用值：`768P`、`2K`。
duration	integer	是	-	生成视频时长（秒），必选，整数。可用值：`4`\~`15`。
ratio	string	条件	`adaptive`	生成视频的宽高比，默认 `adaptive`（自动，由输入自适应选择最合适的宽高比，实际比例可在查询接口的 `ratio` 字段获取）。可用值：`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。
callback_url	string	否	-	任务状态变更的回调通知地址。配置后 MiniMax 服务器会先发送含 `challenge` 字段的验证请求（需 3 秒内原样返回 `challenge` 完成验证），验证成功后每当任务状态变更即向该地址 POST 推送，推送体结构与查询任务接口的响应一致。
aigc_watermark	boolean	否	`false`	是否在生成视频中添加 AIGC 标识水印，默认 `false`。

content字段说明：

每次请求必须包含一个非空 text 项（prompt 必填）；缺失会返回参数错误。

支持的输入组合（对应不同生成场景）：
- 文生视频：仅一个 text 元素。
- 图生视频-首帧：text + 1 张 image_url（role=first_frame 或不填）。
- 图生视频-尾帧：text + 1 张 image_url（role=last_frame）。
- 图生视频-首尾帧：text + 2 张 image_url（role 分别为 first_frame、last_frame）。
- 多模态参考生视频：text + 参考图片（role=reference_image）+ 参考视频（role=reference_video）+ 参考音频（role=reference_audio）的组合；不可仅输入音频，须至少包含 1 个参考视频或图片。

> 图生视频与多模态参考生视频互斥：content 中出现 reference_image / reference_video / reference_audio 任一 role，就不能再出现 first_frame / last_frame（反之亦然），二者不可混用。

输入媒体限制（请求体总大小 ≤ 64 MB，大文件请用公网 URL，勿用 Base64）见下方分表。

文生视频（t2va，content 仅含 text）：ratio 必填，且不能为 adaptive；可用值 21:9、16:9、4:3、1:1、3:4、9:16。

图生视频（i2va，content 含 first_frame / last_frame 图片）：宽高比由输入图片决定，ratio 恒为 adaptive；传入其他合理值不会报错，但会被忽略并按 adaptive 处理。

多模态参考生视频（r2va，content 含 reference_image / reference_video / reference_audio）：ratio 可选，默认 adaptive；也可显式指定上述任一具体比例。

content[] 元素字段

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	输入内容的类型。枚举：`text` / `image_url` / `video_url` / `audio_url`。
text	string	条件	-	文本提示词（prompt），必填：所有场景都需包含一个非空 `text`，描述期望生成的视频。按字符数计算长度，单个 `text` 最多 7000 个字符。
image_url	object	条件	-	当 `type=image_url` 时的图片对象（格式 / 大小 / 尺寸 / 数量限制见上方 content 说明）。
image_url.url	string	是	-	图片地址,支持:公网 URL;`mm_file://{file_id}`(引用平台已有文件,如上传或历史产物的 file_id);`data:image/<格式>;base64,<Base64>` data URI(`<格式>` 小写)。
video_url	object	条件	-	当 `type=video_url` 时的视频对象（参考视频，仅多模态参考场景；格式 / 大小 / 时长限制见上方 content 说明）。
video_url.url	string	是	-	视频地址,支持:公网 URL;`mm_file://{file_id}`(引用平台已有文件的 file_id);`data:video/mp4;base64,<Base64>` data URI。注意请求体总大小 ≤ 64 MB、Base64 会放大约 33%,大视频请用公网 URL 或 mm_file://。
audio_url	object	条件	-	当 `type=audio_url` 时的音频对象（参考音频，仅多模态参考场景；格式 / 大小 / 时长限制见上方 content 说明）。
audio_url.url	string	是	-	音频地址,支持:公网 URL;`mm_file://{file_id}`(引用平台已有文件的 file_id);`data:audio/<格式>;base64,<Base64>` data URI(`<格式>` 小写)。
role	string	条件	-	内容的位置或用途，条件必填： - `first_frame`：首帧图片（图生视频；仅一张图且不填 role 时默认按 first_frame 处理）。 - `last_frame`：尾帧图片（图生视频-首尾帧，需与 first_frame 成对）。 - `reference_image`：参考图片（多模态参考生视频）。 - `reference_video`：参考视频（多模态参考生视频）。 - `reference_audio`：参考音频（多模态参考生视频，不可单独输入）。

图片 image_url 限制

项	限制
格式	JPG、JPEG、PNG、WEBP、HEIC、HEIF
单文件大小	≤ 30 MB
宽高范围	[256, 5760] px
长宽比（宽/高）	[0.4, 2.5]
数量	首帧 ≤ 1、尾帧 ≤ 1、参考图 ≤ 9

视频 video_url（仅多模态参考场景）

项	限制
容器 / 格式	MP4（`.mp4`）、MOV（`.mov`）
编码	视频 H.264/AVC、H.265/HEVC；音频 AAC、MP3
单文件大小	≤ 50 MB
个数	≤ 3
单段时长	[2, 15] s；总时长 ≤ 15 s
宽高范围	[256, 5760] px
长宽比（宽/高）	[0.4, 2.5]
帧率	[23.976, 60]

音频 audio_url（仅多模态参考场景）

项	限制
格式	WAV、MP3
单文件大小	≤ 15 MB
个数	≤ 3
单段时长	[2, 15] s；总时长 ≤ 15 s

响应参数

参数名	字段类型	描述
task_id	string	任务 ID，用于后续查询任务状态与结果。

请求示例

文生视频：

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "16:9"
}'

图生视频（首帧）：

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "Pull focus to the people in the background and add more steam to the ramen bowl."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
      },
      "role": "first_frame"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}'

响应示例

{
  "task_id": "424010985738629"
}

创建 H3-Context-IR 任务

H3-Context-IR 深度理解文本、图像、音频和视频等多模态上下文，分析素材之间以及素材与目标生成结果之间的关系，并进行复杂逻辑推理。系统会将理解结果转换为结构化表达，在尽量保持用户原始意图的前提下丰富语义细节。本接口只返回增强提示词，不创建视频生成任务。

请求 URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/h3_context_ir

请求 Header

参数名	字段类型	是否必填	描述
Authorization	string	是	`Bearer {YOUR_AK}`
Content-Type	string	是	请求体的媒介类型，请设置为 `application/json`。

请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
content	array	是	-	多模态上下文输入数组，用于描述目标视频及各类素材之间的关系。每个元素通过 `type` 区分类型（`text` / `image_url` / `video_url` / `audio_url`），并可通过 `role` 标注用途。每次请求必须包含一个非空 `text` 项（prompt 必填）；缺失会返回参数错误。支持的输入组合、互斥规则与媒体限制同「3.1 创建视频生成任务」。
duration	integer	是	-	目标视频时长（秒），必选，整数。可用值：`4`\~`15`。
ratio	string	条件	`adaptive`	目标视频的宽高比，默认 `adaptive`。可用值：`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。文生视频（t2va，content 仅含 `text`）：`ratio` 必填，且不能为 `adaptive`；可用值 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。图生视频（i2va，content 含 `first_frame` / `last_frame` 图片）：宽高比由输入图片决定，`ratio` 恒为 `adaptive`；传入其他合理值不会报错，但会被忽略并按 `adaptive` 处理。多模态参考生视频（r2va，content 含 `reference_image` / `reference_video` / `reference_audio`）：`ratio` 可选，默认 `adaptive`；也可显式指定上述任一具体比例。
callback_url	string	否	-	任务状态变更的回调通知地址。配置后 MiniMax 服务器会先发送含 `challenge` 字段的验证请求（需 3 秒内原样返回 `challenge` 完成验证），验证成功后每当任务状态变更即向该地址 POST 推送，推送体结构与查询任务接口的响应一致。回调 `status` 取值：`queued`（排队中）、`running`（运行中）、`succeeded`（成功）、`failed`（失败）、`cancelled`（已取消）。

content[] 元素字段同 3.1.3。

响应参数

参数名	字段类型	描述
task_id	string	任务 ID，用于后续查询任务状态与结果。

请求示例

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/h3_context_ir' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "一个男孩在海边打篮球"
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}'

响应示例

{
  "task_id": "426586401755526"
}

创建视频再生成任务

对符合 MiniMax-H3 768P 输出规格的源视频再生成为 2K 视频。支持两种输入模式，source_task_id 与 content（含 base_video）必须且只能提供其一（都提供或都不提供均返回参数错误）：

按任务 ID 再生成（source_task_id）：传入一个已有视频生成成功任务的 source_task_id，以其产物为源再生成。该模式需开通白名单；源任务须属于当前账号、状态为 succeeded，且仍在查询任务的 7 天查询窗口内。无需再传 content。
按源视频再生成（base_video）：在 content 中提供且仅提供一个 type=video_url、role=base_video 的源视频项，并原样附上生成该 768P 视频时的其余输入。

本接口为异步接口，创建成功后返回 task_id，通过查询任务轮询任务状态；task_type 为 regeneration。

请求 URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_regeneration

请求 Header

参数名	字段类型	是否必填	描述
Authorization	string	是	`Bearer {YOUR_AK}`
Content-Type	string	是	请求体的媒介类型,请设置为 `application/json`。

请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
source_task_id	string	条件	-	已有视频生成成功任务的 `task_id`，以其产物为源再生成。使用限制：需开通白名单；源任务须属于当前账号、状态为 `succeeded`，且仍可通过查询任务接口查到（创建于 7 天内）。与 `content` 必须且只能提供其一。
content	array	条件	-	视频再生成输入内容数组（按源视频模式）。请在数组中包含： - 必须原样提交生成 768P 源视频时实际送入模型的全部输入。其中，`text` 必须使用当时实际送入模型的最终 prompt，不可使用 H3-Context-IR 处理前的原始 prompt；所有参考图片、视频和音频也必须与生成时一致。任何输入不一致，都可能无法达到预期的再生成效果 - 一个 768P 源视频项，`type=video_url` 且 `role=base_video`；该项必须且只能有一个 `base_video` 必须符合以下 MiniMax-H3 768P 输出规格。本接口不支持任意视频的通用再生成。 --- 输入媒体限制：请求体总大小 ≤ 64 MB，大文件请用公网 URL，勿用 Base64。参考图片 / 视频 / 音频的格式、单文件大小等限制同「3.1 创建视频生成任务」。与 `source_task_id` 必须且只能提供其一。
resolution	string	是	-	视频再生成的目标分辨率，必填。当前支持 `2K`。
callback_url	string	否	-	任务状态变更的回调 URL,可选。行为同创建视频生成任务的 `callback_url`。
aigc_watermark	boolean	否	-	是否为生成视频添加 AIGC 水印，可选，默认 `false`。

base_video 规格

项目	规格
音轨	需包含音轨，不支持无音轨视频
帧率	24 fps
宽 / 高	均需能被 32 整除
面积（宽 × 高）	≤ 768 × 1344（1,032,192 像素）
总帧数	107–362 帧，每档递增 17 帧（约 4–15 秒）

content[] 元素字段（再生成）

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	输入内容的类型。枚举：`text` / `image_url` / `video_url` / `audio_url`。
text	string	条件	-	必须使用生成 768P 源视频时实际送入模型的最终 prompt，不可使用 H3-Context-IR 处理前的原始 prompt。按字符数计算长度，单个 `text` 最多 7000 个字符。
image_url	object	条件	-	当 `type=image_url` 时的图片对象（格式 / 大小 / 尺寸 / 数量限制见上方 content 说明）。
image_url.url	string	是	-	图片地址,支持:公网 URL;`mm_file://{file_id}`(引用平台已有文件,如上传或历史产物的 file_id);`data:image/<格式>;base64,<Base64>` data URI(`<格式>` 小写)。
video_url	object	条件	-	当 `type=video_url` 时的视频对象（参考视频，仅多模态参考场景；格式 / 大小 / 时长限制见上方 content 说明）。
video_url.url	string	是	-	视频地址,支持:公网 URL;`mm_file://{file_id}`(引用平台已有文件的 file_id);`data:video/mp4;base64,<Base64>` data URI。注意请求体总大小 ≤ 64 MB、Base64 会放大约 33%,大视频请用公网 URL 或 mm_file://。
audio_url	object	条件	-	当 `type=audio_url` 时的音频对象（参考音频，仅多模态参考场景；格式 / 大小 / 时长限制见上方 content 说明）。
audio_url.url	string	是	-	音频地址,支持:公网 URL;`mm_file://{file_id}`(引用平台已有文件的 file_id);`data:audio/<格式>;base64,<Base64>` data URI(`<格式>` 小写)。
role	string	条件	-	内容的位置或用途，条件必填： - `base_video`：视频再生成源视频（仅 `/v2/video_regeneration` 使用）；源视频项必须显式设置该 `role`，`content` 中必须且只能有 1 个。 - `first_frame`：首帧图片（图生视频；仅一张图且不填 role 时默认按 first_frame 处理）。 - `last_frame`：尾帧图片（图生视频-首尾帧，需与 first_frame 成对）。 - `reference_image`：参考图片（多模态参考生视频）。 - `reference_video`：参考视频（多模态参考生视频）。 - `reference_audio`：参考音频（多模态参考生视频，不可单独输入）。

响应参数

参数名	字段类型	描述
task_id	string	任务 ID，用于后续查询任务状态与结果。

请求示例

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_regeneration' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "content": [
    {
      "type": "text",
      "text": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://your-cdn.example.com/h3-t2va-768p.mp4"
      },
      "role": "base_video"
    }
  ],
  "resolution": "2K"
}'

响应示例

{
  "task_id": "424010985738631"
}

查询任务

按 task_id 查询最近 7 天内单个视频生成、H3-Context-IR 或视频再生成任务的状态与结果。任务成功（status=succeeded）后可从 content 获取产物：视频任务返回 content.url，H3-Context-IR 任务返回 content.prompt 中的增强提示词。

请求 URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/query/video_generation/{task_id}

请求 Header

参数名	字段类型	是否必填	描述
Authorization	string	是	`Bearer {YOUR_AK}`

路径参数

参数名	字段类型	是否必填	描述
task_id	string	是	要查询的任务 ID（创建任务返回的 `task_id`）。

响应参数

参数名	字段类型	描述
task	object	H3 共享任务查询和列表接口返回的任务对象。
task.id	string	任务 ID。
task.model	string	任务使用的模型名称，如 `MiniMax-H3`。
task.status	string	任务状态： - `queued`：排队中 - `running`：运行中 - `succeeded`：成功 - `failed`：失败 - `cancelled`：已取消
task.error	object	错误信息，任务成功时不返回；任务失败时返回 `code` 与 `message`。
task.error.code	string	错误码。
task.error.message	string	错误提示信息。
task.created_at	integer	任务创建时间的 Unix 时间戳（秒）。
task.updated_at	integer	任务状态更新时间的 Unix 时间戳（秒）。
task.content	object	任务输出内容，任务成功后返回。
task.content.url	string	视频任务产物的限时下载 URL，请及时下载或转存；过期后可重新查询获取。
task.content.prompt	string	H3-Context-IR 任务生成的结构化增强提示词。仅当 `task_type=h3_context_ir` 且任务成功时返回。
task.resolution	string	任务产物的分辨率。
task.duration	integer	任务产物的时长（秒）。
task.usage	object	本次请求的计费用量。视频任务返回按秒计量的字段；H3-Context-IR 任务返回 Token 用量字段。
task.usage.total_seconds	integer	本次计费总秒数 = 输入秒数 + 输出秒数。
task.usage.input_seconds	integer	输入参考视频计费秒数（含参考视频时计）。
task.usage.output_seconds	integer	输出视频计费秒数。
task.usage.input_image_count	integer	本次计费涉及的图片数量。
task.usage.total_tokens	integer	H3-Context-IR 任务使用的 Token 总数。
task.usage.prompt_tokens	integer	H3-Context-IR 任务的输入 Token 数。
task.usage.completion_tokens	integer	H3-Context-IR 任务的输出 Token 数。
task.ratio	string	任务产物的宽高比；不适用于当前任务类型时可能返回空字符串。
task.task_type	string	任务类型： - `generation`：视频生成 - `h3_context_ir`：H3-Context-IR（`/v2/h3_context_ir`） - `regeneration`：视频再生成（`/v2/video_regeneration`）
task.modality	string	产物模态。视频生成和视频再生成任务返回 `video`；H3-Context-IR 任务返回 `text`。

请求示例

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/query/video_generation/{task_id}' \
--header 'Authorization: Bearer {YOUR_AK}'

响应示例

视频生成成功：

{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/89f8c0bbee5b_denoise_ids_0_final.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

H3-Context-IR 成功：

{
  "task": {
    "id": "426586401755526",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785702855,
    "updated_at": 1785702884,
    "content": {
      "prompt": "integrated_multimodal_description: ..."
    },
    "duration": 5,
    "usage": {
      "total_tokens": 9090,
      "prompt_tokens": 5664,
      "completion_tokens": 3426
    },
    "ratio": "16:9",
    "task_type": "h3_context_ir",
    "modality": "text"
  }
}

取消或删除任务

根据任务当前状态取消或删除视频生成、H3-Context-IR 及视频再生成任务：

任务状态	执行操作（action）	说明
`queued`（排队中）	`cancelled`	取消任务，任务尚未开始处理，无扣费
`succeeded`（成功）	`deleted`	删除任务记录
`failed`（失败）	`deleted`	删除任务记录
`running`（运行中）	—	不可操作，返回错误（处理中无法取消）
`cancelled`（已取消）	—	不可操作，返回错误

请求 URL

DELETE https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation/{task_id}

请求 Header

参数名	字段类型	是否必填	描述
Authorization	string	是	`Bearer {YOUR_AK}`

路径参数

参数名	字段类型	是否必填	描述
task_id	string	是	要取消或删除的任务 ID。

响应参数

参数名	字段类型	描述
task_id	string	被操作的任务 ID。
action	string	实际执行的操作：`cancelled`（取消，仅 queued 态）或 `deleted`（删除成功或失败的任务记录）。
status	string	操作结果状态：`cancelled`（已取消）或 `deleted`（记录已删除）。

请求示例

curl --location --request DELETE 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/minimax/video_generation/{task_id}' \
--header 'Authorization: Bearer {YOUR_AK}'

响应示例

{
  "task_id": "424010985738629",
  "action": "cancelled",
  "status": "cancelled"
}