Руководство
Как вызывать minimax-h3-max-turbo для генерации видео из текста через HiAPI API
- Модель
- minimax-h3-max-turbo
На этой странице
Что делает этот эндпоинт и когда его использовать
minimax-h3-max-turbo/text-to-video — это эндпоинт модели генерации видео из текста, доступный через HiAPI API. Вы отправляете текстовый промпт, описывающий нужную сцену, плюс несколько параметров, управляющих формой вывода, и HiAPI возвращает сгенерированное видео. Эта модель отлично подходит, когда у вас есть текстовое описание, но нет исходных материалов: рекламные ролики, переходные кадры для соцсетей, превью раскадровок, фоновые зацикленные видео для приложений или пакетная генерация вариаций одной и той же креативной концепции.
Прежде чем писать код, обратите внимание на несколько особенностей:
- Это эндпоинт генерации, а не шаблон. Вывод предсказуем только по структуре (вы получите видео), но не по содержанию. Относитесь к каждой задаче как к новой рендеринговой операции и проектируйте промпты с расчётом на повторное использование.
- Он асинхронный. Вызов отправки задачи не возвращает байты готового видео напрямую. Сначала вы получаете идентификатор задачи, затем опрашиваете результат. Любая интеграция, рассчитанная на синхронный ответ, сломается на первом же таймауте.
- Вывод определяется параметрами запроса. Длительность и разрешение влияют на стоимость рендеринга и фактическое время выполнения, поэтому выбранные вами параметры одновременно являются решением о задержке и бюджете.
- Исходные медиа не нужны. Вам не нужно загружать видео или изображения; промпт и параметры — это вся входная поверхность.
Когда стоит использовать другое решение? Если у вас уже есть материалы и вы хотите их стилизовать или расширить, этот эндпоинт не подходит. Если вам нужен покадровый контроль движения камеры или точной композиции, текстовый промпт окажется слишком свободным. А если вам нужна только статичная картинка, эндпоинт генерации изображений дешевле и быстрее. Используйте minimax-h3-max-turbo/text-to-video, когда промпта достаточно в качестве спецификации кадра.
Остальная часть руководства последовательно охватывает аутентификацию, рабочий вызов curl, эквивалентный вызов Python, жизненный цикл задачи, ключевые параметры, ошибки, с которыми вы столкнётесь, и шаги по усилению надёжности перед запуском в продакшен.
Предварительные требования и аутентификация
Перед первым запросом вам понадобятся три вещи:
- API-ключ аккаунта HiAPI. Относитесь к нему как к секрету: загружайте из переменной окружения, никогда не коммитьте в репозиторий и немедленно ротируйте при утечке.
- Базовый URL HiAPI. Все вызовы в этом руководстве отправляются на один и тот же базовый хост; модель выбирается сегментом пути, а не отдельным доменом для каждой модели.
- HTTP-клиент. curl для дымового тестирования, любая стандартная библиотека или HTTP-клиент для сервисного кода.
Как передаётся ключ
HiAPI аутентифицирует запросы с помощью bearer-токена в заголовке Authorization. Форма всегда одна и та же:
export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Две привычки сэкономят массу времени на отладку:
- Заголовок должен быть написан точно. В
Authorizationбуква A заглавная, послеBearerидёт один пробел, затем ключ. Отсутствие одного пробела — самая частая причина загадочного 401. - Всегда отправляйте
Content-Type: application/json. Сервер, ожидающий JSON, отклонит или неверно разберёт тело запроса без этого заголовка, а полученная вами ошибка часто сообщает об отсутствующем поле, а не о настоящей причине.
Сначала проверьте, потом разрабатывайте
Не начинайте сразу с видеоэндпоинта. Сначала сделайте дешёвый и быстрый вызов, чтобы убедиться, что ключ и базовый URL разрешаются правильно, а затем продолжайте. Если эта проверка работоспособности не пройдёт, ничего ниже работать не будет, и вы будете отлаживать не тот уровень. Храните ключ в одном месте кодовой базы — в небольшом клиентском модуле, — чтобы будущая ротация требовала изменения одной строки.
Рабочий curl-запрос
Вызов отправки передаёт промпт и параметры как JSON-тело на путь модели. Вот минимальный рабочий вызов:
curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "На рассвете медленный воздушный наезд камеры над туманным сосновым лесом, мягкий объёмный свет, кинематографично",
"duration": 5,
"resolution": "720p"
}'
Что делает каждая часть:
-X POST— задачи генерации создаются через POST.- URL — базовый хост плюс путь
minimax-h3-max-turbo/text-to-video. Держите базовый хост в переменной, чтобы тестирование и продакшен шли по одному и тому же пути кода. Authorization— bearer-токен, описанный в предыдущем разделе.Content-Type— объявляет JSON-тело.prompt— единственный обязательный креативный вход. Пишите его как описание кадра: субъект, поведение камеры, освещение и атмосфера. Короткие именные группы дают расплывчатые результаты; одно-два предложения с конкретным визуальным направлением работают гораздо лучше.durationиresolution— параметры, управляющие формой вывода, им посвящён отдельный раздел ниже.
Используйте -sS, чтобы curl работал тихо, но всё же выводил ошибки; на этапе исследования выводите ответ через инструмент красивого форматирования. Ответ — это JSON с идентификатором задачи; сохраните его, так как он нужен для опроса готового видео. Не ожидайте, что в этом ответе будут байты видео.
Если при отладке хотите видеть, что именно отправляется, добавьте -v для подробного вывода, но удалите его перед публикацией логов, так как подробный вывод может содержать заголовки.
Эквивалентный запрос на Python
Версия на Python — тот же самый запрос, только ключ загружается из окружения, а ответ разбирается. Вот небольшой переиспользуемый клиент:
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"
def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
resp = requests.post(
f"{BASE_URL}{MODEL_PATH}",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job = submit_video(
"На рассвете медленный воздушный наезд камеры над туманным сосновым лесом, мягкий объёмный свет, кинематографично"
)
print(job)
Замечания при адаптации:
json=payloadзадаёт и тело запроса, и тип содержимого; не сериализуйте вручную повторно.timeout=30ограничивает время вызова отправки. Отправка быстрая, рендеринг — нет, поэтому здесь таймаут короткий, а ожидание ложится на опрос.raise_for_status()превращает не-2xx ответы в исключения, чтобы сбои аутентификации и валидации сразу проявлялись, а не тихо возвращали тело с ошибкой, которое вы позже ошибочно примете за задачу.- Возвращайте разобранный JSON как словарь и извлекайте идентификатор задачи в месте вызова. Так вспомогательная функция остаётся универсальной, а код оркестрации решает, что с ним делать.
Если вы используете асинхронный стек, та же форма применима к выбранному вами HTTP-клиенту: соберите заголовки один раз, сделайте POST тела, проверьте статус и верните разобранное тело ответа.
Обработка жизненного цикла асинхронной задачи
Генерация требует времени, поэтому эндпоинт разделён на отправку и опрос. Жизненный цикл всегда таков: отправить, получить идентификатор задачи, опрашивать задачу до сообщения о терминальном состоянии, затем получить вывод.
Отправка
Отправьте POST, описанный выше, и прочитайте идентификатор задачи из ответа. Сразу залогируйте его и свяжите с вашим собственным ID запроса, чтобы позже при сбое опроса можно было проследить путь к исходному промпту.
Опрос с экспоненциальной задержкой
Не опрашивайте в плотном цикле. Начните с короткого интервала, затем увеличивайте:
def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
deadline = time.time() + max_wait
interval = 2.0
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}{MODEL_PATH}/{job_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
status = job.get("status")
if status in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 15.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Три детали делают этот код надёжным. Во-первых, дедлайн: всегда в конце концов сдавайтесь и выбрасывайте таймаут, а не опрашивайте вечно. Во-вторых, ограниченная задержка: начинайте с нескольких секунд, постепенно увеличивайте и ограничивайте интервал сверху, чтобы продолжать добиваться прогресса, не обрушивая API. В-третьих, обработка терминальных состояний: считайте терминальными только успех и неудачу и возвращайте объект задачи, чтобы вызывающий код мог ветвиться.
Получение результата
Как только задача сообщает об успехе, ответ несёт местоположение готового видео. Скачайте или передайте потоком в собственное хранилище как можно скорее и залогируйте URL вместе с ID задачи. Не предполагайте, что ссылка постоянна, и не получайте видео на каждой итерации опроса. Опрашивайте статус задачи, а затем получайте видео один раз при успехе.
Параметры длительности и разрешения
Два параметра запроса определяют вывод, а также время рендеринга и стоимость вызова.
duration
Длина сгенерированного фрагмента. Чем длиннее фрагмент, тем пропорционально больше время рендеринга, а значит, длиннее окно опроса и выше вероятность срабатывания клиентского таймаута. Практические советы:
- Согласуйте длительность с用例. Переходные кадры для соцсетей короткие; фоновому циклу нужно быть лишь настолько длинным, чтобы приемлемо зацикливаться. Генерировать более длинный контент, чем будет показано, — чистая трата.
- Начинайте с малого при итерации. Настраивайте промпт на короткой длительности, затем перерендеривайте победивший промпт в финальной длине.
- Помните, что стоимость растёт с объёмом вывода. Биллинг рассчитывается по длине вывода, поэтому длительность — это и креативный, и бюджетный рычаг.
resolution
Пространственное качество вывода. Более высокое разрешение даёт больше деталей, но расходует больше времени рендеринга и больше денег. Советы:
- Выбирайте по сценарию доставки, а не по таблице характеристик. Если видео будет в ленте или маленьком плеере, генерация с разрешением выше этого сценария не даст никакой выгоды.
- Итерируйте в низком разрешении, сдавайте в высоком. Пока промпт ещё меняется, просматривайте в низком разрешении, затем отправляйте одобренный промпт повторно в разрешении для доставки.
- Более высокие настройки означают более долгое ожидание. Устанавливайте дедлайн опроса под максимальную разрешённую вами комбинацию, а не под минимальную.
Держите оба значения в одном объекте конфигурации, а не разбросанными по коду, чтобы переход от превью к продакшену был осознанной и видимой правкой, а не забытым литералом.
Отладка частых ошибок
Большинство сбоев сводится к четырём категориям. Прежде чем менять код, сопоставьте симптом с категорией.
Сбой аутентификации
401 означает, что HiAPI не принимает ваши учётные данные. Проверяйте по порядку: заголовок Authorization присутствует и написан правильно; после Bearer ровно один пробел; ключ действующий и не из другого проекта; переменная окружения действительно загружена (перевод строки в конце при вставке ключа — классическая проблема). Убедитесь, выведя длину переменной, а не сам ключ.
Сбой валидации
4xx, отличный от 401, обычно означает ошибку в теле запроса. Content-Type отсутствует или не application/json; prompt отсутствует или пуст; duration или resolution вне допустимого набора. Читайте сообщение об ошибке буквально; оно обычно указывает проблемное поле. Воспроизведите через версию curl, так как там нет библиотечного слоя, скрывающего тело запроса.
Таймауты
Есть два разных таймаута. Таймаут отправки означает, что сам POST не вернулся, что обычно указывает на сетевой путь или слишком агрессивный клиентский таймаут. Таймаут опроса означает, что задача не достигла терминального состояния до вашего дедлайна; либо рендеринг действительно требует больше времени, либо ваш дедлайн установлен под настройки превью, а не продакшена. Для исправления последнего увеличьте max_wait под большие длительности и разрешения, а не сокращайте интервал опроса.
Ошибки опроса
Более коварные. Опрос без сна тратит квоту и провоцирует ограничение частоты; опрос с фиксированным коротким интервалом даёт тот же эффект. Опрос неверного ID задачи, обычно потому что вы переиспользовали переменную между отправками. Принятие промежуточного состояния за ошибку. А также получение URL видео на каждой итерации вместо одного раза при успехе. Логируйте ID задачи и каждое наблюдаемое состояние; последовательность сразу скажет, какой из случаев вы поймали.
Чек-лист перед продакшеном
Переход от рабочего скрипта к сервису, работающему без присмотра, означает добавление нескольких слоёв вокруг одного и того же запроса.
- Повторы с джиттером. Повторяйте при временных сетевых ошибках и 5xx-ответах с экспоненциальной задержкой и рандомизацией. Никогда не повторяйте ошибки валидации; они провалятся так же и消耗уют квоту.
- Ограниченные таймауты везде. Короткий таймаут для отправки, более длинный дедлайн для опроса (под максимально разрешённые вами длительность и разрешение), и таймаут для скачивания видео.
- Структурированное логирование. Логируйте ваш ID запроса, ID задачи, каждый наблюдаемый переход состояния и финальный результат, но не логируйте API-ключ или полные заголовки. Когда в три часа ночи что-то сломается, этот лог будет вашим единственным доказательством.
- Идемпотентность на вашем слое. Ведите сопоставление вашего собственного ID запроса с ID задачи, чтобы клиентский повтор не создавал молча второй рендер.
- Контроль расходов. Биллинг рассчитывается по длине вывода, поэтому задайте верхние границы длительности и разрешения, принимаемые сервисом, и держите превью промптов на низких настройках, пока финальный рендер не будет одобрен человеком или правилом.
- Гигиена ключей. Загружайте ключи из хранилища секретов, ротируйте по расписанию, используйте разные ключи для теста и продакшена, чтобы утёкший тестовый ключ не мог消耗ть продакшен-бюджет.
- Принадлежность результатов. Как только задача успешна, сразу копируйте готовое видео в хранилище под вашим контролем и относитесь к URL доставки как к временной ссылке.
С этими мерами эндпоинт станет предсказуемой зависимостью, а не источником сюрпризов. Сначала подтвердите учётные данные приведённым выше curl-запросом, затем внедрите Python-клиент в ваш сервис и оберните его проверками из этого чек-листа.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий