视频生成

minimax-h3 / minimax-h3-max:文生视频、图生视频,带原生音频,最长 15 秒。异步任务接口:提交 → 轮询 → 下载。

先看这三点

视频生成不是对话接口。它是异步任务:先提交拿到任务号,隔几秒查一次状态,成功后从结果里拿下载地址。请求参数与模型官方一致,把地址和密钥换成本平台的即可。

这两个模型为定向开放:需要先联系管理员为账号开通,未开通时调用会返回 403 model_requires_grant。开通后现有密钥立即可用,不用重建。

minimax-h3 — 通用旗舰:768P / 2K,4~15 秒;支持文生、首尾帧图生、参考图 / 参考视频 / 参考音频,以及 768P → 2K 再生成、提示词增强
minimax-h3-max — 极速版:480P / 768P,5~15 秒;出片快一个数量级(768P 5 秒的片子通常一二十秒完成,minimax-h3 约需两分钟),目前支持文生与首尾帧图生
按成片秒数计费,任务成功才扣费;失败、超时、内容审核不通过都不收费。价格见定价页

第一步:提交任务

content 是一个数组,至少要有一个 text(提示词)。只有文字 = 文生视频,此时必须指定 ratio;带一张 first_frame 图 = 图生视频,ratio 写 adaptive 或不写。

resolution — minimax-h3:768P / 2K;minimax-h3-max:480P / 768P
duration — 整数秒。minimax-h3:4~15;minimax-h3-max:5~15
ratio — adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16;文生视频必填且不能是 adaptive
素材 — 图片 JPG / PNG / WEBP / HEIC,单张 ≤ 30 MB;视频 MP4 / MOV,单个 ≤ 50 MB;音频 WAV / MP3,单个 ≤ 15 MB;请求体总大小 ≤ 64 MB,大文件请用公网 URL
aigc_watermark — 是否在画面上加 AIGC 水印,默认 false
暂不支持 callback_url,请用下面的查询接口轮询

curl https://api.qiyuanapi.cc/v1/video_generation \
  -H "Authorization: Bearer $OPC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "content": [
      {"type": "text", "text": "清晨的窗台上,一只橘猫伸了个懒腰,镜头缓慢推进,电影感"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'

# 返回:{"task_id": "418220931455072991"}

第二步:轮询任务状态

用提交时拿到的 task_id 查询,建议每 5~10 秒查一次。status 依次是 queued(排队)→ running(生成中)→ succeeded / failed。

下载地址 24 小时内有效,请及时下载或转存到自己的存储;过期后查询结果里 content.url 为 null。任务只能用创建它的账号查询。

curl https://api.qiyuanapi.cc/v1/query/video_generation/418220931455072991 \
  -H "Authorization: Bearer $OPC_API_KEY"

# 成功时:
{
  "task": {
    "id": "418220931455072991",
    "model": "minimax-h3",
    "status": "succeeded",
    "task_type": "generation",
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "content": {"url": "https://api.qiyuanapi.cc/videos/xxxxxxxx.mp4"},
    "usage": {"total_seconds": 5, "input_seconds": 0, "output_seconds": 5, "input_image_count": 0}
  }
}

# 失败时 task.error 里有 code 与 message,失败不收费

完整示例(Python)

提交、轮询、下载一条龙。只依赖 requests。

import os, time, requests

BASE = "https://api.qiyuanapi.cc/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['OPC_API_KEY']}"}

task_id = requests.post(f"{BASE}/video_generation", headers=HEADERS, json={
    "model": "minimax-h3-max",
    "content": [{"type": "text", "text": "海边日落,延时摄影,云层流动"}],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
}, timeout=200).json()["task_id"]

while True:
    task = requests.get(f"{BASE}/query/video_generation/{task_id}", headers=HEADERS, timeout=30).json()["task"]
    if task["status"] in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(8)

if task["status"] == "succeeded":
    video = requests.get(task["content"]["url"], timeout=300)
    open("result.mp4", "wb").write(video.content)
    print("已保存 result.mp4,计费秒数:", task["usage"]["total_seconds"])
else:
    print("失败:", task.get("error"))

提示词增强与 2K 再生成(仅 minimax-h3)

两个都是同样的异步任务,提交后用同一个查询接口拿结果。

# 让模型先把你的描述(和素材)理解一遍,产出一段更适合生成的提示词;按 token 计费
curl https://api.qiyuanapi.cc/v1/h3_context_ir \
  -H "Authorization: Bearer $OPC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "content": [{"type": "text", "text": "一个关于咖啡店开业的 10 秒广告"}],
    "duration": 10,
    "ratio": "16:9"
  }'

# 查询结果里 task.content.prompt 就是增强后的提示词,拿它去提交 /video_generation

计费与限制

任务成功才扣费,金额 = 成片秒数 × 单价(按分辨率)+ 输入视频秒数 × 单价 + 输入图片张数 × 单价;明细见定价页该模型的「规格单价」
提交时会按这条任务可能的最高费用检查余额:余额(减去其它在途任务已占用的部分)不够会返回 402,任务不会创建。实际按用量结算,多占的部分任务结束即释放
每个账号同时进行的视频任务有上限,超出返回 429,等在途任务完成后再提交
任务提交后无法取消。客户端超时重试前,请先确认上一次是否已经拿到 task_id,避免重复下单
生成的视频文件内带有国家标准要求的 AI 生成内容隐式标识,请勿去除;对外传播时请按规定添加显式标识

常见报错

400 model_endpoint_mismatch — 用对话 / 生图接口调了视频模型,或用视频接口调了别的模型。视频模型只能走本页的接口
400 invalid_params — 参数不符合要求,message 里会指出是哪一项(如文生视频没写 ratio、时长超范围、该模型不支持的分辨率)
400 content_policy_violation — 提示词或素材未通过内容安全审核,调整后重试
402 quota_exceeded — 余额不足以覆盖本任务的最高预计费用
403 model_requires_grant — 账号未开通该模型,联系管理员
429 too_many_tasks / rate_limited — 在途任务已达上限或平台排队已满,按 Retry-After 等一会儿再提交
404 task_not_found — 任务号不存在,或不属于当前账号

curl https://api.qiyuanapi.cc/v1/video_generation \ -H "Authorization: Bearer $OPC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "content": [ {"type": "text", "text": "清晨的窗台上,一只橘猫伸了个懒腰,镜头缓慢推进,电影感"} ], "resolution": "768P", "duration": 5, "ratio": "16:9" }' # 返回:{"task_id": "418220931455072991"}

curl https://api.qiyuanapi.cc/v1/query/video_generation/418220931455072991 \ -H "Authorization: Bearer $OPC_API_KEY" # 成功时: { "task": { "id": "418220931455072991", "model": "minimax-h3", "status": "succeeded", "task_type": "generation", "resolution": "768P", "duration": 5, "ratio": "16:9", "content": {"url": "https://api.qiyuanapi.cc/videos/xxxxxxxx.mp4"}, "usage": {"total_seconds": 5, "input_seconds": 0, "output_seconds": 5, "input_image_count": 0} } } # 失败时 task.error 里有 code 与 message,失败不收费

import os, time, requests BASE = "https://api.qiyuanapi.cc/v1" HEADERS = {"Authorization": f"Bearer {os.environ['OPC_API_KEY']}"} task_id = requests.post(f"{BASE}/video_generation", headers=HEADERS, json={ "model": "minimax-h3-max", "content": [{"type": "text", "text": "海边日落,延时摄影,云层流动"}], "resolution": "768P", "duration": 5, "ratio": "16:9", }, timeout=200).json()["task_id"] while True: task = requests.get(f"{BASE}/query/video_generation/{task_id}", headers=HEADERS, timeout=30).json()["task"] if task["status"] in ("succeeded", "failed", "cancelled"): break time.sleep(8) if task["status"] == "succeeded": video = requests.get(task["content"]["url"], timeout=300) open("result.mp4", "wb").write(video.content) print("已保存 result.mp4,计费秒数:", task["usage"]["total_seconds"]) else: print("失败:", task.get("error"))

# 让模型先把你的描述(和素材)理解一遍,产出一段更适合生成的提示词;按 token 计费 curl https://api.qiyuanapi.cc/v1/h3_context_ir \ -H "Authorization: Bearer $OPC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "content": [{"type": "text", "text": "一个关于咖啡店开业的 10 秒广告"}], "duration": 10, "ratio": "16:9" }' # 查询结果里 task.content.prompt 就是增强后的提示词,拿它去提交 /video_generation