MiniMax H3 API: руководство по видео и референсным материалам

Если считать все варианты MiniMax H3 одинаковыми, запросы легко настроить неверно. Идентификатор модели влияет на проверку длительности и разрешения, а режим ввода определяет, можно ли передавать вместе начальный/конечный кадр, референсные изображения, видео и аудио.

Руководство описывает контракт запросов, реализованный во фронтенде ToAPIs по состоянию на 22 октября 2026 года. Это не тест производительности upstream-модели и не текущий прайс аккаунта. Перед рабочими вызовами убедитесь, что нужная модель включена для вашего аккаунта.

Быстрый старт

В примерах API ToAPIs для отправки задачи используется POST /v1/videos/generations. Передайте Bearer API Key, доступный ID модели, промпт, длительность и соотношение сторон:

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
    "duration": 5,
    "ratio": "16:9"
  }'

Генерация выполняется асинхронно. Получите идентификатор задачи из ответа API вашего аккаунта и опрашивайте статус через endpoint, указанный в документации аккаунта. Не предполагайте фиксированный путь в JSON-ответе, если он не документирован.

import os
import requests

BASE_URL = "https://api.toapis.com/v1"
headers = {"Authorization": f"Bearer {os.environ['TOAPIS_API_KEY']}"}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json={
        "model": "minimax-h3",
        "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
        "duration": 5,
        "ratio": "16:9",
    },
    timeout=30,
)
response.raise_for_status()
print("Submission response:", response.json())

Пример выводит ответ целиком, не угадывая расположение ID задачи или ссылки на видео. Разбирайте ответ в соответствии со схемой, опубликованной для вашего аккаунта, чтобы изменение структуры не привело к ложному статусу успеха.

Указывайте точный ID модели

Фронтенд распознаёт minimax-h3 и minimax-h3-global как базовые ID, а также ID, содержащие minimax-h3-max. Например, ID Turbo — minimax-h3-max-turbo. Используйте полный ID из каталога моделей, не сокращайте его и не придумывайте псевдонимы.

Текущие ограничения проверки во фронтенде:

Это ограничения проверки на стороне фронтенда, а не гарантия доступности во всех аккаунтах или upstream-маршрутах. В текущем клиенте 1080P добавлен только для точного ID minimax-h3-max. Не следует считать, что Turbo, псевдоним -global или все модели H3 поддерживают 1080P.

Выберите один режим входных материалов

Форма H3 поддерживает два взаимоисключающих сценария:

1. Кадровый режим: не более одного first_frame_image и одного last_frame_image. При наличии кадров клиент выбирает адаптивное соотношение сторон.
2. Режим референсов: передавайте референсные изображения, видео и/или аудио без начального и конечного кадров. Используется выбранное соотношение сторон.

Пример запроса с начальным кадром:

{
  "model": "minimax-h3",
  "prompt": "The subject turns toward the camera as the camera gently moves forward",
  "duration": 5,
  "ratio": "16:9",
  "first_frame_image": ["https://example.com/starting-frame.jpg"]
}

Пример запроса с референсными материалами:

{
  "model": "minimax-h3",
  "prompt": "Use the supplied references to guide the scene and motion",
  "duration": 5,
  "ratio": "16:9",
  "media_mode": "reference",
  "reference_images": ["https://example.com/character-reference.jpg"],
  "reference_videos": ["https://example.com/motion-reference.mp4"]
}

Формат значений загруженных материалов зависит от процедуры загрузки в шлюзе. Примеры показывают поля запроса, но не утверждают, что любой маршрут принимает произвольные общедоступные URL. Используйте URL или ID материалов, полученные в документированном процессе загрузки.

Текущие ограничения фронтенда: до 9 референсных изображений, 3 видео и 3 аудио; суммарно не более 12 материалов. Длительность каждого референсного видео — 2–15 секунд, общая длительность видео — не более 15 секунд. Для аудио нужен хотя бы один визуальный материал. Запросы Turbo не принимают референсные материалы.

Перед отправкой проверьте режим, количество и длительность. При смешении режимов, превышении лимитов или отсутствии визуального референса фронтенд отклонит запрос.

Промпт, формат кадра и дополнительные параметры

Промпт обязателен; текущий фронтенд ограничивает его 7 000 символами Unicode. Описывайте объект, сцену, действие и визуальную цель обычным языком. Если upstream-документация не определяет специальный синтаксис, считайте строки вроде [Pan Left] обычным текстом промпта. Контракт фронтенда не подтверждает, что это встроенные команды H3.

Конструктор запроса обрабатывает такие опции, как prompt_optimizer, watermark и seed, в зависимости от модели и маршрута. Не предполагайте, что они одинаково поддерживаются всеми upstream-каналами. При смене модели удаляйте оставшиеся поля, которые новая модель не поддерживает.

Фронтенд принимает adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 и 9:16. Кадровый режим принудительно выбирает adaptive. В Text-to-Video значение adaptive нормализуется до 16:9, а в режиме референсов сохраняется выбранное поддерживаемое соотношение.

Соотношение сторон определяет форму кадра, а разрешение — размер вывода, доступный для маршрута модели. Регистр значения тоже может отличаться (768p и 768P). Не приводите значения к единому формату без проверки контракта конкретной модели.

Опрос задач, ошибки и повторные попытки

После отправки сохраните ID задачи и проверяйте статус через endpoint из документации аккаунта. Используйте ограниченный backoff и общий тайм-аут, различайте ошибку задачи и клиентский тайм-аут ожидания. Тайм-аут клиента сам по себе не означает, что upstream-задача завершилась ошибкой. Перед повторной отправкой потенциально платного запроса сначала проверьте исходную задачу, чтобы избежать дубликата.

Клиенту следует проверять HTTP-статус, разбирать ответ по опубликованной схеме, прекращать опрос на документированном терминальном статусе и ограничивать число повторов и общее время. ID запроса или задачи можно записывать в лог, но не API Key и не приватные URL материалов.

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

Цена, конфиденциальность и проверка перед запуском

Цена, доступность, возвраты и SLA могут различаться в зависимости от модели, маршрута и аккаунта. В руководстве намеренно нет цены за секунду или обещания доступности. Перед расчётом затрат проверяйте текущий каталог и цену аккаунта; не используйте плановую цену как коммерческое предложение.

Референсные материалы следует считать пользовательскими данными. До загрузки проверяйте тип, размер и количество файлов, обрабатывайте только материалы, на которые у пользователя есть права, и соблюдайте правила хранения данных продукта. Не размещайте приватные исходники по публичным URL ради демонстрации и не записывайте временные ссылки в долгосрочные логи.

Перед запуском протестируйте по одному корректному запросу для каждой модели, включённой в аккаунте. Добавьте отрицательные тесты для дробной длительности, неподдерживаемого разрешения, превышения количества материалов, смешения режимов и референсов в Turbo. При переключении модели интерфейс должен очищать несовместимые параметры. Ответы и статусы проверяйте на локальных фикстурах или одобренном тестовом аккаунте. В этой статье не выполнялись вызовы production API.

Полезные ссылки

• Каталог видеомоделей
• Открыть MiniMax H3 в Playground
• Открыть MiniMax H3 Max Turbo в Playground