Руководство по промптам MiniMax H3: кинематографическая камера через API

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

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

• Задача: превратить раскадровку в повторяемые промпты MiniMax H3 — объект, действие, путь камеры, объектив и свет — и отправить их на эндпоинт generations ToAPIs.
• Стиль промпта: сначала замысел камеры, затем объект. Сочетайте направление с фокусным расстоянием (например, 35mm против 85mm) и подсказкой по свету.
• Контракт: базовый minimax-h3 принимает целочисленные клипы 4–15 с. Используйте ratio (16:9, 9:16 и другие значения ниже). Это контракт запроса фронтенда, а не бенчмарк задержки или качества.
• Осторожность с синтаксисом: теги в скобках — помощники промпта. Не считайте [Pan Left] задокументированной нативной командой, пока этого не подтверждает документация апстрим-модели.
• Протокол: Bearer REST. Отправьте запрос один раз, сохраните идентификатор задачи и опрашивайте задокументированный эндпоинт статуса с ограниченным дедлайном.

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

Полезный промпт H3 описывает одну сцену и одно главное действие, и только потом добавляет направление камеры, объектив или стиль. При сравнении моделей или длительности держите эти части стабильными, иначе смена формулировки сама объяснит другой результат.

Теги в таблице ниже — помощники промпта, а не гарантированная командная грамматика. Контракт фронтенда ToAPIs проверяет промпт как текст (до 7000 символов Unicode) и не доказывает, что строки вроде [Pan Left] являются нативными командами H3. Используйте их как единый словарь в шаблонах и проверяйте результат.

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

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

[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES

Пример: [Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur.

Для заданий с первым кадром (R2V) тот же текст промпта описывает, как камера должна двигаться вокруг якорного изображения или от него. Поля запроса см. в руководстве по конвейеру R2V. Входы кадров и референс-медиа по-прежнему взаимно исключают друг друга.

Поддерживаемые значения ratio в текущем фронтенде: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 и 9:16. При наличии кадровых входов включается adaptive. Не отправляйте aspect_ratio; имя поля в контракте — ratio.

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-h3",
    "prompt": "[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur",
    "duration": 6,
    "ratio": "16:9"
  }'

Шаг 2: помощник промпта и поллер на Python

Согласуйте имена полей и форму ответа со справочником API вашего аккаунта. Пример ниже использует тот же путь статуса задачи, что и другие видеогиды ToAPIs; перед релизом подтвердите task_id, status и video_url.

import os
import time
import requests

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


def build_cinematic_prompt(
    subject: str,
    camera_move: str,
    lighting: str,
    lens: str = "35mm anamorphic",
) -> str:
    return (
        f"[{camera_move}] {subject}, {lighting}, "
        f"shot on {lens}, photorealistic, cinematic motion blur."
    )


def dispatch_camera_shot(prompt: str, duration: int = 6, ratio: str = "16:9") -> str:
    payload = {
        "model": "minimax-h3",
        "prompt": prompt,
        "duration": duration,
        "ratio": ratio,
    }
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 180) -> str:
    poll_url = f"https://api.toapis.com/v1/videos/tasks/{task_id}"
    interval = 3.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status in {"succeeded", "success"}:
            return data["video_url"]
        if status in {"failed", "error"}:
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = build_cinematic_prompt(
        subject="Matte black mechanical wristwatch resting on volcanic stone",
        camera_move="Orbit 180 + Slow Dolly In",
        lighting="Moody low-key rim lighting, subtle steam haze",
        lens="85mm macro lens",
    )
    task_id = dispatch_camera_shot(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

Храните версию шаблона промпта рядом с записью задачи, чтобы отличать смену модели от смены формулировки. Таймаут на стороне клиента не доказывает, что апстрим-задача провалилась: перед повторной платной отправкой проверьте статус.

Длительность базового H3 — целое число от 4 до 15 секунд. ID семейства Max начинаются с 5 секунд и имеют собственные списки разрешения; Turbo не принимает референс-медиа. Перед сменой ID см. руководство по API.

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

Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs.

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

5. Цены и FinOps ROI

$\text{Estimated cost} = \text{successful output seconds} \times \text{current account rate per second}$

• Не переиспользуйте черновые плановые цены. Ставка за секунду, единица биллинга и учёт неудачных задач зависят от модели, маршрута и аккаунта. Перед прогнозом раскадровки смотрите актуальный каталог ToAPIs и котировку вашего аккаунта.
• Официальные контракты вендоров часто включают годовые обязательства, квоты мест и порог предоплаты. Биллинг ToAPIs обычно идёт по факту использования — уточните действующие условия в аккаунте.
• Контролируйте расход на уровне промпта: версионируйте шаблон, меняйте по одной переменной и после клиентского таймаута сначала проверяйте статус, а уже потом решайте, отправлять ли снова.
• Для выбора между базовым H3, каноническим Max и Turbo используйте руководство по выбору, а не непроверенные оценки скорости или качества.

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

Структурированные ответы — в блоке FAQ во frontmatter. Кратко: начинайте промпт с замысла камеры; составное движение — это текст промпта, а не гарантированная грамматика; та же формулировка применима в режиме первого кадра; теги в скобках не являются официальными параметрами API.

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

• Создайте ключ в портале разработчика ToAPIs.
• Проверьте cURL-пример с minimax-h3, ratio: "16:9" и длительностью 6 секунд.
• Подключите помощник промпта, сохраняйте версии шаблонов и опрашивайте статус с дедлайном 180 с.
• Далее: контракт запроса H3 API и автоматизированный конвейер R2V.