视频生成

MoziaVerse 提供统一的异步视频生成 API。无论底层使用哪个模型，调用流程均为：提交任务、查询状态、下载结果。

快速开始

基础地址：

https://mzsjai.com

所有请求都必须携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

请只在服务端保存 API Key，不要将其写入浏览器代码、公开仓库或日志。

1. 提交任务

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": 5,
    "resolution": "768P",
    "ratio": "16:9"
  }'

提交成功后请保存返回的 task_id：

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

2. 查询状态

curl 'https://mzsjai.com/v1/video/generations/task_a1b2c3d4' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}"

建议每 5～10 秒查询一次，直到状态变为 succeeded 或 failed。

3. 下载结果

任务成功后，可以访问响应中的 content.url，也可以通过统一下载接口获取文件：

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

接口一览

方法	路径	说明
POST	/v1/video/generations	提交视频生成任务
GET	/v1/video/generations/{task_id}	查询任务状态与结果
GET	/v1/video/generations/{task_id}/content	下载生成的视频

/v1/videos 及其查询、下载路由仅用于兼容旧客户端。新接入请使用 /v1/video/generations，不要混用两套响应结构。

选择模型

模型决定可使用的输入素材与生成能力。当前推荐：

模型 ID	能力	输入要求
minimax/minimax-h3-t2va	文生视频	仅提示词，不可携带素材
minimax/minimax-h3-fl2va	文生视频、首帧或首尾帧生成	可不传图片，或传首帧及可选尾帧
minimax/minimax-h3-ref2va	参考素材生成	至少提供一项参考图、视频或音频
minimax/minimax-h3-2k	2K 视频生成	具体能力与参数以模型目录为准

新接入的纯文本生成推荐使用 minimax/minimax-h3-t2va。模型列表、可用状态和计费可能调整，请以控制台模型目录为准。

H3 模型的完整素材角色、扩展参数和兼容说明请参阅 MiniMax H3。

Seedance 2.0 的首尾帧、参考素材、上传和兼容说明请参阅 Seedance 2.0。

提交视频生成任务

POST /v1/video/generations
Content-Type: application/json

通用参数

参数	类型	必填	说明
model	string	是	控制台模型目录中的完整模型 ID
prompt	string	条件必填	文本提示词；与 content 中的文本至少提供一种
content	array	否	文本及图片、视频或音频素材
duration	integer	是	视频时长，当前 H3 模型支持 4～15 秒
resolution	string	否	清晰度，例如 768P
ratio	string	否	宽高比，例如 16:9、9:16 或 1:1
size	string	否	兼容旧客户端的尺寸字段；不要与 resolution、ratio 混用
seed	integer	否	随机种子，固定后有助于复现
preserve_reference_audio	boolean	否	是否保留唯一参考视频的原音轨，默认 false
metadata	object	否	模型专属扩展参数

如果 prompt 与 content 中的文本同时存在，顶层 prompt 优先。

素材格式

文本：

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

图片：

{
  "type": "image_url",
  "role": "first_frame",
  "image_url": {"url": "https://example.com/start.jpg"}
}

视频或音频使用相同结构：

{
  "type": "video_url",
  "role": "reference_video",
  "video_url": {"url": "https://example.com/reference.mp4"}
}

type	role	说明
image_url	first_frame	视频首帧
image_url	last_frame	视频尾帧，必须同时提供首帧
image_url	reference_image	人物、主体、服装、风格或场景参考
video_url	reference_video	动作、身份或场景参考
audio_url	reference_audio	语义、节奏或氛围参考

素材必须是模型服务可访问的 HTTP(S) URL。当前接口不接受 Data URL、原始 Base64、本地文件路径或 multipart 文件上传。

文生视频示例

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": 5,
    "resolution": "768P",
    "ratio": "16:9",
    "seed": 20260827
  }'

图生视频示例

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-ref2va",
    "content": [
      {
        "type": "text",
        "text": "让参考图中的人物在海边自然行走，保持人物身份一致"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {"url": "https://example.com/person.jpg"}
      }
    ],
    "duration": 8,
    "resolution": "768P",
    "ratio": "9:16"
  }'

查询任务

GET /v1/video/generations/{task_id}

状态	说明
queued	已创建或正在排队
running	正在生成
succeeded	生成成功
failed	生成失败
cancelled	已取消
expired	已过期
unknown	状态暂未同步，通常应继续轮询

成功响应示例：

{
  "id": "task_a1b2c3d4",
  "task_id": "task_a1b2c3d4",
  "object": "video",
  "model": "minimax/minimax-h3-t2va",
  "status": "succeeded",
  "progress": 100,
  "content": {
    "url": "https://mzsjai.com/v1/video/generations/task_a1b2c3d4/content/video.mp4?signature=...",
    "expires_at": 1780086580
  }
}

content.url 是有时效的签名地址，请及时下载。resolution、ratio、duration 和 usage 等字段只在平台获得相应信息时返回，客户端不应假设它们始终存在。

错误处理

错误响应示例：

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

状态码	说明	建议
400	参数、素材或模型不匹配	修正请求后重试
401	API Key 缺失或无效	检查鉴权配置
404	任务不存在	检查 task_id 和 API Key
429	额度不足或触发限流	检查余额并降低请求频率
500	生成失败	保存请求 ID 后联系平台
502/503/504	服务暂不可用或超时	使用指数退避进行有限重试

视频生成耗时较长。客户端应设置合理的总等待时间，并对查询请求使用指数退避和最大重试次数。