Интеграция MiniMax Hailuo 2.3 API: сложное движение человека в ИИ-видео

Целевая модель: MiniMax-Hailuo-2.3
Эндпоинт инференса: https://api.toapis.com/v1/videos/generations
Связанные материалы: Руководство по MiniMax H3 API · Промпты движения камеры H3 · Автоматизированный конвейер R2V

1. Краткое содержание и обзор (TL;DR)

• Задача: Отправлять на эндпоинт генерации ToAPIs задания text-to-video или image-to-video с первым кадром, чтобы получать клипы с движением персонажа и человека.
• Контракт: MiniMax-Hailuo-2.3 принимает целочисленную длительность 6 или 10 секунд и разрешение 768P или 1080P. Для 1080P доступны только 6 секунд. В актуальном справочнике API длина промпта ограничена 2000 символами.
• Идентификаторы: Для text-to-video и image-to-video используйте строку каталога MiniMax-Hailuo-2.3. MiniMax-Hailuo-2.3-Fast работает только как image-to-video и требует URL первого кадра. Ни один из этих ID нельзя подменять на minimax-h3.
• Язык камеры: Справочник ToAPIs по Hailuo 2.3 документирует директивы в квадратных скобках, например [Push in] и [Pan left, Pedestal up]. Таблица ниже — актуальный зафиксированный словарь; перед жёсткой кодировкой грамматики кадра сверьтесь с живой документацией.
• Протокол: Bearer REST. Сохраните id задачи из ответа на отправку и опрашивайте GET /v1/videos/generations/{task_id} (или GET /v1/tasks/{task_id}) с ограниченным дедлайном. Таймаут клиента не доказывает, что Upstream-задача завершилась ошибкой.

2. Шаблоны промптов сложного движения человека

Публичный каталог ToAPIs описывает MiniMax Hailuo 2.3 как видеомодель для движения персонажа, мимики и стиля в выразительных историях и коротких роликах. Это позиционирование продукта, а не независимое измерение «нулевой деформации конечностей». Для продакшена описывайте одного героя и одно основное действие механическим языком, затем проверяйте дубль.

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

Справочник API ToAPIs по Hailuo 2.3 помещает следующие директивы камеры в строку промпта, а не в отдельное поле запроса. Контракт фронтенда по-прежнему проверяет prompt как текст. Одновременное движение — не больше трёх директив в одних скобках; последовательное — перечислите их в предложении.

Рис. 1: Считайте неподвижную позу входом первого кадра, опишите последующее действие в промпте и один раз отправьте запрос генерации через шлюз ToAPIs.

Короткий шаблон, который удобно тестировать:

SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES

Пример: A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs.

Для image-to-video передайте один публично доступный URL первого кадра в image_urls. Изображение — стартовый кадр, промпт описывает движение, которое за ним следует. Актуальные ограничения на изображение: JPG, JPEG, PNG или WebP; меньше 20 МБ; короткая сторона больше 300 px; соотношение сторон от 2:5 до 5:2. Не кладите base64 в image_urls — локальный файл сначала загрузите.

MiniMax-Hailuo-2.3-Fast не принимает text-to-video: URL первого кадра обязателен. У Hailuo 2.3 нет задокументированного поля последнего кадра; интерполяция от первого кадра к последнему относится к MiniMax-Hailuo-02, а не к этому ID. Не переносите поля H3 вроде ratio или reference_videos в запрос Hailuo 2.3.

Подписи опций в Playground могут показывать строчные 768p / 1080p. Текущие примеры API используют 768P и 1080P. Перед автоматизацией пакета подтвердите значение, которое принимает ваш аккаунт. Ту же формулировку камеры можно использовать как текст промпта в MiniMax H3, но контракты длительности, разрешения и медиарежима другие — меняйте ID только после повторного чтения того руководства.

3. Продакшен-реализация: cURL и Python

Шаг 1: отправка через cURL

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs",
    "duration": 6,
    "resolution": "768P"
  }'

Шаг 2: помощник и опрос на Python

Официальная документация сейчас указывает публичный origin https://toapis.com (для материкового Китая — https://toapis.cn). Другие руководства этой серии используют https://api.toapis.com. Выберите один базовый URL и придерживайтесь его. Пример ниже следует задокументированному пути статуса задачи и статусам completed / failed; перед выпуском сверьте id, result.data[0].url и конверт ответа со справочником API вашего аккаунта.

import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_motion_clip(
    prompt: str,
    duration: int = 6,
    resolution: str = "768P",
    image_url: str | None = None,
    model: str = "MiniMax-Hailuo-2.3",
) -> str:
    if resolution == "1080P" and duration != 6:
        raise ValueError("1080P currently supports a 6-second duration only")
    payload = {
        "model": model,
        "prompt": prompt,
        "duration": duration,
        "resolution": resolution,
        "metadata": {"prompt_optimizer": True, "aigc_watermark": False},
    }
    if image_url:
        payload["image_urls"] = [image_url]
    elif model == "MiniMax-Hailuo-2.3-Fast":
        raise ValueError("MiniMax-Hailuo-2.3-Fast requires a first-frame image_urls value")
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 300) -> str:
    poll_url = f"{BASE}/v1/videos/generations/{task_id}"
    interval = 5.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 30))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 10.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = (
        "A contemporary dancer in a black practice leotard plants the left foot, "
        "then uncoils a slow 360-degree turn with the right arm leading and the "
        "torso stacked over the standing leg, warehouse skylight, [Tracking shot], "
        "photorealistic, no morphing limbs"
    )
    task_id = dispatch_motion_clip(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

Храните версию шаблона промпта рядом с записью задачи, чтобы отличить смену модели от смены формулировки. Для задания с первым кадром передайте image_url= в dispatch_motion_clip. Для SKU Fast этот аргумент обязателен.

Базовая длительность Hailuo 2.3 — 6 или 10 секунд. Не отправляйте 1080P вместе с duration: 10. Если нужны непрерывные ролики 4–15 секунд, референсные медиа или последний кадр, это другой контракт — см. руководство по H3 API и учебник по конвейеру R2V.

4. Обработка ошибок и матрица статусов

Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs. Даже при успешном HTTP-запросе нужно читать status задачи.

$\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)$

5. Цены и FinOps ROI

$\text{Estimated cost} = \text{successful billable jobs} \times \text{current account rate for that model, duration, and resolution}$

• Не переиспользуйте черновые единичные цены. Ставки за секунду или за ролик, единицы биллинга и обращение с неудачными задачами зависят от модели, разрешения, длительности, маршрута и аккаунта. Строки официальных вендорских справочных цен на странице ToAPIs носят ознакомительный характер и могут не совпадать со списанием по аккаунту. Перед прогнозом списка кадров прочитайте текущий каталог и котировку аккаунта.
• Fast — отдельный SKU, а не бесплатный переключатель скорости на том же ID. MiniMax-Hailuo-2.3-Fast задокументирован только как image-to-video. Его текущую цену аккаунта подтверждайте отдельно.
• Контролируйте расход на уровне промпта: черновите в 768P и 6 секундах, храните версионированный шаблон, меняйте по одной переменной и не переотправляйте задачу после таймаута клиента, пока не проверили статус.
• Прямые контракты вендоров часто добавляют годовые обязательства, квоты мест и пороги предоплаты. Биллинг ToAPIs обычно строится по факту использования — уточните действующие условия в аккаунте.

6. Часто задаваемые вопросы

См. блок FAQ во frontmatter. Кратко: строка модели в запросе — MiniMax-Hailuo-2.3, а не дефисный slug страницы и не ID семейства H3; 1080P ограничен 6 секундами; Fast требует URL первого кадра и не поддерживает text-to-video; задокументированные директивы камеры живут в промпте, а не в отдельных полях; у Hailuo 2.3 нет входа последнего кадра.

7. Чек-лист действий

• Создайте ключ на портале разработчика ToAPIs.
• Прогоните дымовой тест cURL с MiniMax-Hailuo-2.3, resolution: "768P" и длительностью 6 секунд.
• Уточните, ожидает ли аккаунт 768P или 768p, и опрашивайте GET /v1/videos/generations/{id} с ограниченным дедлайном.
• Далее: если нужен другой контракт длительности или медиа, откройте руководство по камере H3; актуальный статус каталога — в гайде модели Hailuo 2.3.