MiniMax H3 视频生成 API

本文档说明如何通过 Mozia API 的统一视频接口调用 MiniMax H3。接口采用异步任务模式：提交任务、轮询状态、下载结果。

接口总览

方法	路径	作用
`POST`	`/v1/video/generations`	推荐：提交视频生成任务
`GET`	`/v1/video/generations/{task_id}`	推荐：查询任务状态、进度与结果
`GET`	`/v1/video/generations/{task_id}/content`	推荐：下载生成的视频
`POST`	`/v1/videos`	OpenAI Videos 兼容提交路由
`GET`	`/v1/videos/{task_id}`	OpenAI Videos 兼容查询路由
`GET`	`/v1/videos/{task_id}/content`	OpenAI Videos 兼容下载路由

基础地址：https://mzsjai.com

所有请求都需要 API Key：

Authorization: Bearer <YOUR_API_KEY>

模型

对外模型名	用途	素材要求
`minimax/minimax-h3-t2va`	强制文生视频	不允许携带素材
`minimax/minimax-h3-fl2va`	文生视频兼容入口、首帧或首尾帧视频	空素材自动转 `t2va`；有素材时按 `fl2va` 处理
`minimax/minimax-h3-ref2va`	参考素材视频	必须携带参考素材

新接入的纯文本调用推荐使用 minimax/minimax-h3-t2va。已有 minimax/minimax-h3-fl2va 客户端无需迁移，空素材请求会由平台自动兼容。

简单的文生视频请求示例

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/video/generations' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax/minimax-h3-t2va",
    "prompt": "日落时分的无人海滩，镜头贴近沙滩向海面平稳推进",
    "duration": 4,
    "resolution": "768P",
    "ratio": "16:9"
  }'

建议每 5～10 秒查询一次：

GET https://mzsjai.com/v1/video/generations/{task_id}
Authorization: Bearer <YOUR_API_KEY>

该接口对外常见状态为 queued、running、succeeded 和 failed。任务提交后的第一次查询可能短暂返回 unknown，应继续轮询，不要立即判定失败。

当前能力边界

Mozia 平台当前支持以下 MiniMax H3 能力：

能力	当前状态
文生视频	支持
首帧图生视频	支持
首帧 + 尾帧	支持
仅尾帧	不支持，尾帧必须与首帧同时提交
参考图	支持；稳定建议 1～9 张
参考视频	支持，使用 `ref2va`
参考音频	支持，使用 `ref2va`
保留参考视频原音	支持，仅限一个带音轨的参考视频
时长	支持 4～15 秒
`768P`	支持
`2K`	请使用 `minimax/minimax-h3-2k` 模型id
`adaptive` 比例	未作为稳定能力提供
`callback_url`	不会转发给 H3 服务，应使用轮询
`usage`	当前响应不返回

首尾帧不能与任何参考素材混用，包括参考图、参考视频和参考音频。素材应使用模型 Worker 可以访问的 HTTP/HTTPS URL；Data URL、原始 Base64、本地文件路径和 multipart 文件上传不属于当前 V2 H3 接口的稳定输入协议。

ref2va 要求至少提交一个参考素材。

提交任务

POST https://mzsjai.com/v1/video/generations
Content-Type: application/json

请求参数

参数	类型	必填	默认值	说明
`model`	string	是	-	使用上文列出的完整 H3 对外模型名
`content`	array	推荐	-	提示词及带角色的图片、视频或音频素材
`prompt`	string	条件必填	-	顶层提示词；与 `content` 中的文本二选一
`duration`	integer	是	-	视频时长（秒），稳定接口使用 4～15 的整数
`resolution`	string	否	平台默认	当前仅支持 `768P`
`ratio`	string	否	见说明	使用 `768P` 时默认 `16:9`；未指定清晰度时使用平台默认值
`size`	string	否	-	尺寸兼容别名；会转换为短边和宽高比，不是任意宽高的精确透传
`seed`	integer	否	上游默认	随机种子
`preserve_reference_audio`	boolean	否	`false`	控制生成结果是否保留参考视频里的原始音轨
`metadata`	object	否	-	H3 扩展参数；其中字段仅在顶层没有同名字段时生效

prompt 和 content 中至少要有一段非空文本。如果两者同时存在，顶层 prompt 优先。

content 格式

文本项：

{
  "type": "text",
  "text": "人物沿海边自然行走，镜头平稳跟随"
}

图片项：

{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "https://example.com/person.jpg"
  }
}

H3 当前支持的素材角色：

`type`	`role`	数量	说明
`image_url`	`first_frame`	0～1	视频首帧，仅用于 `fl2va`
`image_url`	`last_frame`	0～1	视频尾帧，必须同时提供首帧
`image_url`	`reference_image`	建议 1～9	人物、主体、服装、风格或场景参考图
`video_url`	`reference_video`	稳定建议 1	视频运动、身份或场景参考，仅用于 `ref2va`
`audio_url`	`reference_audio`	稳定建议 1	语义音频参考，仅用于 `ref2va`

不能在同一个请求中混用 first_frame/last_frame 与任何 reference_* 素材。

分辨率和比例

有两种设置方式，分别是 resolution + ratio 和 size。新接入推荐使用 resolution + ratio；size 主要用于兼容旧客户端。两种方式不要在同一个请求中混用。

方式一：`resolution` + `ratio`

resolution 表示清晰度或短边档位，当前 H3 稳定支持 768P。
ratio 表示画面宽高比，例如横屏 16:9、竖屏 9:16 或方形 1:1。
省略 ratio 时默认使用 16:9；这不等同于 adaptive。

{
  "resolution": "768P",
  "ratio": "16:9"
}

`resolution`	`ratio`	典型输出尺寸
`768P`	`16:9` 或省略	`1344x768`
`768P`	`9:16`	`768x1344`
`768P`	`1:1`	`768x768`
`768P`	`4:3`	`1024x768`
`768P`	`3:4`	`768x1024`

方式二：`size`

size 将清晰度和宽高比写在一个字符串中，例如：

{
  "size": "1344x768"
}

它不是任意像素尺寸的精确透传参数。MoziaH3 会先识别兼容值，再将其转换为模型使用的短边和宽高比：

`size`	转换结果	典型输出尺寸
`1344x768` 或 `768x448`	短边 `768`、`16:9`	`1344x768`
`768x1344` 或 `448x768`	短边 `768`、`9:16`	`768x1344`
`1024x768`	短边 `768`、`4:3`	`1024x768`
`768x1024`	短边 `768`、`3:4`	`768x1024`
`768x768`	短边 `768`、`1:1`	`768x768`

因此，size: "768x448" 会被当作 768P + 16:9 的兼容别名，不保证最终严格输出 768x448。

不要使用表中未列出的 size。当前适配器对未识别值可能回退到默认 768P + 16:9，而不是报错或保证精确宽高。

如果 resolution、ratio 和 size 都不传，默认使用 768P + 16:9。当前不要使用 2K 或 adaptive。

示例：文生视频

curl -X POST "https://mzsjai.com/v1/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/minimax-h3-t2va",
    "content": [
      {
        "type": "text",
        "text": "日落时分的无人海滩，镜头贴近沙滩向海面平稳推进，海浪声清晰自然"
      }
    ],
    "duration": 5,
    "resolution": "768P",
    "ratio": "16:9"
  }'

示例：首帧图生视频

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/video/generations' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax/minimax-h3-fl2va",
  "content": [
    {
      "type": "text",
      "text": "人物从静止开始自然向前行走，镜头平稳跟随，生成环境声"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://example.com/start.jpg"
      }
    }
  ],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
  }'

示例：首帧和尾帧

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/video/generations' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax/minimax-h3-fl2va",
  "content": [
    {
      "type": "text",
      "text": "从首帧自然过渡到尾帧，保持主体身份、光线和镜头运动连续"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://example.com/start.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": {
        "url": "https://example.com/end.jpg"
      }
    }
  ],
  "duration": 8,
  "resolution": "768P",
  "ratio": "16:9"
  }'

示例：多张参考图

多参考图场景可以在提示词中使用 <Picture 1>、<Picture 2> 等标记，按 reference_image 在 content 中出现的顺序引用图片。

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/video/generations' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax/minimax-h3-ref2va",
  "content": [
    {
      "type": "text",
      "text": "让 <Picture 1> 中的人物穿着 <Picture 2> 中的服装，在海边自然行走，保持人物身份一致"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/person.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/clothes.jpg"
      }
    }
  ],
  "duration": 5,
  "resolution": "768P",
  "ratio": "9:16",
  "metadata": {
    "num_inference_steps": 20,
    "seed": 20260813
  }
  }'

示例：参考视频

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/video/generations' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax/minimax-h3-ref2va",
  "content": [
    {
      "type": "text",
      "text": "Use <Video 1> as the motion and identity reference. Keep the subject and camera motion coherent."
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "url": "https://example.com/reference.mp4"
      }
    }
  ],
  "duration": 8,
  "resolution": "768P",
  "ratio": "16:9"
  }'

Ref2VA 是语义参考生成，不是逐像素视频编辑；不保证与参考视频完全相同的构图和时间对齐。

示例：保留参考视频原音轨

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/video/generations' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax/minimax-h3-ref2va",
  "prompt": "保持参考人物、动作和镜头连续，保留原始音轨",
  "content": [
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "url": "https://example.com/reference-with-audio.mp4"
      }
    }
  ],
  "duration": 8,
  "resolution": "768P",
  "ratio": "16:9",
  "preserve_reference_audio": true
  }'

preserve_reference_audio=true 时必须只有一个参考视频，且文件本身必须含有音频流。上游会在生成后将原音轨合并到结果；保留失败时任务会失败，不会静默改用生成音频。

示例：参考音频

curl --fail-with-body \
  -X POST 'https://mzsjai.com/v1/video/generations' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax/minimax-h3-ref2va",
  "prompt": "生成与参考音频节奏和氛围一致的电影感画面",
  "content": [
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "url": "https://example.com/reference.mp3"
      }
    }
  ],
  "duration": 8,
  "resolution": "768P",
  "ratio": "16:9"
  }'

H3 扩展参数

下列参数可放在顶层，也可放在 metadata 中。顶层同名字段优先：

参数	类型	默认值	说明
`seed`	integer	上游默认	随机种子
`num_inference_steps`	integer	`20`	推理步数；不要使用无效别名 `steps`
`flow_shift`	number	`12.0`	视频生成 flow shift
`audio_flow_shift`	number	FL2VA/T2VA `2.0`，Ref2VA `3.0`	音频生成 flow shift
`quality`	string	`lossless`	上游输出质量
`output_compression`	integer	`100`	上游输出压缩参数
`preserve_reference_audio`	boolean	`false`	保留唯一参考视频的原音轨

这些是 H3 渠道扩展参数，不是所有 Mozia 视频模型的通用参数。除 seed 和 preserve_reference_audio 的明确场景外，建议保持默认值。

旧字段兼容

仍兼容顶层 prompt、image、images、seconds、aspect_ratio 和 size。新接入应使用 content、duration、resolution 和 ratio。input_reference 虽存在于部分通用视频协议中，但当前 MoziaH3 适配器不会将它转换为 H3 参考素材，不应使用。

旧 images 数组没有角色信息：在 fl2va 模型中，一张表示首帧，两张依次表示首帧和尾帧，不要传入更多图片；在 ref2va 模型中视为参考图；t2va 模型会拒绝该字段。新接入应使用 content[].role 明确表达素材语义。

提交成功响应

HTTP 状态码：200

{
  "id": "task_a1b2c3d4",
  "task_id": "task_a1b2c3d4",
  "object": "video",
  "model": "minimax/minimax-h3-t2va",
  "status": "queued",
  "progress": 0,
  "created_at": 1780000000
}

id 与 task_id 相同，都是 Mozia API 的任务 ID。请保存该 ID，用于后续查询和下载。

查询任务

GET https://mzsjai.com/v1/video/generations/{task_id}

curl "https://mzsjai.com/v1/video/generations/task_a1b2c3d4" \
  -H "Authorization: Bearer $API_KEY"

建议每 5～10 秒查询一次。任务状态异步更新，因此连续请求不一定每次都会看到变化。

状态

`status`	说明
`queued`	已创建或正在排队
`running`	正在生成
`succeeded`	生成成功
`failed`	生成失败
`cancelled`	已取消
`expired`	已过期
`unknown`	未识别的状态

progress 是 0～100 的整数。成功、失败、取消或过期任务均返回 100；生成中的进度为平台估算值，不代表 H3 工作流的精确渲染百分比。

生成中响应

{
  "id": "task_a1b2c3d4",
  "task_id": "task_a1b2c3d4",
  "object": "video",
  "model": "minimax/minimax-h3-t2va",
  "status": "running",
  "progress": 30,
  "created_at": 1780000000,
  "updated_at": 1780000060
}

成功响应

{
  "id": "task_a1b2c3d4",
  "task_id": "task_a1b2c3d4",
  "object": "video",
  "model": "minimax/minimax-h3-t2va",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1780000000,
  "updated_at": 1780000180,
  "content": {
    "url": "https://mzsjai.com/v1/video/generations/task_a1b2c3d4/content/video.mp4?uid=1&expires=1780086580&signature=...",
    "expires_at": 1780086580
  },
  "resolution": "768P",
  "ratio": "16:9",
  "duration": 5
}

content 只在任务成功且结果可用时出现。resolution、ratio 和 duration 只有平台能够获得对应信息时才出现，调用方不能依赖它们必定存在。当前 GET 响应不返回 usage，也不会用 0 伪造缺失的用量数据。

返回的 content.url 是有效期内可访问的签名地址，过期时间见 content.expires_at。也可以在当前 API Key 鉴权下使用 /v1/video/generations/{task_id}/content 下载。

失败响应

{
  "id": "task_a1b2c3d4",
  "task_id": "task_a1b2c3d4",
  "object": "video",
  "model": "minimax/minimax-h3-t2va",
  "status": "failed",
  "progress": 100,
  "created_at": 1780000000,
  "updated_at": 1780000045,
  "error": {
    "code": "task_failed",
    "message": "H3 generation failed"
  }
}

下载视频

任务状态变为 succeeded 后，可以直接使用查询响应中的 content.url，也可以调用 V2 下载路径：

curl -L "https://mzsjai.com/v1/video/generations/task_a1b2c3d4/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.mp4

下载接口可能返回重定向，因此命令行调用应使用 curl -L。

错误格式

请求校验、任务不存在或任务提交失败时，接口返回非 2xx 状态码，例如：

{
  "code": "invalid_request",
  "message": "last_frame requires first_frame",
  "type": "invalid_request_error",
  "data": null
}

常见错误包括：缺少模型、提示词或 duration；时长不在 4～15 秒；单独提交尾帧；首尾帧与参考素材混用；t2va 携带素材；ref2va 没有参考素材；保留原音时提交多个视频或提交静音视频；请求 2K、adaptive 或未支持的尺寸；模型暂时不可用；任务 ID 不存在。

从旧接口迁移

旧 /v1/videos 路由仍保留兼容，但会返回旧版 OpenAI Video 响应。新客户端应完整迁移，不要混用两套响应结构：

旧接口/字段	V2 接口/字段
`POST /v1/videos`	`POST /v1/video/generations`
`GET /v1/videos/{id}`	`GET /v1/video/generations/{id}`
`in_progress`	`running`
`completed`	`succeeded`
`content_url` 或 `metadata.url`	`content.url`
`images` 的隐式含义	`content[].role` 的明确角色

接口总览​

模型​

简单的文生视频请求示例​

当前能力边界​

提交任务​

请求参数​

content 格式​

分辨率和比例​

方式一：resolution + ratio​

方式二：size​

示例：文生视频​

示例：首帧图生视频​

示例：首帧和尾帧​

示例：多张参考图​

示例：参考视频​

示例：保留参考视频原音轨​

示例：参考音频​

H3 扩展参数​

旧字段兼容​

提交成功响应​

查询任务​

状态​

生成中响应​

成功响应​

失败响应​

下载视频​

错误格式​

从旧接口迁移​