海螺 Hailuo API 怎么用？MiniMax H3 的 Python 调用和三种视频模式实测

海螺 API 就是 MiniMax 的视频 API，现在的模型是 MiniMax H3（MiniMax-H3），是 Hailuo 01、Hailuo 02 之后的下一代。每次调用都是异步的：创建任务、轮询、下载 MP4。2026 年 10 月 26 日，我们用三种模式各生成了一段 5 秒 768P 的片段，每段 35 到 42 秒出片，都带声音。

简短回答

• 模型： MiniMax 自家 API 上是 MiniMax-H3，2026 年 7 月 31 日发布（release notes）；OmniaKey 上的 id 是 minimax-h3，文生视频、图生视频、参考生视频共用一个（视频文档）。
• 要设的： resolution 填 "768P" 或 "2K"（必填），duration 从 4 到 15 的整数秒，aspect_ratio 比例（视频文档）。
• 价格： MiniMax 官方价目表上 768P 每秒 $0.08，5 秒就是 $0.40，2K 每秒 $0.13（定价页，2026 年 10 月 26 日核对）；OmniaKey 的价格见 模型页。
• 耗时和声音： 每段 35 到 42 秒，自带立体声；V2 的创建文档里没有关闭声音的开关（创建文档）。

有没有官方的海螺 API？

有。MiniMax 在 platform.minimax.io 上提供，现在的视频模型是 MiniMax H3，API id 是 MiniMax-H3（模型页，2026 年 10 月 26 日核对）。

MiniMax 的发布公告把 H3 称作 Hailuo 01、Hailuo 02 之后的下一代（发布公告）。较早的模型在 API 里还能用，叫 MiniMax-Hailuo-2.3 和 MiniMax-Hailuo-02（V1 文档）。

名字有好几种写法：MiniMax 文档写 "MiniMax H3"，API 文档的描述写 "Hailuo-03"（创建文档），海螺 AI 应用写 "Hailuo 3.0"（应用）。发布公告让人去那个应用里试。"Hailuo 3" 不是官方名字。

密钥在 Account > API Keys 里建，按量付费（API FAQ）。视频资源包覆盖的是较早的模型，暂时不含 H3（定价页）。

MiniMax 自家的四个型号（创建文档）：

直接调 MiniMax 自己的 API，分三步（视频指南）：

• POST https://api.minimax.io/v2/video_generation 返回 task_id（创建文档）。
• 轮询 GET /v2/query/video_generation/{task_id}，到 succeeded 后下载 content.url（查询文档）。
• 只能查最近 7 天的任务，下载链接有时效，但 MiniMax 没写具体多久（查询文档）。

V1 那条线（Hailuo 2.3 和 02）把任务 id 放在 ?task_id= 里，不在路径上，两条流程别弄混（V1 文档）。

OmniaKey 卖的是 MiniMax H3 的 API 接入，所以我们的例子都从它这里跑。流程一样：POST https://api.omniakey.com/v1/media/tasks 带上 Idempotency-Key 头，返回 202 和一个 id，然后 GET /v1/media/tasks/{id}（媒体概览）；一个模型 id minimax-h3 覆盖三种任务（视频文档）。同一套流程也在 Grok Imagine Video API 教程里。所有价格都是 MiniMax 官方价。

能设哪些参数？

• resolution 必填；填 1080P 和 4K 会直接报 400 model_price_error，任务都建不出来（视频文档）。MiniMax 的 V2 API 里 H3 也没有 1080P（创建文档）。我们三种模式都跑 768P，2K 没测。
• duration 是 4 到 15 的整数秒（视频文档）；MiniMax-H3-Max 最短 5 秒，填 4 会报 2013（创建文档）。
• aspect_ratio 支持 adaptive、16:9、9:16、1:1、4:3、3:4、21:9（视频文档）。MiniMax 那边文生视频必须给具体比例，图生视频跟着图片的形状走（创建文档）。我们的图生视频没填比例，成片保持了原图的形状，1376×768。
• input.media[] 里，图生视频用 first_frame 加可选的 last_frame；参考生视频用 reference_image、reference_video 或 reference_audio。两类不能混，音频参考还要配一张图或一段视频（视频文档）。每一项是 type 加 url，可以填公网 HTTPS 链接或 data URI；OmniaKey 限制整个请求不超过 1 MiB（含 Base64，媒体概览），所以脚本发的是 1024 像素的 JPEG。
• 提示词放在 input.prompt（视频文档），V2 最多 7,000 字符（视频指南）。想要什么声音也写进去。

怎么用 Python 调用海螺 API？

需要 Python 3 和 requests，密钥放在环境变量里。

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

唯一的参数是 t2v、i2v 或 r2v；需要图片的那两次会从同一个目录读 bicycle.jpg 或 robot.jpg。

下面是我们跑的脚本，一字未改：

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

2026 年 10 月 27 日的输出：

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

三次从开始到存盘用了 47 到 60 秒。

任务 id 要留着：任务慢不代表失败，接着轮询同一个 id，不要重新提交（媒体概览）。签名下载链接大约有效一小时，任务记录留 24 小时，所以要么马上存下来，要么重新轮询拿一个新链接；下载走签名，不用带密钥。

三种模式实测结果

下面三段片子是 2026 年 10 月 26 日三个任务跑出来的，请求体就是脚本里那些。

每一段都是 MP4，H.264，24 fps，5.17 秒，立体声 AAC，32 kHz；返回的 usage 里写着 output_seconds: 5。

文生视频：街头鼓手

提示词就是脚本里的 DRUMMER。

我们看到的：

• 夜里的人行道是湿的，路面映着红蓝霓虹，旁边停着车，一个穿黑色连帽外套的人俯身敲几只倒扣的蓝色塑料桶，兜帽一直遮着脸。
• 镜头从全景推到双手、鼓棒和桶面的特写，背后有人打着伞走过。
• 霓虹灯上的字母拼不成真的单词。鼓点越到后面越重，雨声却听不出来。

可以改的地方：想看到脸就写 "hood down, face visible"；想要雨声，就把雨单独写进声音描述。

图生视频：第一帧保持不变

第一帧是我们用 Nano Banana 2.1 做的静态图，提示词是 BICYCLE，只描述动作。

我们看到的：

• 第一帧和原图一样：红色自行车、黄色灰泥墙、百叶窗、盆栽。
• 镜头推进到一篮白色雏菊占满画面，自行车和墙的形状没变。
• 我们看过的画面里没有花瓣落下。声音是一段慢速钢琴独奏，可提示词里根本没提声音和音乐。

可以改的地方：只写动作和声音，画面的样子原图已经定了；成片会沿用原图的形状，所以想要什么比例，就先把原图做成什么比例。

参考生视频：一张图记住角色

参考图只有一张，是我们用 Nano Banana 2.1 做的小橙色机器人，提示词是 ROBOT。

我们看到的：

• 还是那个机器人：橙色圆身体、圆圆的蓝色玻璃眼、顶着小球的短天线、头侧一个圆盘；场景换成了阳光下的阳台，摆着花草盆栽。
• 它拿着红色洒水壶浇水，水流大约 1 秒时出现，镜头缓缓横移。
• 声音是流水和溅水，比水流早一点开始，没有音乐。

可以改的地方：角色本身不用改。想让几段片子里都是同一个角色，每次都用同一张参考图。

声音：写进提示词，否则 H3 自己挑

提示词没写声音时，H3 自己挑了：机器人配了跟浇水对得上的水声，自行车配了一段慢速钢琴。想要什么声音，就写进提示词。V2 的创建文档里没有关掉声音的开关（创建文档），要无声的片子，就事后去掉音轨：

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

这样只留 H.264 画面，还是 5.17 秒，不重新编码。

会遇到哪些报错？

报错有两个来源：OmniaKey 的任务接口，以及直接调 MiniMax 时的它自己的接口。

• 400 missing_idempotency_key：没带 Idempotency-Key 头。补上。
• 409 idempotency_key_reused：同一个 key 换了请求体。每个任务一个新 key。
• 400 model_price_error：用了 1080P 或 4K。改成 768P 或 2K。
• 400 invalid_request：请求体或参数不对。按参数表检查。
• 403 model_not_allowed：这个 key 没有该模型权限。查密钥权限。
• 503 no_available_channel：模型暂时不可用。稍后重试。
• provider_submit_uncertain：提交时被拒。提示词放 input.prompt，检查素材。
• 任务 failed：生成失败。看 error。

失败或取消的任务会自动退款（媒体概览）。直接调 MiniMax 时（错误码，2026 年 10 月 26 日核对）：

• MiniMax 会同时给真实的 HTTP 状态码，比如 401 配 1004、400 配 2013（创建文档）。
• H3 的 V2 API 限制每分钟 300 个请求、同时 30 个任务（限流说明）。

海螺 API 多少钱？

MiniMax 按输出视频的秒数计费，单价看型号和分辨率（定价页，2026 年 10 月 26 日核对）：

按这个价：768P 5 秒 $0.40，2K 10 秒 $1.30，2K 15 秒 $1.95。

• 输入图片每个任务前 5 张免费（Max 是 2 张），多出来的在 H3 上每张 $0.04，音频输入免费。输入视频按秒计费，Max 上输入一秒（768P $0.143）比输出一秒还贵。同一个模型同一档分辨率，三种任务价格一样。
• H3 只能按量付费，视频资源包不覆盖。海螺 AI 应用套餐里按秒折算的数字是应用积分，不是 API 价格（应用）。
• MiniMax 国内站是另一套人民币价目表，别按汇率换算（国内定价，2026 年 10 月 26 日核对）。
• OmniaKey 上视频任务在创建时按输出秒数扣费，失败或取消会自动退款（媒体概览）。

OmniaKey 现在的价格看 MiniMax H3 模型页，请求格式看 视频 API 文档。

国内怎么用

MiniMax 国内站（platform.minimax.cn，2026 年 10 月 26 日核对）按人民币计价：H3 768P 每秒 ¥0.50，2K 每秒 ¥0.80，超出免费额度的输入图片每张 ¥0.20。它是另一套价目表，不是国际站换算过来的；国内站的视频资源包同样暂不支持 H3，要用按量付费 API。

OmniaKey 支持人民币直充（支付宝、微信支付），一个 key 就能调用 MiniMax H3 和其它视频模型，具体见 MiniMax H3 模型页。

常见问题

海螺 API 免费吗？

MiniMax 自家 API 不免费：定价页、快速开始和 FAQ 里都没有 H3 的免费试用或额度（2026 年 10 月 26 日核对）。免费的部分只有每个任务前 5 张输入图片和音频输入（定价页）。应用积分不能当 API 额度用。

Hailuo 2.3 和 MiniMax H3 有什么区别？

Hailuo 2.3 走 V1，时长 6 秒或 10 秒，最高 1080P，按条计费：MiniMax 官方价 6 秒 768P 一条 $0.28（定价页、V1 文档）。H3 走 V2，4 到 15 秒，768P 或 2K，按秒计费，自带立体声（创建文档、模型页）。两个都还在售（模型 FAQ）。

MiniMax H3 Max 是什么？

它是 MiniMax 和 fal.ai 联合发布的版本，由 fal.ai 在 H3 上后训练，专门优化速度（视频指南）。480P 或 768P，5 到 15 秒；extra.prompt_expansion_mode 有 disabled、balanced（默认）和 quality 三档（创建文档）。它支不支持参考素材，MiniMax 自己的页面说法不一致：视频指南和模型 FAQ 只列了文生视频、图生视频，创建文档和定价页还列了参考。

能自己部署 MiniMax H3 吗？

可以，但有地区限制。权重在 Hugging Face 的 MiniMaxAI/MiniMax-H3 和 GitHub 的 MiniMax-AI/MiniMax-H3，许可协议是 MiniMax H3 Community License Agreement，属于自定义许可（Hugging Face、GitHub）。按 MiniMax 本地部署指南，截至 2026 年 8 月 26 日复核的那版许可，美国、欧盟、英国和韩国属于排除地区，需要单独授权（本地部署指南）。

更新记录

2026 年 10 月 27 日：第一版，片段生成于 2026 年 10 月 26 日。