AI API Gateway

Appearance

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（当前网关仅支持 768P，2K 暂不可用）
durationinteger是视频时长（秒），取值 5～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 非 768P（2K 当前不可用）；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
400 invalid_durationduration 超出范围取值 5～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.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