Автоматизированный конвейер Image-to-Video (R2V) на MiniMax H3 API

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

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

• Задача: анимировать статичный кадр в короткий ролик в кадровом режиме MiniMax H3 и обернуть отправку с опросом в воркер, который можно запускать без присмотра.
• Входы: first_frame_image как список из одного элемента; необязательный last_frame_image как список из одного элемента; промпт, описывающий движение от якоря или вокруг него; целочисленная длительность 4–15 с на базовом minimax-h3.
• Режимы: кадровые входы и референс-медиа взаимно исключают друг друга. Turbo (minimax-h3-max-turbo) отклоняет референс-медиа; не копируйте референсные поля в полезную нагрузку Turbo.
• Воркер: подготовьте доступный ассет, сделайте один POST, сохраните идентификатор задачи, опрашивайте статус с backoff и жёстким дедлайном, затем сохраните URL результата в своей системе.
• Область: это руководство по интеграции текущего контракта фронтенда ToAPIs, а не бенчмарк задержки, доступности или цены.

2. Архитектура конвейера

Автономный воркер R2V должен отделять HTTP-запрос вызывающей стороны от долгого рендера:

1. Принять исходный кадр и промпт движения из вашего продукта.
2. Подготовить изображение через задокументированный процесс загрузки или URL, который вам разрешено запрашивать. Предпочитайте объектное хранилище с короткоживущим доступным указателем, а не частный путь на диске.
3. Отправить один POST /v1/videos/generations с model, prompt, duration и first_frame_image.
4. Опросить задокументированный эндпоинт статуса задачи с ограниченным экспоненциальным backoff и общим дедлайном.
5. Доставить URL готового видео своим каналом уведомлений (очередь, почта или продуктовый webhook). Перед созданием второй платной задачи проверьте статус.

Рис. 1: Статичный кадр сначала готовят, затем один раз отправляют через шлюз generations ToAPIs и опрашивают до конечного состояния, после чего ваш сервис отдаёт готовый ролик.

Проверки перед отправкой, которые предотвращают большинство ошибок 400:

• Используйте точный ID модели, включённый для аккаунта (minimax-h3, minimax-h3-max или minimax-h3-max-turbo — без выдуманных псевдонимов).
• Длительность — целое число: 4–15 с на базовом H3, 5–15 с у семейства Max.
• first_frame_image и last_frame_image — списки не более чем из одного изображения.
• Не отправляйте reference_images, reference_videos или reference_audio в том же запросе, что и кадровые входы.
• В кадровом режиме текущий фронтенд принудительно ставит ratio в adaptive. Совместите форму кадра с задуманным холстом (например, 1920×1080 для широкого ролика, 1080×1920 для вертикального), чтобы снизить неожиданную обрезку.
• Имя поля в контракте — ratio, а не aspect_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": "[Dolly Forward] Rain falling onto neon asphalt, steam rising from grates, cinematic reflections",
    "duration": 6,
    "ratio": "16:9",
    "first_frame_image": ["https://example.com/starting-frame.jpg"]
  }'

Замените URL-заполнитель идентификатором ассета или URL из задокументированного процесса загрузки. В опубликованном контракте H3 поле first_frame_image — массив, а не одиночная строка.

Чтобы также задать конечный кадр, добавьте в тот же кадровый запрос "last_frame_image": ["https://example.com/ending-frame.jpg"]. Это стандартный кадровый режим, а не экспериментальный флаг только для Turbo.

Шаг 2: Python-воркер с ограниченным опросом

Перед релизом согласуйте task_id, status и video_url со схемой ответа, описанной для вашего аккаунта.

import os
import time
import requests
from typing import Any

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


class MiniMaxR2VPipeline:
    def trigger_r2v(
        self,
        image_ref: str,
        prompt: str,
        duration: int = 6,
        last_frame_ref: str | None = None,
    ) -> str:
        if not 4 <= duration <= 15:
            raise ValueError("Base minimax-h3 accepts integer durations of 4-15 seconds")
        payload: dict[str, Any] = {
            "model": "minimax-h3",
            "prompt": prompt,
            "duration": duration,
            "ratio": "16:9",
            "first_frame_image": [image_ref],
        }
        if last_frame_ref:
            payload["last_frame_image"] = [last_frame_ref]
        res = requests.post(
            f"{BASE_URL}/videos/generations",
            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_until_complete(self, task_id: str, max_timeout: int = 180) -> dict[str, Any]:
        start = time.time()
        interval = 3.0
        poll_url = f"{BASE_URL}/videos/tasks/{task_id}"
        while time.time() - start < max_timeout:
            res = requests.get(poll_url, headers=HEADERS, timeout=15)
            res.raise_for_status()
            data = res.json()
            status = data.get("status")
            if status in {"succeeded", "success"}:
                return {
                    "status": "success",
                    "task_id": task_id,
                    "video_url": data.get("video_url"),
                    "elapsed_seconds": round(time.time() - start, 2),
                }
            if status in {"failed", "error"}:
                return {
                    "status": "error",
                    "task_id": task_id,
                    "error": data.get("error", "Generation failed"),
                }
            time.sleep(interval)
            interval = min(interval * 1.1, 6.0)
        return {
            "status": "timeout",
            "task_id": task_id,
            "error": f"Exceeded {max_timeout}s; check task status before retrying",
        }


if __name__ == "__main__":
    pipeline = MiniMaxR2VPipeline()
    # Replace with an uploaded asset identifier or a URL you are authorized to fetch.
    image_ref = "https://example.com/starting-frame.jpg"
    prompt = "[Dolly Forward] Rain falling onto neon asphalt, steam rising from grates, cinematic reflections"
    task_id = pipeline.trigger_r2v(image_ref, prompt)
    print("Task:", task_id)
    print("Result:", pipeline.poll_until_complete(task_id))

Таймаут не подтверждает сбой. Запишите идентификатор задачи (никогда — API-ключ или частные URL медиа), проверьте статус и только затем решайте, отправлять ли снова.

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}$

• Берите котировку с датой из аккаунта. Не вставляйте черновые плановые цены за секунду или проценты SLA в производственный прогноз. Ставки и биллинг неудачных задач могут отличаться по модели и маршруту.
• Официальные контракты вендоров могут требовать обязательств или порог предоплаты. Уточните, является ли ваш аккаунт ToAPIs чисто pay-as-you-go и как тарифицируются сбои апстрима.
• Дисциплина конвейера — практический рычаг FinOps: одна отправка на кадр, проверка статуса перед повтором, шаблоны промпта рядом с задачей и длительность не длиннее необходимого клипа.
• Нужен 1080P? Проверьте, включён ли точный канонический ID minimax-h3-max. Нужен Turbo? Используйте minimax-h3-max-turbo и не включайте поля референс-медиа. Подробности — в руководстве по выбору.

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

Структурированные ответы — во frontmatter. Кратко: совместите статичный кадр с задуманным холстом; подсказка конечного кадра — стандартный кадровый режим (не более одного изображения в каждом поле); используйте задокументированный процесс загрузки, а не частный путь; это руководство опрашивает статус и не предполагает webhook ToAPIs.

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

• Создайте ключ в портале разработчика ToAPIs.
• Подготовьте один статичный кадр через задокументированный процесс загрузки и проверьте cURL-запрос с первым кадром.
• Подключите Python-воркер с дедлайном опроса 180 с и запретом повторной отправки при таймауте.
• Перед пакетной обработкой перечитайте контракт запроса H3 и руководство по промптам движения камеры.