Руководство
Как использовать minimax-h3-max-turbo/image-to-video через HiAPI API: curl, Python и рабочие примеры запросов
На этой странице
Что делает этот эндпоинт и когда его использовать
minimax-h3-max-turbo/image-to-video принимает исходное изображение и текстовый промпт и возвращает короткое видео, начинающееся с этого изображения. Изображение служит первым кадром (или визуальным якорем), поэтому выходное видео наследует его композицию, цветовую палитру и идентичность субъекта. Затем промпт описывает, что должно произойти дальше — движение камеры, действие субъекта, атмосферу.
Когда выбирать его вместо text-to-video
Text-to-video подходит, когда у вас нет референсного визуала и вы хотите, чтобы модель создала всё сама. Image-to-video — правильный выбор, когда первый кадр сам по себе важен: у вас есть одобренное изображение продукта, ключевой кадр раскадровки, дизайн персонажа или загруженное пользователем фото, которое нужно оживить, сохранив узнаваемость. Конкретно, команды используют этот эндпоинт в следующих случаях:
- Первый кадр — обязательное требование. Маркетинговой команде нужно начать с точного главного изображения, а не с похожего.
- Важна согласованность между фрагментами. Повторное использование одного и того же исходного изображения сохраняет стабильность персонажа или продукта в серии фрагментов.
- Вы анимируете пользовательский контент. Загруженные конечными пользователями фотографии должны быть анимированы, а не переосмыслены.
- Вы хотите более узкий диапазон промпта. Описать движение проще, чем всю сцену с нуля, поэтому промпт остаётся коротким и предсказуемым.
Эндпоинт асинхронный: вы отправляете задачу, а затем получаете отрендеренное видео. Такая форма хорошо подходит для бэкендов, управляемых очередями; подробности ниже. Полный набор параметров см. на странице модели.
Предварительные условия и структура запроса
Перед вызовом эндпоинта убедитесь, что у вас есть четыре вещи:
- API-ключ. Создаётся в вашей учётной записи HiAPI и отправляется как bearer token. Считайте его конфиденциальным — никогда не встраивайте в клиентский код.
- Базовый URL. Все запросы отправляются на единый API-хост HiAPI; путь эндпоинта совпадает с идентификатором модели.
- Исходное изображение, доступное или кодируемое — либо публичный HTTPS URL, либо base64-полезная нагрузка, в зависимости от того, какую форму принимает схема запроса.
- 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, чтобы пользователи сразу получали ясную ошибку, а не асинхронный сбой через несколько минут.
- Осознание затрат. Генерация тарифицируется за каждый выходной результат отрендеренного видео, поэтому отслеживайте объём и длительность задач по пользователю или функции. Сверяйтесь с актуальной панелью цен, а не зашивайте предположения в код или документацию.
- Канареечный промпт. Держите в тестовом наборе известный рабочий набор изображений и промптов и запускайте его после любого изменения интеграции, чтобы подтвердить, что контракт запроса всё ещё выполняется.
Как только асинхронный жизненный цикл обрабатывается правильно — отправка, сохранение, поллинг, хранение — эндпоинт становится простым. Возьмите точную схему со страницы модели, затем подключите описанные выше шаблоны отправки и поллинга.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий