HiAPI
Блог

Руководство

Как использовать minimax-h3-max-turbo/image-to-video через HiAPI API: curl, Python и рабочие примеры запросов

Nov 17, 2026
Абстрактная обложка: широкие горизонтальные ступенчатые полосы терракотового и умбрового цвета спускаются по тёплому песочному фону с плоскими печатными краями.
На этой странице

Что делает этот эндпоинт и когда его использовать

minimax-h3-max-turbo/image-to-video принимает исходное изображение и текстовый промпт и возвращает короткое видео, начинающееся с этого изображения. Изображение служит первым кадром (или визуальным якорем), поэтому выходное видео наследует его композицию, цветовую палитру и идентичность субъекта. Затем промпт описывает, что должно произойти дальше — движение камеры, действие субъекта, атмосферу.

Когда выбирать его вместо text-to-video

Text-to-video подходит, когда у вас нет референсного визуала и вы хотите, чтобы модель создала всё сама. Image-to-video — правильный выбор, когда первый кадр сам по себе важен: у вас есть одобренное изображение продукта, ключевой кадр раскадровки, дизайн персонажа или загруженное пользователем фото, которое нужно оживить, сохранив узнаваемость. Конкретно, команды используют этот эндпоинт в следующих случаях:

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

Эндпоинт асинхронный: вы отправляете задачу, а затем получаете отрендеренное видео. Такая форма хорошо подходит для бэкендов, управляемых очередями; подробности ниже. Полный набор параметров см. на странице модели.

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

Перед вызовом эндпоинта убедитесь, что у вас есть четыре вещи:

  1. API-ключ. Создаётся в вашей учётной записи HiAPI и отправляется как bearer token. Считайте его конфиденциальным — никогда не встраивайте в клиентский код.
  2. Базовый URL. Все запросы отправляются на единый API-хост HiAPI; путь эндпоинта совпадает с идентификатором модели.
  3. Исходное изображение, доступное или кодируемое — либо публичный HTTPS URL, либо base64-полезная нагрузка, в зависимости от того, какую форму принимает схема запроса.
  4. HTTP-клиент — curl для быстрой проверки и любая стандартная библиотека или requests в Python для реальной интеграции.

Из чего состоит запрос

Независимо от языка, каждая отправка задачи содержит одни и те же концептуальные части:

  • Модель / эндпоинт — minimax-h3-max-turbo/image-to-video, входит в путь запроса и повторяется в теле запроса для ясности.
  • Исходное изображение — первый кадр. Это поле отличает image-to-video от text-to-video и чаще всего вызывает ошибки валидации.
  • Промпт — описание движения и сцены. Описывайте только то, что меняется, а не то, что уже есть на изображении.
  • Необязательные подсказки генерации — управление длительностью и стилем разрешения, если эндпоинт их предоставляет. Отправляйте только параметры, задокументированные в схеме; неизвестные ключи — частая причина ответов 4xx.

Отправка возвращает идентификатор задачи и статус. Само видео приходит позже через второй запрос — поэтому раздел о поллинге ниже так же важен, как и вызов отправки.

Рабочий запрос curl

Следующая команда отправляет задачу image-to-video. Перед запуском замените заполнители — заглавные метки в угловых скобках — своими значениями.

curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": "Медленный наезд камеры на продукт, мягкий студийный свет скользит по поверхности, малая глубина резкости."
  }'

Несколько практических замечаний к этой команде:

  • Читайте ключ из переменной окружения. $HIAPI_API_KEY не даёт ключу попасть в историю shell, если вы экспортируете его, а не вставляете в строку.
  • Для первой проверки используйте публичный URL изображения. Это исключает фактор base64-кодирования и одновременно подтверждает, что аутентификация и соединение работают.
  • Держите JSON-тело компактным. Полезная нагрузка -d — это весь запрос; одна пропущенная запятая здесь даст непонятный 400 вместо ясной ошибки схемы.
  • Заключайте промпт в кавычки. Промпты со знаками препинания ломают неэкранированные строки shell.

Ответ — это объект задачи, а не видео. Захватите из него ID задачи — он понадобится для запроса поллинга. Если вызов сразу завершился ошибкой, переходите к разделу устранения неполадок; ошибки аутентификации и полезной нагрузки проявляются на этом шаге, а не позже.

Тот же запрос на Python

Ниже — эквивалентный вызов отправки на Python с использованием requests. Предполагается, что HIAPI_API_KEY задан в переменных окружения.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"

payload = {
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": (
        "Медленный наезд камеры на продукт, мягкий студийный свет скользит "
        "по поверхности, малая глубина резкости."
    ),
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))

Что важно сохранить при адаптации этого фрагмента:

  • Тайм-аут не является опциональным. Отправка быстрая, но зависший сокет в обработчике веб-запросов потянет за собой и ваш worker.
  • raise_for_status() перед разбором. Он превращает молчаливый 401 в исключение, которое можно реально залогировать.
  • Возвращайте ID задачи, а не ответ. В сервисе функция отправки должна возвращать идентификатор, чтобы отдельный поллер — или фоновая задача — отвечал за ожидание.
  • Храните полезную нагрузку в переменной. После успешного вызова замена URL изображения на подписанный URL загрузки или base64-строку потребует изменения одной строки.

Здесь намеренно используется обычный HTTP-клиент, а не библиотека-обёртка: форма запроса — это контракт, и вы должны уметь воспроизвести её на любом языке вашего стека.

Подготовка изображения и первого кадра

Большинство неудачных задач image-to-video терпят крах на изображении, а не на промпте. Несколько привычек помогут этого избежать.

Формат и доставка

Используйте стандартный, широко поддерживаемый растровый формат — JPEG или PNG — и убедитесь, что URL общедоступен, не требует cookie, не перенаправляет на страницу входа и не зависит от истекающей подписи, сгенерированной после отправки. Если ваши ресурсы находятся в приватном бакете, сгенерируйте подписанный URL, время жизни которого заметно превышает ожидаемое время выполнения задачи. Для base64-полезных нагрузок уберите префикс data-URI, если схема ожидает сырые закодированные байты, и убедитесь, что закодированный размер с большим запасом укладывается в задокументированные ограничения.

Размер и композиция

Модель рендерит видео с фиксированным выходным размером, поэтому исходное изображение подгоняется. Два следствия:

  • Совпадайте с желаемым соотношением сторон. Вертикальное портретное фото, поданное в горизонтальный рендер, будет обрезано или получит чёрные полосы, а субъект может сместиться от центра.
  • Оставляйте запас для движения. Если промпт описывает наезд камеры или движение субъекта вверх, оставьте в исходном изображении пространство в этом направлении.

Сохраняйте целостность первого кадра

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

Не предполагайте наличия недокументированных параметров. Если нужного вам элемента управления нет в схеме, реализуйте его через промпт или подготовку изображения.

Обработка жизненного цикла асинхронной задачи

Задачи image-to-video не синхронны. Схема — отправить → опросить → получить, и производственная интеграция должна явно реализовывать все три шага.

1. Отправка и сохранение

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

2. Поллинг с экспоненциальной задержкой

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

  • Начинайте с умеренного интервала — нескольких секунд — и увеличивайте его по мере роста времени задачи, а не долбите эндпоинт с постоянной частотой.
  • Ограничьте общее время ожидания разумным для задачи пределом, затем считайте задачу просроченной и решите, повторять ли попытку.
  • Считайте конечное состояние конечным: как только задача сообщает об успехе или ошибке, прекращайте поллинг.
import time

def wait_for_job(poll_fn, job_id, max_wait=600):
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        job = poll_fn(job_id)
        if job["status"] in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"задача {job_id} не завершилась за {max_wait}с")

3. Получение и сохранение результата

После успеха объект задачи содержит расположение результата. Скачайте видео вовремя и скопируйте в собственное хранилище — URL результата следует рассматривать как временный ресурс, а не как вашу постоянную библиотеку ресурсов. Записывайте ID задачи рядом с сохранённым файлом, чтобы служба поддержки могла проследить любой фрагмент до его запроса.

Для повторов опрашивайте только задачи с уже сохранёнными ID; никогда не отправляйте повторно вслепую, иначе получите дублирующие рендеры и двойную оплату.

Устранение типичных ошибок

Ошибки аутентификации (401 / 403)

Сначала проверьте заголовок Authorization: слово Bearer, один пробел, затем ключ, и никакого завершающего символа новой строки, прихваченного при копировании ключа. Убедитесь, что ключ активен и принадлежит нужной вам учётной записи. Если curl работает, а Python нет, выведите длину заголовка — пустая переменная окружения даст внешне корректный, но бесполезный token.

Некорректная или неподдерживаемая полезная нагрузка изображения (400 / 422)

Самая частая ошибка, не связанная с аутентификацией. Проверяйте по порядку:

  • URL изображения разрешается нормально и не перенаправляет на HTML-страницу входа.
  • Формат — JPEG или PNG, а не WebP, HEIC или миниатюра PDF.
  • Размер после кодирования или скачивания в пределах задокументированных ограничений.
  • В base64-полезной нагрузке нет префикса data: и нет пробелов от переносов строк.
  • Изображение не повреждено — скачайте и откройте его сами, прежде чем винить API.

Неизвестные или недействительные параметры

Опечатка в имени поля или параметр, который эндпоинт не предоставляет, обычно возвращает ошибку валидации с указанием этого поля. Уберите предположительные параметры и восстановите запрос из минимального набора, заданного документацией.

Ограничения скорости (429)

Используйте экспоненциальную задержку и соблюдайте любые подсказки о повторе из ответа. Не повторяйте в плотном цикле; это только усугубит ограничение. Если вы сталкиваетесь с этим часто, отправляйте пакетами через очередь, а не напрямую из пользовательского запроса.

Тайм-ауты задач и зависший поллинг

Если задача так и не достигла конечного состояния в пределах вашего бюджета, залогируйте ID задачи и историю статусов и прекратите поллинг. Постоянные тайм-ауты обычно указывают на слишком большое или необычное изображение при отправке, поэтому вернитесь к разделу о подготовке изображения. Не повторяйте отправку автоматически без верхнего предела попыток.

Чек-лист перед запуском в производство

Прежде чем этот эндпоинт приблизится к реальному трафику, проверьте следующее:

  • Тайм-ауты везде. Отправка с коротким тайм-аутом, для поллинга задан общий предел ожидания, у попыток повтора есть жёсткий предел. Никаких неограниченных циклов while True.
  • Повторы с задержкой. Повторяйте при 429 и транзиентных ответах 5xx; никогда не повторяйте ошибки валидации — они упадут так же.
  • ID задач в логах. Логируйте для каждого запроса ID задачи, ваш корреляционный ID и итоговый статус. Это самый полезный артефакт отладки, который у вас будет.
  • Результаты в вашем хранилище. Копируйте готовые видео с возвращённого URL в постоянное хранилище и сохраняйте ссылку на исходное изображение для воспроизводимости.
  • Валидация изображений на периферии. Отклоняйте неверные форматы и слишком большие загрузки до обращения к API, чтобы пользователи сразу получали ясную ошибку, а не асинхронный сбой через несколько минут.
  • Осознание затрат. Генерация тарифицируется за каждый выходной результат отрендеренного видео, поэтому отслеживайте объём и длительность задач по пользователю или функции. Сверяйтесь с актуальной панелью цен, а не зашивайте предположения в код или документацию.
  • Канареечный промпт. Держите в тестовом наборе известный рабочий набор изображений и промптов и запускайте его после любого изменения интеграции, чтобы подтвердить, что контракт запроса всё ещё выполняется.

Как только асинхронный жизненный цикл обрабатывается правильно — отправка, сохранение, поллинг, хранение — эндпоинт становится простым. Возьмите точную схему со страницы модели, затем подключите описанные выше шаблоны отправки и поллинга.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API