Как оживить фото в Hailuo через API

Как оживить фото в Hailuo: документация MiniMax описывает режим Image-to-Video, где модель принимает промпт и изображение первого кадра. Понадобятся учётные данные API — ключ в переменной окружения и доступ к платному Pay-as-you-go API. Веб-редактор здесь не рассматривается: ниже идёт документированный путь через API.

Что нужно для запуска: ключ и доступ к API

Документация MiniMax по генерации видео называет два продукта: MiniMax H3 и MiniMax H3 Max. H3 — открытая универсальная мультимодальная видеомодель, понимающая текст, изображение, видео и аудио; H3 Max выпущен совместно MiniMax и fal.ai, оптимизирован под высокую скорость и выдаёт 480P и 768P. Для работы с любой из них документация указывает выбрать Pay-as-you-go API.

Учётные данные — это ключ API. В официальном примере он читается из переменной окружения: api_key = os.environ["MINIMAX_API_KEY"], а заголовок запроса собирается как {"Authorization": f"Bearer {api_key}"}. Ключ хранится в окружении и в логи не выводится. Базовый адрес в примере — https://api.minimax.io, модель обозначена строкой MiniMax-H3.

Перед отправкой запроса проверьте три вещи: ключ доступен процессу, выбран режим Image-to-Video с изображением первого кадра, и вы понимаете, что генерация асинхронная. Последнее важно: запрос создаёт задачу и возвращает task_id, а сам ролик появляется позже. Документация описывает три шага: создание задачи, опрос статуса по task_id, скачивание файла по content.url. Никакого мгновенного ответа с видео при создании задачи не приходит.

Если ключа нет, документированный путь начинается с его получения в личном кабинете платформы. Дальше всё сводится к одному POST-запросу на /v2/video_generation и последующему опросу. Для четырёх режимов примера MiniMax-H3 общий порядок состоит из создания задачи, опроса статуса и скачивания; состав content и требования к ratio зависят от режима. Для Text-to-Video поле ratio обязательно и не может быть adaptive; в примере Image-to-Video это поле опущено, а соотношение сторон определяется изображением и фиксировано как adaptive.

Требования к изображению и входные форматы

Раздел «Input Requirements» документации задаёт границы для кадров. Для входа первого и последнего кадра: изображений 0, 1 или 2; ширина и высота в диапазоне от 256 до 5760; соотношение сторон (ширина к высоте) в пределах от 2:5 до 5:2. Если изображений нет вовсе, режим превращается в Text-to-Video.

Для reference-входа лимиты шире: до 9 изображений, те же границы по размеру и соотношению сторон. Видео — до 3 клипов, длительность каждого от 2 до 15 секунд, суммарно не больше 15 секунд. Аудио — до 3 клипов с теми же временными рамками. Смешанный вход ограничен 12 файлами суммарно.

Поддерживаемые форматы изображений: JPG, JPEG, PNG, WEBP, HEIC, HEIF. Видео — H.264/AVC и H.265/HEVC, звук внутри видео — AAC и MP3. Аудиофайлы — WAV и MP3. Лимиты по размеру: видео до 50 МБ на файл, изображение до 30 МБ на файл, аудио до 15 МБ на файл. Ограничения применяются к каждому файлу отдельно. Тело запроса — до 64 МБ, для крупных файлов документация советует передавать URL. Длина промпта — до 7000 символов.

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

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

Официальный пример на Python показывает режим Image-to-Video функцией invoke_image_to_video. Запрос идёт методом POST на {BASE_URL}/v2/video_generation. Поле content — список элементов, различаемых по type. Текстовый элемент обязателен и задаёт содержание и движение: {"type": "text", "text": "..."}. Кадр передаётся элементом {"type": "image_url", "image_url": {"url": "..."}, "role": "first_frame"}.

Для режима Image-to-Video документация отмечает: соотношение сторон определяется входным изображением, а параметр ratio всегда равен adaptive. В примере заданы duration: 5 и resolution: "2K". Ответ возвращает task_id через response.json()["task_id"].

Дальше — опрос статуса. Функция query_task_status обращается к {BASE_URL}/v2/query/video_generation/{task_id} в цикле. Рекомендованный интервал опроса — 10 секунд, чтобы не нагружать сервер. При статусе succeeded возвращается task["content"]["url"] — прямая ссылка на скачивание. Терминальные состояния отказа — failed и cancelled.

Скачивание — третий шаг: функция fetch_video забирает файл по ссылке и сохраняет его локально как output.mp4. Обмен file_id не нужен: успешный статус сразу отдаёт URL. В основном блоке примера режим выбирается раскомментированием одной из четырёх функций, затем идут опрос и скачивание.

Учебный шаблон движения: субъект, движение, камера

Промпт в H3 описывает отношения между контекстом и целевым видео словами. В анонсе H3 приведён пример: сослаться на движение камеры из одного видео, попросить персонажа из изображения петь, а вокал взять из аудио. Для Image-to-Video достаточно текстового элемента и кадра.

Рабочий учебный шаблон строится из трёх частей: субъект, движение, камера. Субъект называет, кто или что в кадре. Движение описывает, что происходит. Камера задаёт поведение объектива. Документация отмечает, что для более тонкого контроля инструкции по движению камеры добавляют прямо после ключевых описаний — например, [pan], [zoom], [static].

Субъект: [кто или что в кадре].
Движение: [что происходит — плавно, без резких переходов].
Камера: [static] — камера зафиксирована, либо [pan] влево, либо [zoom] медленно.
Сохранить: черты лица и одежду без изменений.

Меняйте под себя квадратные скобки: субъект, характер движения и метку камеры. Стоп-лист отдельным параметром API не объявляется — перечисление того, чего быть не должно, идёт обычным текстом внутри промпта. Формулируйте его утверждениями о желаемом результате: «фон остаётся ровным», «пропорции лица сохраняются».

Промпты для портрета, товара и пейзажа

Три готовых промпта под разные исходные фото. Цель каждого — удержать то, что важно в конкретном типе снимка.

Портрет: задача — мягкое движение без искажения лица.

Портрет: человек с фотографии слегка поворачивает голову и улыбается.
Движение: медленное, естественное, без резких рывков.
Камера: [static], лёгкий [zoom] к лицу.
Сохранить: черты лица, причёску, одежду и фон без изменений.

Товар: задача — показать предмет в движении, сохранив форму и надписи.

Товар: предмет на фотографии медленно поворачивается, демонстрируя боковую сторону.
Движение: равномерное вращение, блики скользят по поверхности.
Камера: [static], предмет остаётся в центре кадра.
Сохранить: форму, цвет, текстуру и текст на упаковке.

Пейзаж: задача — оживить статичный вид природным движением.

Пейзаж: в кадре движутся облака, трава колышется, вода слегка рябит.
Движение: медленное и непрерывное, в едином темпе.
Камера: [pan] вправо с постоянной скоростью.
Сохранить: линию горизонта, освещение и цвета снимка.

Промпты учебные: качество и сохранение лица заранее не гарантируются. Если сцена сложная, упростите её — меньше объектов и одно движение дают модели более ясную задачу.

Таблица допустимых сочетаний модели, разрешения и длительности

Сочетания берутся из раздела «Output Specs» документации MiniMax. Владелец факта — официальная документация платформы.

Анонс H3 на сайте MiniMax добавляет: модель генерирует видео с нативным стереозвуком, до 15 секунд при разрешении 2K. Разрешение 2K доступно по умолчанию. Для Image-to-Video параметр ratio фиксирован как adaptive, поэтому соотношение наследуется от кадра.

Для разрешения 2K и нативного звука выбирайте H3. Нужна скорость и хватает 480P или 768P — H3 Max. Длительность задаётся целым числом секунд в поле duration. Значения вне диапазона документация не описывает как допустимые.

Проверка результата и упрощение сцены

После скачивания ролика проверьте три вещи. Первое — целостность лица или предмета: черты не должны «плыть» между кадрами, форма товара и текст на упаковке остаются читаемыми. Второе — движение: оно выглядит равномерным, без рывков и внезапных скачков позы. Третье — стабильность камеры: при [static] кадр не дёргается, при [pan] смещение идёт с постоянной скоростью.

Если что-то не так, возможные причины — перегруженная сцена, слишком быстрый характер движения или конфликтующие инструкции камеры. Упрощение сцены — рабочий совет: оставьте один субъект и одно движение, уберите лишние объекты из описания. Это снижает число переменных, которые модель должна удержать. Гарантии исправления конкретного дефекта такой приём не даёт.

Полезный инструмент — задача H3-Context-IR. Документация описывает её так: она глубоко интерпретирует мультимодальный контекст и выдаёт структурированный расширенный промпт, сохраняя исходный замысел. Эта задача возвращает только улучшенный промпт и видео не создаёт. Готовый промпт можно затем подставить в запрос генерации. Для повторной попытки с тем же кадром помогает режим регенерации: если есть видео в спецификации 768P, задача Create Video Regeneration Task выдаёт версию 2K, воспроизводя весь исходный контент и добавляя один элемент с type=video_url и role=base_video.

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

Нужен ли VPN для Hailuo?
Документация MiniMax по генерации видео описывает работу через API по адресу https://api.minimax.io и не упоминает VPN. Доступность сервиса из конкретной страны в источниках этого разбора не описана. Для API-маршрута важен ключ и доступ к платному Pay-as-you-go API.

Сколько секунд может длиться ролик?
Документация задаёт диапазоны: MiniMax H3 — от 4 до 15 секунд, MiniMax H3 Max — от 5 до 15 секунд. Значения целые. Анонс H3 подтверждает длительность до 15 секунд при разрешении 2K.

Какие форматы фото принимаются?
Изображения: JPG, JPEG, PNG, WEBP, HEIC, HEIF. Размер до 30 МБ на файл, ширина и высота от 256 до 5760, соотношение сторон от 2:5 до 5:2. Для первого и последнего кадра допустимо одно или два изображения.

Почему лицо искажается при анимации?
Возможные причины — перегруженная сцена, быстрое движение или конфликтующие инструкции камеры. Упростите сцену: один субъект, одно движение, фиксированная камера. Гарантии исправления конкретного дефекта нет.

Как получить ссылку на готовое видео?
После создания задачи опрашивайте статус по task_id с интервалом 10 секунд. При статусе succeeded ответ содержит content.url — прямую ссылку на скачивание. Обмен file_id не требуется.