MiniMax H3 参考生视频 (V2)

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

概述

通过 Osprey 官方 MiniMax H3 V2 接口做多模态参考生视频：上传至少 2 张参考图，并可选附加参考视频、参考音频，模型以它们为视觉/动作/声音参考生成全新视频（非首帧延展，而是参考角色/场景/风格/动作/声音再生）。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）+ 参考素材，参考项用 role 标注类型。ratio 可选，默认 adaptive。

1. 仅参考图（至少 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": "Use reference image 1 for the character and reference image 2 for the environment. Create a cinematic scene."},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/character.png"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/scene.png"}, "role": "reference_image"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'

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": "Use the reference images for the character and environment, follow the motion rhythm of the reference video, and use the reference audio as the voice style."},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/character.png"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "https://pic.ospreyai.cn/i/2026/08/26/scene.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/motion-reference.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/voice-reference.mp3"}, "role": "reference_audio"}
    ],
    "resolution": "768P",
    "duration": 8,
    "ratio": "adaptive"
  }'

响应：

json

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

记下返回的 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_xxxxxxxxxxxxxxxxxxxxx"

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

成功响应：

json

{
  "task": {
    "id": "task_xxxxxxxxxxxxxxxxxxxxx",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1787730224,
    "updated_at": 1787730569,
    "content": {
      "url": "https://minimax-h3-ospreyai.oss-cn-hangzhou.aliyuncs.com/.../output.mp4?..."
    },
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video",
    "usage": {
      "total_seconds": 5,
      "input_seconds": 6,
      "output_seconds": 5,
      "input_image_count": 2,
      "input_audio_seconds": 6,
      "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": 1787730224,
    "updated_at": 1787730400
  }
}

仅支持查询最近 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 / 比例 adaptive / 约 5 秒。

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，当前固定 `MiniMax-H3`
`content`	array	是	多模态输入数组，含 `text` + 参考素材
`resolution`	string	是	分辨率，可用值 `768P`、`2K`（当前网关仅支持 768P，2K 暂不可用）
`duration`	integer	是	视频时长（秒），取值 `5`～`15` 的整数
`ratio`	string	否	宽高比，默认 `adaptive`；也可指定 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`

content 元素

`type`	必填字段	说明
`text`	`text`	文本提示词（prompt），所有场景必填，单个 `text` 最多 7000 字符
`image_url`	`url`、`role`	参考图片，`role` 固定 `reference_image`；≤ 9 张
`video_url`	`url`、`role`	参考视频，`role` 固定 `reference_video`；≤ 3 个
`audio_url`	`url`、`role`	参考音频，`role` 固定 `reference_audio`；≤ 3 个

参考生视频与图生视频（first_frame/last_frame）互斥，不可混用。混合参考素材总数（参考图 + 参考视频 + 参考音频）≤ 12 个。

媒体地址格式

各 url 字段支持：

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

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

输入媒体限制

图片 image_url：

项	限制
格式	JPG、JPEG、PNG、WEBP、HEIC、HEIF
单文件大小	≤ 30 MB
宽高范围	[256, 5760] px
长宽比（宽/高）	[0.4, 2.5]
数量	参考图 ≤ 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

提示词技巧

用 <Picture 1> / <Picture 2> 指代参考图（建议，否则参考内容可能不出现）
说明各参考素材的用途：Reference image 1 defines the character appearance. Reference image 2 defines the environment.
逐镜头分镜：CUT 1: ...、CUT 2: ...
可加音频提示，模型会生成同步音轨：Audio: wind, footsteps, low score...

Python 调用示例

python

import json, time, urllib.request, base64, mimetypes

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):
    mime = mimetypes.guess_type(path)[0] or "image/png"
    b64 = base64.b64encode(open(path, "rb").read()).decode("ascii")
    return f"data:{mime};base64,{b64}"

# 提交（2 张参考图）
payload = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "Use reference image 1 for the character and reference image 2 for the environment."},
        {"type": "image_url", "image_url": {"url": image_data_uri("character.png")}, "role": "reference_image"},
        {"type": "image_url", "image_url": {"url": image_data_uri("scene.png")}, "role": "reference_image"},
    ],
    "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 素材相关报错	格式/大小/时长/数量超限	见输入媒体限制；参考素材总数 ≤ 12，参考图 ≤ 9、参考视频 ≤ 3、参考音频 ≤ 3
400 content must include a non-empty text	缺少 prompt	`content` 必须含一个非空 `text` 项
参考图角色没出现	提示词没引用 `<Picture N>`	在 prompt 里用 `<Picture 1>`/`<Picture 2>` 指代参考图
任务 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.0.0	2026-08-26	重写为 V2 接口：`/v2/video_generation` + `/v2/query` + `/v1/videos/{task_id}/content` 下载，多模态 content 数组，支持参考图/视频/音频，输出带音频 mp4

MiniMax H3 参考生视频 (V2) ​

概述 ​

接口清单 ​

创建视频生成任务 ​

1. 仅参考图（至少 2 张） ​

2. 参考图 + 参考视频 + 参考音频 ​

查询任务状态 ​

下载结果 ​

请求参数 ​

content 元素 ​

媒体地址格式 ​

输入媒体限制 ​

提示词技巧 ​

Python 调用示例 ​

错误码 ​

常见问题 ​

更新日志 ​

MiniMax H3 参考生视频 (V2)

概述

接口清单

创建视频生成任务

1. 仅参考图（至少 2 张）

2. 参考图 + 参考视频 + 参考音频

查询任务状态

下载结果

请求参数

content 元素

媒体地址格式

输入媒体限制

提示词技巧

Python 调用示例

错误码

常见问题

更新日志