Как использовать MiniMax H3 Max API? Генерация видео из текста или изображения

В HiAPI модель MiniMax H3 Max представлена двумя именами: текст в видео minimax-h3-max/text-to-video и изображение в видео minimax-h3-max/image-to-video. Модель генерирует видео длительностью 0,92–15 секунд: 480P — $0.072 в секунду, 768P — $0.115 в секунду, 1080P — $0.229 в секунду; оплата идёт по запрошенному количеству секунд. Для начала сгенерируйте с помощью приведённого ниже промпта про бумажный кораблик 5-секундный горизонтальный ролик: при 768P бюджет составит $0.575. При работе с API отправьте задачу один раз, а затем получите видео по возвращённому taskId.

MiniMax H3 Max уже доступна в HiAPI — сгенерируйте по этому промпту →. Промпт заполнится автоматически, после чего вручную выберите 5 секунд, 768P и 16:9.

Первое видео: бумажный кораблик после дождя

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

сгенерируйте по этому промпту →

В этом промпте действие и движение камеры разделены: бумажный кораблик дрейфует по воде, камера плавно следует за ним с нижней точки, а звук передаётся пением птиц вдалеке. Заменяя кораблик на свой объект, сохраните одно действие и один тип движения камеры — так легче понять, что именно нужно скорректировать.

Онлайн-тест или подключение через API — что выбрать?

Если сначала хотите посмотреть результат, откройте страницу модели текст в видео, скопируйте промпт, выберите длительность и разрешение и отправьте генерацию; если у вас уже есть начальный кадр, перейдите на страницу модели изображение в видео и загрузите первое изображение. Для интеграции в приложение сначала получите ключ на странице API Key, создайте задачу серверным запросом, сохраните taskId и после успешного завершения задачи прочитайте адрес видео.

Разрешение рекомендуется указывать явно: 5 секунд в 480P — $0.36, в 768P — $0.575, в 1080P — $1.145. Сначала проверьте действие в низком разрешении, затем выбирайте уровень под требования к результату; полная смета приведена в таблице цен H3 и H3 Max.

cURL: создание задачи и опрос результата

Задайте API Key в локальной переменной окружения HIAPI_API_KEY и выполните этот запрос:

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

Если POST завершился по таймауту, соединение прервалось или ответ не позволяет однозначно определить результат создания, состояние отправки неизвестно: сначала проверьте историю задач, не повторяйте POST сразу. Убедившись, что в ответе code=200, data является объектом, а data.taskId не пуст, сохраните ID и подставьте его вместо YOUR_TASK_ID в адрес опроса:

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Для задачи в процессе выполнения продолжайте опрашивать тот же ID. Когда data.status равен success, прочитайте url видеоэлемента из data.output; если fail — проверьте сообщение об ошибке задачи; при ошибках входных данных или аутентификации сначала исправьте соответствующую проблему, а при наличии ID задачи продолжайте опрашивать её.

Python: отправить один раз и дождаться той же задачи

Ниже используется стандартная библиотека Python. POST выполняется только один раз с проверкой ответа; если результат отправки неизвестен, скрипт останавливается и предлагает проверить историю задач. При временных сбоях опроса ID задачи сохраняется и GET повторяется; 600 секунд — верхний предел ожидания в этом примере.

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

Управление первым или последним кадром с помощью изображения

Чтобы видео начиналось с вашего изображения товара, замените имя модели на minimax-h3-max/image-to-video и добавьте в input поле first_frame_image; чтобы задать концовку, добавьте last_frame_image. Можно передать только последний кадр или сразу первый и последний; в режиме изображение в видео нет поля aspect_ratio — формат кадра следует за изображением.

Поле	Использование
prompt	Обязательное, до 50000 символов, описывает действие, движение камеры и звук
duration	0,92–15 секунд, может быть дробным, по умолчанию 5 секунд
resolution	480P, 768P или 1080P, по умолчанию 768P
aspect_ratio	Только для текст в видео: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, по умолчанию 16:9
first_frame_image	Изображение в видео: публичный URL изображения первого кадра
last_frame_image	Изображение в видео: публичный URL изображения последнего кадра
target_audio_url	Необязательно, заменяет звуковую дорожку вашим аудио длительностью не менее 2 секунд
prompt_expansion_mode	Необязательно, disabled / balanced (по умолчанию) / quality

Ниже приведено полное тело запроса с первым и последним кадром, где URL изображений — заполнители для ваших собственных публично доступных адресов; изображения задают начальную и конечную композицию:

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

Если нужно управлять только последним кадром, удалите first_frame_image и оставьте last_frame_image. Описывайте в промпте только движение камеры — изображение отвечает за объект и начальную композицию. Для нескольких планов явно опишите в промпте каждый переход; поля запроса при этом берутся из этой таблицы — не добавляйте camera_angle, mode или watermark.

Для вертикального ролика в режиме текст в видео просто укажите "aspect_ratio": "9:16"; в режиме изображение в видео используйте вертикальное изображение первого кадра — формат кадра следует за изображением.

При интеграции в приложение размещайте callback на верхнем уровне запроса

Добавьте необязательный callback на верхний уровень запроса на создание, рядом с model и input:

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Включите этот фрагмент в полный запрос. На принимающей стороне дедуплицируйте по taskId, обрабатывайте успех и ошибку раздельно, а пропущенные уведомления восполняйте опросом задачи. Получив ID задачи, не отправляйте её повторно; при ошибке HTTP сначала прочитайте тело ответа и определите, связана ли проблема с аутентификацией или с параметрами.

Четыре проверки после интеграции

1. Сохраните непустой data.taskId и используйте его даже после сбоя опроса.
2. Убедитесь, что конечное состояние — success или fail, и не принимайте верхний предел ожидания за время работы модели.
3. В data.output успешной задачи найдите URL видео по type=video.
4. Скачайте результат и проверьте фактические размеры, длительность и изображение на соответствие требованиям к результату.

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

Можно ли использовать в H3 Max референсное видео или аудио? H3 Max заменяет звуковую дорожку через target_audio_url, но не принимает референсное видео; если нужны мультимодальные референсы изображения, видео и аудио, выберите MiniMax H3.

Дороже ли Max, чем H3? H3 в 2K стоит $0.1189 в секунду, Max в 768P — $0.115 в секунду, в 1080P — $0.229 в секунду. Сначала выберите модель по необходимому разрешению и референсным материалам, затем рассчитайте бюджет по длительности.

С чего начать вертикальный ролик? В режиме текст в видео укажите "aspect_ratio": "9:16"; в режиме изображение в видео подготовьте вертикальное изображение первого кадра — формат кадра следует за изображением.

Скопируйте промпт про бумажный кораблик, сгенерируйте по этому промпту → и сначала сделайте 5-секундный ролик. Больше вариантов описания действий и движения камеры — в статье 4 реальных видео и полные промпты, полный список полей — в документации параметров текст в видео и документации параметров изображение в видео.