Hailuo API: MiniMax H3 на Python и 3 режима видео в тесте

Hailuo API — это видео API от MiniMax, и его текущая модель — MiniMax H3 (MiniMax-H3), поколение после Hailuo 01 и 02. Любой вызов асинхронный: создать задачу, опросить её, скачать MP4. 26 октября 2026 года наши клипы длиной 5 секунд в 768P во всех трёх режимах делались от 35 до 42 секунд, и каждый пришёл со звуком.

Коротко

• Модель: MiniMax-H3 в API MiniMax, объявлена 31 июля 2026 года (release notes); minimax-h3 в OmniaKey, один id на три типа задач (документация по видео).
• Что задавать: resolution (обязательно) со значением "768P" или "2K", duration от 4 до 15 целых секунд, aspect_ratio (документация по видео).
• Цена: $0.08 за секунду в 768P, $0.40 за 5 секунд, $0.13 в 2K, это прайс-лист MiniMax (цены, проверено 26 октября 2026 года); тариф OmniaKey указан на странице модели.
• Время и звук: от 35 до 42 секунд на клип, у всех стереозвук; в справочнике создания V2 нет переключателя, который отключает звук (справочник создания).

Есть ли официальный Hailuo API?

Есть. MiniMax держит его на platform.minimax.io, и текущая модель там — MiniMax H3 с id MiniMax-H3 (страница моделей, проверена 26 октября 2026 года).

В анонсе MiniMax описывает H3 как поколение после Hailuo 01 и Hailuo 02 (анонс). Старые модели по-прежнему доступны в API как MiniMax-Hailuo-2.3 и MiniMax-Hailuo-02 (справочник V1).

Имя меняется от страницы к странице. В документации MiniMax написано «MiniMax H3», в описании модели в API — «Hailuo-03» (справочник создания), а в приложении Hailuo AI, куда анонс отправляет пробовать, — «Hailuo 3.0» (приложение). «Hailuo 3» официальным именем не является.

Ключ создаётся в Account > API Keys, оплата идёт по факту использования (FAQ по API). Видеопакеты MiniMax рассчитаны на старые модели и H3 не покрывают (цены).

У MiniMax четыре варианта H3 (справочник создания):

В собственном API MiniMax вызов состоит из трёх шагов (руководство по видео):

• 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 продаёт доступ к API MiniMax H3, поэтому примеры ниже шли через него. Схема та же: POST https://api.omniakey.com/v1/media/tasks с заголовком Idempotency-Key возвращает 202 и id, дальше вы опрашиваете GET /v1/media/tasks/{id} (обзор media). Эта же схема работает для Grok Imagine Video в руководстве по Grok Imagine Video API. Все цены ниже — прайс-лист MiniMax.

Какие параметры можно задать?

• resolution обязателен; 1080P и 4K дают ошибку 400 model_price_error (документация по видео), и в V2 для H3 нет 1080P (справочник создания). Все три режима шли в 768P, 2K мы не проверяли.
• duration — от 4 до 15 целых секунд (документация по видео); MiniMax-H3-Max начинается с 5 и отклоняет 4 (справочник создания).
• aspect_ratio принимает adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 или 21:9 (документация по видео). В API MiniMax режиму текста в видео нужно фиксированное соотношение, а изображение в видео следует форме картинки (справочник создания). В нашем прогоне изображения в видео мы не указали соотношение, и клип сохранил форму исходной картинки, 1376×768.
• input.media[] принимает first_frame и необязательный last_frame для изображения в видео либо reference_image, reference_video и reference_audio для референса в видео. Два вида не смешиваются, а аудиореференсу нужен референс изображения или видео рядом (документация по видео). Каждый элемент — это type и url, то есть либо публичная ссылка HTTPS, либо data URI. OmniaKey ограничивает весь запрос 1 MiB вместе с Base64 (обзор media), поэтому скрипт отправляет JPEG размером 1024 пикселя.
• Промпт лежит в input.prompt (документация по видео), до 7,000 символов (руководство по видео). Нужный звук тоже описывается там.

Как вызвать Hailuo API из Python?

Нужны 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",
    )

Вывод 27 октября 2026 года:

$ 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 вместо повторной отправки (обзор media). Подписанная ссылка на скачивание живёт около часа, а запись задачи — 24 часа, так что либо сохраните файл сразу, либо опросите задачу снова ради свежей ссылки. Само скачивание ключа API не требует.

Что вернули три режима

Три клипа вышли из трёх задач 26 октября 2026 года, с теми же телами запросов, что в скрипте.

Каждый клип был 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 секунды и без перекодирования.

Какие ошибки встретятся?

Ошибки приходят из API задач OmniaKey, а при прямом вызове — от MiniMax.

• 400 missing_idempotency_key: Нет заголовка Idempotency-Key. Добавить его.
• 409 idempotency_key_reused: Тот же ключ, новое тело. Новый ключ на каждую задачу.
• 400 model_price_error: 1080P или 4K. Взять 768P или 2K.
• 400 invalid_request: Неверное тело или параметр. Проверить параметры.
• 403 model_not_allowed: У ключа нет этой модели. Проверить доступ ключа.
• 503 no_available_channel: Модель сейчас недоступна. Повторить позже.
• provider_submit_uncertain: Отказ на отправке. Использовать input.prompt, проверить материалы.
• Задача failed: Генерация не удалась. Прочитать error.

Проваленная или отменённая задача возвращает деньги (обзор media). В собственном API MiniMax (коды ошибок, проверено 26 октября 2026 года):

• MiniMax присылает с каждым кодом соответствующий статус HTTP, например 401 с 1004 и 400 с 2013 (справочник создания).
• H3 в V2 допускает 300 запросов в минуту и 30 одновременно работающих задач (лимиты).

Сколько стоит Hailuo API?

MiniMax считает H3 по секундам выходного видео, в зависимости от варианта и разрешения (страница цен, проверена 26 октября 2026 года):

По этим ценам 5 секунд в 768P стоят $0.40, 10 секунд в 2K — $1.30, 15 секунд в 2K — $1.95.

• Первые 5 входных изображений на задачу бесплатны (2 в Max), каждое следующее стоит $0.04 в H3, аудиовход бесплатен. Входное видео считается по секундам, и в Max входная секунда ($0.143 в 768P) дороже выходной. При том же варианте и разрешении все три типа задач стоят одинаково.
• H3 работает только по факту использования, видеопакеты MiniMax его не покрывают. Секундные цифры в тарифах приложения Hailuo AI — это кредиты приложения, а не цены API (приложение).
• У китайской платформы MiniMax свой прайс-лист в юанях, поэтому не пересчитывайте один в другой (цены в Китае, проверены 26 октября 2026 года).
• В OmniaKey видео-задача списывается по выходным секундам при создании, а проваленная или отменённая задача возвращает деньги (обзор media).

Текущий тариф OmniaKey указан на странице модели MiniMax H3, форма запроса — в документации по видео API.

Частые вопросы

Hailuo API бесплатный?

В собственном API MiniMax — нет: на страницах цен, быстрого старта и в FAQ нет ни бесплатного периода, ни кредита для H3 (проверено 26 октября 2026 года). Бесплатны только первые 5 входных изображений на задачу и аудиовход (цены), а кредиты приложения Hailuo AI не работают как кредиты API.

Чем Hailuo 2.3 отличается от MiniMax H3?

Hailuo 2.3 работает в V1: 6 или 10 секунд, до 1080P, оплата за видео, прайс-лист MiniMax — $0.28 за 6 секунд в 768P (цены, справочник V1). H3 работает в V2: от 4 до 15 секунд, 768P или 2K, оплата по секундам, стереозвук (справочник создания, страница моделей). MiniMax по-прежнему предлагает обе (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). В редакции лицензии, проверенной 26 августа 2026 года, США, ЕС, Великобритания и Южная Корея входят в исключённые территории и требуют отдельной лицензии (руководство по локальной установке).

История обновлений

27 октября 2026 года: первая версия, клипы сделаны 26 октября 2026 года.