Skip to content

MiniMax H3 文生视频 (V2) ​

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

概述 ​

通过 Osprey 官方 MiniMax H3 V2 接口做文生视频。MiniMax H3 原生支持音视频联合生成——输出 mp4 自带同步音频轨(环境音/配乐/音效),无需额外 TTS。任务异步执行:提交任务 → 轮询状态 → 下载结果。

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),ratio 必填且不能为 adaptive。

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 bird spreading its wings and flying away over a misty lake at dawn"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'

响应:

json
{
  "task_id": "task_l2sqtkJRicfdXsL8NDfPqhiWRJwGUJ9f",
  "id": "task_l2sqtkJRicfdXsL8NDfPqhiWRJwGUJ9f",
  "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_l2sqtkJRicfdXsL8NDfPqhiWRJwGUJ9f"

任务状态流转: queued(排队)→ running(运行中)→ succeeded/failed/cancelled

成功响应:

json
{
  "task": {
    "id": "task_l2sqtkJRicfdXsL8NDfPqhiWRJwGUJ9f",
    "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": 0,
      "output_seconds": 5,
      "input_image_count": 0,
      "total_tokens": 97645,
      "prompt_tokens": 0,
      "completion_tokens": 97645
    }
  }
}

失败响应:

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 / 16:9 / 约 5 秒。

请求参数 ​

参数类型必填说明
modelstring是模型名称,当前固定 MiniMax-H3
contentarray是多模态输入数组,文生视频仅含一个 text 项
resolutionstring是分辨率,可用值 768P、2K
durationinteger是视频时长(秒),取值 4~15 的整数
ratiostring是宽高比,文生视频必填且不能为 adaptive;可用值 21:9、16:9、4:3、1:1、3:4、9:16

content 元素 ​

type必填字段说明
texttext文本提示词(prompt),所有场景必填,单个 text 最多 7000 字符

媒体输入项(image_url/video_url/audio_url)见 图生视频、参考生视频。

媒体地址格式 ​

image_url/video_url/audio_url 的 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]
数量首帧 ≤ 1、尾帧 ≤ 1、参考图 ≤ 9

视频 video_url(仅参考场景): MP4/MOV;≤ 50 MB;≤ 3 个;单段 [2, 15] s,总时长 ≤ 15 s。

音频 audio_url(仅参考场景): WAV/MP3;≤ 15 MB;≤ 3 个;单段 [2, 15] s,总时长 ≤ 15 s。

提示词技巧 ​

MiniMax H3 的文本编码器基于 Qwen3-VL,支持长篇分镜脚本,可包含:

  • 整体风格 + 场景概述
  • 逐镜头分镜([0s-1.5s] Shot 1: ...)
  • 运镜、光影、质感描述
  • 音频提示(Audio: wind, footsteps, low score...)——模型会据此处生成同步音轨
Realistic live-action cinematic look, action movie trailer...
Scene overview: ...
Storyboard (each shot a separate scene, rapid cuts):
[0s-1.5s] Shot 1: ...
[1s-2.5s] Shot 2: ...
Audio: wind, rapid footsteps, city ambience, low score underneath...

Python 调用示例 ​

python
import json, time, urllib.request

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

# 提交
payload = {
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "A bird spreading its wings and flying away"}],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
}
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;ratio 用了 adaptive;resolution/duration 取值非法
401鉴权失败API Key 错误/未传
402余额不足账户额度耗尽
422敏感内容prompt 涉及敏感内容
429触发限流请求过频
500服务端错误网关或上游异常

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

常见问题 ​

问题现象可能原因解决方案
401 UnauthorizedAPI Key 错误/未传检查 Authorization: Bearer sk-xxx
400 invalid_resolution分辨率取值非法用 768P 或 2K
400 invalid_durationduration 超出范围取值 4~15 的整数
400 content must include a non-empty text缺少 promptcontent 必须含一个非空 text 项
400 ratio adaptive 文生视频不可用文生视频 ratio 用了 adaptive用具体比例,如 16:9
任务 failed内容审核/参数非法看 task.error,调整 prompt
任务长时间 running排队或生成中通常 3~8 分钟,调大轮询超时
下载 403/链接失效task.content.url 过期重新查询任务获取新链接并及时下载

更新日志 ​

版本日期更新内容
v1.2.02026-09-28新增 2K 分辨率支持(与 768P 并列可选);duration 最短时长由 5s 放宽至 4s
v1.1.02026-08-27下载改回 task.content.url(OSS 预签名直链,无需 token);注明 2K 当前网关暂不支持,仅 768P 可用
v1.0.02026-08-26重写为 V2 接口:/v2/video_generation + /v2/query + /v1/videos/{task_id}/content 下载,多模态 content 数组,输出带音频 mp4

AI API Gateway Documentation