MiniMax H3 图生视频 (V2)

网关地址: https://open.ospreyai.cn（公网）模型: MiniMax-H3 鉴权: Authorization: Bearer sk-xxx（网关 new-api key）

概述

通过 Osprey 官方 MiniMax H3 V2 接口做图生视频：上传一张图作为首帧，配合提示词生成带音频的动态视频；也可同时提供首帧 + 尾帧，让模型生成两帧之间的自然过渡。MiniMax H3 原生支持音视频联合生成——输出 mp4 自带同步音频轨。任务异步执行：提交任务 → 轮询状态 → 下载结果。

bash

export GW="https://open.ospreyai.cn"
export API_KEY="sk-your-api-key"

接口清单

用途	方法	路径
创建视频生成任务	POST	`/v2/video_generation`
查询任务状态	GET	`/v2/query/video_generation/{task_id}`

提交任务后异步生成，需轮询查询接口直到 task.status=succeeded，再从 task.content.url 下载视频。

创建视频生成任务

POST /v2/video_generation
Content-Type: application/json
Authorization: Bearer sk-xxx

图生视频：content 含一个 text 项（prompt）+ 1～2 张 image_url（首帧 / 尾帧）。三种模式：仅首帧、仅尾帧、首尾帧。宽高比由输入图片决定，ratio 恒为 adaptive（传其他值会被忽略）。

1. 仅首帧

bash

curl -H "Authorization: Bearer $API_KEY" -X POST "$GW/v2/video_generation" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "A slow camera push-in, the subject begins to move naturally"},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/first.png"}, "role": "first_frame"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'

仅一张图且不填 role 时，默认按 first_frame 处理。

2. 仅尾帧

bash

curl -H "Authorization: Bearer $API_KEY" -X POST "$GW/v2/video_generation" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "The scene slowly resolves into this final frame, camera settling gently"},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/last.png"}, "role": "last_frame"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'

仅尾帧模式：尾帧作为视频结束画面，模型生成通向尾帧的过程。

3. 首帧 + 尾帧

bash

curl -H "Authorization: Bearer $API_KEY" -X POST "$GW/v2/video_generation" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "Create an 8-second smooth cinematic transition from the first frame to the last frame"},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/first.png"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/last.png"}, "role": "last_frame"}
    ],
    "resolution": "768P",
    "duration": 8,
    "ratio": "adaptive"
  }'

响应：

json

{
  "task_id": "task_TXFDbUO3PYGmhHhrQs4lVZDzlExjU66U",
  "id": "task_TXFDbUO3PYGmhHhrQs4lVZDzlExjU66U",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1787724354
}

记下返回的 task_id，用于查询任务状态和下载视频。

查询任务状态

GET /v2/query/video_generation/{task_id}
Authorization: Bearer sk-xxx

bash

curl -H "Authorization: Bearer $API_KEY" \
  "$GW/v2/query/video_generation/task_TXFDbUO3PYGmhHhrQs4lVZDzlExjU66U"

任务状态流转： queued（排队）→ running（运行中）→ succeeded/failed/cancelled

成功响应：

json

{
  "task": {
    "id": "task_TXFDbUO3PYGmhHhrQs4lVZDzlExjU66U",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1787724354,
    "updated_at": 1787724695,
    "content": {
      "url": "https://minimax-h3-ospreyai.oss-cn-hangzhou.aliyuncs.com/.../output.mp4?..."
    },
    "resolution": "768P",
    "duration": 5,
    "ratio": "1:1",
    "task_type": "generation",
    "modality": "video",
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 1,
      "total_tokens": 273890,
      "prompt_tokens": 13500,
      "completion_tokens": 260390
    }
  }
}

失败响应：

json

{
  "task": {
    "id": "task_xxx",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {"code": "1026", "message": "video description contains sensitive content"},
    "created_at": 1787724354,
    "updated_at": 1787724500
  }
}

仅支持查询最近 7 天内的任务。task_type 当前部署恒为 generation。视频地址在 task.content.url（OSS 预签名直链，有时效）。

下载结果

任务成功后，视频地址在 task.content.url（OSS 预签名直链，无需 Bearer token，有时效），用 curl -L 下载：

bash

curl -L "$VIDEO_URL" -o result.mp4

URL 失效后可重新查询任务获取新链接。

输出： MP4 视频（带音频），默认 768P / 比例跟随输入图 / 约 5 秒。

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，当前固定 `MiniMax-H3`
`content`	array	是	多模态输入数组，含 `text` + 1～2 张 `image_url`（首帧/尾帧至少给一张）
`resolution`	string	是	分辨率，可用值 `768P`、`2K`（当前网关仅支持 768P，2K 暂不可用）
`duration`	integer	是	视频时长（秒），取值 `5`～`15` 的整数
`ratio`	string	否	宽高比，图生视频恒为 `adaptive`（由输入图决定），传其他值会被忽略

content 组合

模式	content 组合
仅首帧	`text` + 1 张 `image_url`（`role=first_frame`，或单图不填默认首帧）
仅尾帧	`text` + 1 张 `image_url`（`role=last_frame`）
首帧 + 尾帧	`text` + 2 张 `image_url`（`role` 分别为 `first_frame`、`last_frame`）

content 元素

`type`	必填字段	说明
`text`	`text`	文本提示词（prompt），所有场景必填，单个 `text` 最多 7000 字符
`image_url`	`url`、`role`	图片，`role` 取 `first_frame`（首帧）或 `last_frame`（尾帧）；单图不填默认 `first_frame`

image_url 与多模态参考（reference_image/reference_video/reference_audio）互斥，不可混用。

媒体地址格式

image_url 的 url 字段支持：

公网 URL（http:// / https://）
mm_file://{file_id}（引用平台已有文件）
data:image/<格式>;base64,<Base64> data URI（<格式> 小写）

请求体总大小 ≤ 64 MB，Base64 会放大约 33%，大文件请用公网 URL，勿用 Base64。

输入图片限制

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

提示词技巧

用 <Picture 1> 指代首帧图片，模型会基于该图延展（如 The subject from <Picture 1> in its original scene...）
描述运镜为主：slow push-in / low-angle beauty shot / rotating in a slow orbit
可加音频提示，模型会生成同步音轨：Audio: deep pulsing sub-bass, sharp mechanical clicks...

Python 调用示例

python

import json, time, urllib.request, base64

GW = "https://open.ospreyai.cn"
API_KEY = "sk-your-api-key"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 本地图片转 data URI（大图建议先用 pic.ospreyai.cn 转公网 URL）
def image_data_uri(path):
    import mimetypes
    mime = mimetypes.guess_type(path)[0] or "image/png"
    b64 = base64.b64encode(open(path, "rb").read()).decode("ascii")
    return f"data:{mime};base64,{b64}"

# 提交（仅尾帧：尾帧作结束画面，模型生成通向尾帧的过程）
payload = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "The scene slowly resolves into this final frame, camera settling gently"},
        {"type": "image_url", "image_url": {"url": image_data_uri("ending.png")}, "role": "last_frame"},
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive",
}
req = urllib.request.Request(
    f"{GW}/v2/video_generation",
    data=json.dumps(payload).encode(),
    headers=HEADERS, method="POST",
)
task_id = json.loads(urllib.request.urlopen(req, timeout=30).read())["task_id"]

# 轮询
while True:
    r = urllib.request.Request(f"{GW}/v2/query/video_generation/{task_id}", headers=HEADERS)
    task = json.loads(urllib.request.urlopen(r, timeout=30).read())["task"]
    print(f"status={task['status']}")
    if task["status"] in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(10)

# 下载（task.content.url 公网直链，无需 token）
video_url = task["content"]["url"]
data = urllib.request.urlopen(video_url, timeout=180).read()
open("result.mp4", "wb").write(data)

错误码

HTTP	说明	常见原因
400	参数错误	`content` 缺少 `text`；图片格式/大小/尺寸超限；`resolution`/`duration` 取值非法
401	鉴权失败	API Key 错误/未传
402	余额不足	账户额度耗尽
422	敏感内容	prompt 或图片涉及敏感内容
429	触发限流	请求过频
500	服务端错误	网关或上游异常

错误体格式（Osprey 网关）：{"code": "...", "message": "...", "data": null}，上游错误信息可能嵌在 message 字符串内。

常见问题

问题现象	可能原因	解决方案
401 Unauthorized	API Key 错误/未传	检查 `Authorization: Bearer sk-xxx`
400 invalid_resolution	分辨率取值非法	用 `768P`
400 invalid_duration	duration 超出范围	取值 5～15 的整数
400 图片相关报错	格式/大小/尺寸超限	见输入图片限制；大图用公网 URL
400 content must include a non-empty text	缺少 prompt	`content` 必须含一个非空 `text` 项
首帧变形/拉伸	输入图比例与预期不符	图生视频 `ratio` 恒为 `adaptive`，由输入图决定，选比例合适的输入图
任务 failed	内容审核/参数非法	看 `task.error`，调整 prompt 或素材
任务长时间 running	排队或生成中	通常 3～8 分钟，调大轮询超时
下载 403/链接失效	`task.content.url` 过期	重新查询任务获取新链接并及时下载

更新日志

版本	日期	更新内容
v1.1.0	2026-08-27	下载改回 `task.content.url`（OSS 预签名直链，无需 token）；注明 2K 当前网关暂不支持，仅 768P 可用
v1.1.0	2026-08-27	新增仅尾帧模式（`role=last_frame` 单图），补全 content 组合表，Python 示例改用尾帧
v1.0.0	2026-08-26	重写为 V2 接口：`/v2/video_generation` + `/v2/query` + `/v1/videos/{task_id}/content` 下载，多模态 content 数组，支持首帧/首尾帧，输出带音频 mp4

MiniMax H3 图生视频 (V2) ​

概述 ​

接口清单 ​

创建视频生成任务 ​

1. 仅首帧 ​

2. 仅尾帧 ​

3. 首帧 + 尾帧 ​

查询任务状态 ​

下载结果 ​

请求参数 ​

content 组合 ​

content 元素 ​

媒体地址格式 ​

输入图片限制 ​

提示词技巧 ​

Python 调用示例 ​

错误码 ​

常见问题 ​

更新日志 ​

MiniMax H3 图生视频 (V2)

概述

接口清单

创建视频生成任务

1. 仅首帧

2. 仅尾帧

3. 首帧 + 尾帧

查询任务状态

下载结果

请求参数

content 组合

content 元素

媒体地址格式

输入图片限制

提示词技巧

Python 调用示例

错误码

常见问题

更新日志