Hailuo AI API: как подключить генерацию видео через MiniMax

Быстрый ответ:

Если нужно генерировать видео автоматически на сайте или в приложении, используйте MiniMax Open Platform API. Обычная подписка Hailuo AI и тарифы API — разные продукты. Для MiniMax H3 предусмотрена асинхронная схема: сначала создаётся задача, затем по её идентификатору запрашивается результат.

Что нужно для подключения MiniMax H3

  1. Создайте аккаунт разработчика MiniMax Open Platform и проверьте доступ к видеомоделям.
  2. Выберите оплату по использованию (pay-as-you-go) и пополните доступный баланс, если это необходимо.
  3. Получите API-ключ в личном кабинете. Сохраните его на сервере в защищённом хранилище или переменной окружения.
  4. Выберите доступную модель, например MiniMax-H3, и определите лимит расхода на задачу.
  5. Решите, как приложение будет получать результат: опрос статуса задачи или поддерживаемый callback.

Не публикуйте секретный ключ в браузерном JavaScript, HTML страницы, репозитории или логах. Пользовательская форма должна обращаться к вашему серверу, а тот — к API MiniMax.

Пример запроса на генерацию видео из текста

Для H3 используется POST /v2/video_generation по адресу API MiniMax. Обязательны название модели, массив content с непустым текстовым элементом, длительность и разрешение. Для Text to Video требуется явное соотношение сторон.

curl --request POST 'https://api.minimax.io/v2/video_generation' \
  --header "Authorization: Bearer $MINIMAX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {"type":"text","text":"A ceramic cup on a table, slow camera push-in, soft morning light."}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'

В ответ приходит task_id. Это ещё не готовый файл. Сохраните идентификатор задачи вместе с номером заказа и состоянием оплаты. Затем используйте метод Query Task для проверки обработки. При статусе succeeded сохраните результат в собственное хранилище; при failed зафиксируйте ошибку и доступность возврата средств.

Текст, кадры и референсы: как выбрать режим

Text to Video использует текстовый элемент. Image to Video добавляет одно или два изображения с ролями first_frame и last_frame. Reference to Video использует отдельные роли reference_image, reference_video, reference_audio. Режимы первого/последнего кадра и референсов нельзя механически объединять: API запрещает часть смешанных комбинаций.

MiniMax-H3 поддерживает длительность 4–15 секунд и 768P или 2K. Варианты Highspeed, Lite и Max могут ограничивать разрешение 480P/768P и отличаться минимальной длительностью. Перед переносом кода на другую модель проверяйте её спецификацию. О том, когда полезна H3, читайте сравнение H3 и Hailuo 2.3.

Как защитить бюджет интеграции

  • Ограничьте количество активных задач на одного пользователя и зафиксируйте максимальную длительность.
  • Проверяйте баланс и доступность модели до создания платной задачи.
  • Сохраняйте task_id даже после сетевого таймаута: задача могла быть принята сервером.
  • Не делайте слепую повторную отправку дорогого запроса без проверки его статуса.
  • Сохраняйте дату, модель, разрешение, потраченные секунды и идентификатор клиента.

На публичной странице API MiniMax для H3 указаны ставки $0,08 за секунду в 768P и $0,13 за секунду в 2K, отдельно могут оплачиваться входные материалы. Условия оплаты API отличаются от подписки Hailuo AI. Для систем, работающих с клиентскими файлами, отдельно проверьте коммерческие права.

Типичные ошибки запросов

Ошибка 400 часто указывает на неверные параметры или отсутствие текстового элемента, 401 — на проблему авторизации, 402 — на недостаток средств, 422 — на отклонённый контент, 429 — на превышение лимитов. Обрабатывайте коды по-разному: 400 требует исправить запрос, 429 — ограничить частоту, 402 — показать состояние платежей. Дополнительные причины ошибок разобраны в руководстве по сбоям Hailuo AI.

Как опросить задачу и сохранить готовый файл

Создание задачи и получение результата разделены. После ответа с task_id запросите статус через Query Task, используя адрес и версию метода из документации вашей MiniMax Open Platform. Например, для H3 V2 в доступном описании метода используется маршрут /v2/query/video_generation/{task_id}; при изменении версии API необходимо сверить точный путь в кабинете разработчика. Пример вызова после подстановки своего идентификатора:

export TASK_ID="идентификатор_из_ответа"
curl --request GET "https://api.minimax.io/v2/query/video_generation/$TASK_ID" \
  --header "Authorization: Bearer $MINIMAX_API_KEY"

Повторяйте проверку с интервалом, а не непрерывным потоком запросов. Пока статус показывает ожидание или обработку, сохраняйте идентификатор задачи. При успешном завершении получите URL результата из поля ответа, предусмотренного вашей версией API, и скачайте видео на сервер. Ссылка на выдачу может иметь ограниченный срок жизни, поэтому не рассчитывайте на её вечное хранение.

Что предусмотреть в рабочей интеграции

  • Таймаут: если первый запрос завершился ошибкой сети, проверьте, была ли задача создана, прежде чем повторять платную операцию.
  • Очередь: храните состояния pending/processing и показывайте пользователю, что работа продолжается.
  • Готовый файл: сохраняйте URL временного результата, затем копируйте файл в собственное хранилище с ограниченным доступом.
  • Ошибка: фиксируйте код, сообщение и номер задачи, не публикуя секретный ключ.
  • Расход: считайте стоимость выходных секунд и платных входных материалов отдельно.

Проверяйте формат результата по фактическому JSON-ответу: старые и новые методы MiniMax могут по-разному передавать URL или идентификатор файла. Для продакшен-интеграции обработайте все конечные статусы, лимиты запросов и повторные попытки; один успешный вызов curl не заменяет обработку ошибок.

Пример получения видео через Python

После создания задачи и получения task_id можно отдельно запустить проверку её состояния. Ниже используется протокол MiniMax H3 V2. Переменные окружения MINIMAX_API_KEY и MINIMAX_TASK_ID задаются на сервере; код не размещают в браузере.

import os
import time
import requests

key = os.environ["MINIMAX_API_KEY"]
task_id = os.environ["MINIMAX_TASK_ID"]
url = f"https://api.minimax.io/v2/query/video_generation/{task_id}"
headers = {"Authorization": f"Bearer {key}"}

for attempt in range(60):
    response = requests.get(url, headers=headers, timeout=30)
    response.raise_for_status()
    task = response.json()["task"]
    status = task["status"]
    if status == "succeeded":
        video_url = task["content"]["url"]
        video = requests.get(video_url, timeout=120)
        video.raise_for_status()
        with open("output.mp4", "wb") as file:
            file.write(video.content)
        print("Видео сохранено: output.mp4")
        break
    if status in ("failed", "cancelled"):
        raise RuntimeError(f"Задача завершилась: {status}")
    time.sleep(10)
else:
    raise TimeoutError("Проверка заняла слишком много времени")

Этот пример показывает обработку успешного завершения, ошибки и превышения времени ожидания. Для рабочего сервиса нужны журнал задач, безопасная обработка ошибок сети, контроль числа запросов и запись результата в долговременное хранилище.

🙂+
👁 9
👍 ❤️ 🔥 🤔 😂 😱 😢 👏 😡
Не нашли ответ?
Спросите автора или предложите отдельную тему — разберём подробнее.
История обновлений
15 ноября 2026 — статья опубликована.

Оставьте комментарий