HiAPI
Блог

Руководство

Как использовать minimax-h3 через HiAPI API: curl, Python и рабочие запросы

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

Как выглядит интеграция minimax-h3 от начала до конца

Генерация видео — не мгновенная операция. minimax-h3 должен принять подсказку или исходное изображение, запланировать задачу в пуле GPU, закодировать кадры и собрать выходной файл. Весь процесс в зависимости от длительности и разрешения может занять от нескольких секунд до нескольких минут. Если конечная точка HiAPI блокируется до готовности файла, ваш HTTP-клиент будет занимать открытое соединение всё это время — это хрупко при повторных попытках, недружелюбно к ограничениям времени бессерверных функций и не может работать в обработчиках Web с моделью запрос/ответ.

Поэтому интеграция следует форме сначала отправка, затем опрос, что является стандартным паттерном для асинхронных медиа-API:

  1. Отправка. Вы выполняете POST с JSON-нагрузкой, описывающей задачу (подсказка, необязательное изображение, длительность, соотношение сторон и любые специфичные для модели параметры). API проверяет её и немедленно возвращает идентификатор задачи и начальный статус.
  2. Опрос. С этим идентификатором вы вызываете конечную точку статуса задачи через короткие интервалы. Статус проходит через состояния в очереди, в обработке, а затем успех или неудача.
  3. Получение. Как только статус переходит в терминальное состояние, ответ несёт результат — обычно загружаемый URL сгенерированного видео.

Эта модель влечёт три следствия, которые определяют всё дальнейшее в этом руководстве:

  • ID задачи — ваш единственный дескриптор. Сохраняйте его. Если вы его потеряете, вы не сможете получить задачу; останется только повторно отправить её и снова заплатить за работу.
  • У вашего кода две поверхности отказа, а не одна. Отправка может не удаться (аутентификация, некорректная нагрузка), и опрос тоже может не удаться (тайм-аут, временная сетевая ошибка, задача завершилась неудачей). Обрабатывайте их раздельно.
  • Ритм опроса — это проектное решение. Слишком агрессивный тратит запросы; слишком медленный заставляет пользователя ждать состояния, которое давно готово.

В этой статье все вызовы направляются в единый API HiAPI. Вам нужно получить ключ API из вашей учётной записи HiAPI и ссылаться на модель как minimax-h3 в нагрузке. Всё остальное — заголовок аутентификации, базовый URL, конечная точка опроса — общее для всей платформы, поэтому изученный здесь паттерн можно перенести на другие модели без перестройки клиента.

С этой ментальной моделью самый быстрый способ проверить настройку — один вызов curl.

Ваш первый рабочий запрос curl

Прежде чем писать код приложения, убедитесь, что ваш ключ действителен и API доступен. Одноразовая команда curl — самый дешёвый способ отличить проблему аутентификации от проблемы нагрузки.

Сначала экспортируйте ключ, чтобы он не попал в историю оболочки в буквальном виде:

export HIAPI_API_KEY="your-api-key-here"

Затем отправьте минимальную задачу генерации видео из текста:

curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Успешный ответ возвращает JSON-объект, содержащий идентификатор задачи и статус. Его структура примерно такая:

{
  "id": "task_abc123xyz",
  "status": "queued",
  "model": "minimax-h3",
  "created_at": "2024-01-01T00:00:00Z"
}

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

Что делает каждая часть запроса

  • URL указывает на ресурс генерации видео на платформе HiAPI. Все вызовы моделей используют эту базу, поэтому переключение модели — это изменение нагрузки, а не переписывание кода.
  • Authorization: Bearer несёт ваш ключ API. Это самый частый источник сбоев, поэтому при проблемах сначала проверяйте его.
  • Content-Type: application/json обязателен. Без него сервер может отклонить или неверно разобрать тело запроса.
  • model явно выбирает minimax-h3. Никогда не опускайте его — платформа маршрутизирует по этому значению.
  • prompt — творческая инструкция. Будьте конкретны в отношении субъекта, движения камеры и освещения; расплывчатая подсказка даст расплывчатое видео.
  • duration и aspect_ratio ограничивают вывод. Держите их в пределах поддержки модели; значения вне диапазона — это ошибка валидации нагрузки, а не сбой сервера.

Убедитесь, что задача существует

Сразу после отправки получите задачу один раз, чтобы доказать, что ID действителен:

curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Замените task_abc123xyz на ID из ответа на отправку. Если это вернуло статус, значит ваш ключ, конечная точка и дескриптор задачи верны — можно переходить к Python.

Сейчас стоит выработать две привычки: запускать curl с -sS, чтобы ошибки всплывали, а не проглатывались молча, и всегда брать URL в кавычки. Неожиданное раскрытие оболочки в JSON-нагрузке — ловушка отладки, которая стоит гораздо больше времени, чем сами кавычки.

Создание того же запроса на Python

Вызов curl подтвердил контракт; Python — то место, где вы строите переиспользуемое. Не переходите сразу к циклу опроса, а начните с небольшого класса клиента, который обрабатывает отправку и получение результата двумя чёткими методами. Это разделение выводит асинхронную логику из вашего транспортного слоя.

Используйте requests (или httpx, если предпочитаете асинхронность); форма в обоих случаях одинакова.

import os
import time
import requests

BASE_URL = "https://api.hiapi.ai/v1"

class MiniMaxH3Client:
    def __init__(self, api_key: str | None = None):
        self.api_key = api_key or os.environ["HIAPI_API_KEY"]
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        })

    def submit(self, prompt: str, duration: int = 5,
               aspect_ratio: str = "16:9", **extra) -> str:
        payload = {
            "model": "minimax-h3",
            "prompt": prompt,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
            **extra,
        }
        resp = self.session.post(
            f"{BASE_URL}/video/generations",
            json=payload,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        return data["id"]

Здесь есть несколько намеренных решений, которые стоит отметить.

Используйте session, а не голый requests. Повторное использование requests.Session поддерживает соединение активным между вызовами отправки и опроса, что важно, когда вы многократно опрашиваете один и тот же хост. Он также централизует управление заголовками, поэтому заголовок аутентификации определяется один раз.

Устанавливайте жёсткий тайм-аут при отправке. Для запроса, который должен вернуться почти сразу, тридцать секунд — щедро. Без тайм-аута сетевая дрожь заставит ваш процесс висеть бесконечно. Никогда не вызывайте удалённый API без timeout.

Вызывайте raise_for_status() перед разбором. Тело ответа при не-2xx обычно имеет другую форму, чем при успехе. Проверка кода состояния сначала означает, что ваш обработчик ошибок читает правильно сформированное сообщение об ошибке, а не падает при отсутствии ключа id.

Проброс **extra. Специфичные для модели опции развиваются. Проброс дополнительных именованных аргументов позволяет экспериментировать с новыми параметрами, не редактируя сигнатуру метода каждый раз.

Использование

client = MiniMaxH3Client()
task_id = client.submit(
    "A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")

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

Опрос результата без бомбардировки API

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

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

TERMINAL = {"succeeded", "failed", "cancelled"}

def wait_for(self, task_id: str, interval: float = 3.0,
             max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status", "unknown")
        if status in TERMINAL:
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")

Выбор интервала

Для генерации видео фиксированные несколько секунд — разумное значение по умолчанию. Задача не завершится в первые секунды — загрузка модели и кодирование кадров требуют реального времени — поэтому опрос каждые 200 мс не даёт ничего, кроме нагрузки. Если вы хотите быть одновременно вежливым и эффективным, используйте экспоненциальную задержку с верхним пределом: начните с одной-двух секунд, умножайте примерно на 1,5 на каждом раунде, пока не достигнете пяти или десяти секунд, затем оставайтесь там. Ранний опрос быстро ловит быстрые сбои; поздний опрос сохраняет низкую стоимость во время длительного рендеринга.

Правильная остановка

Считайте любой нераспознанный статус нетерминальным и продолжайте ждать — но только до определённого предела. Важны два условия остановки:

  • Терминальный статус. При успехе немедленно верните результат. При неудаче выведите сообщение об ошибке из ответа, а не возвращайте пустой результат; причина важна для ваших логов.
  • Реальный бюджет времени. Используйте монотонные часы, а не настенные, чтобы корректировка системных часов не заставила ваш цикл выйти раньше или работать вечно. Выберите предел, который с запасом превышает самую долгую реальную задачу для выбранной длительности и разрешения, и рассматривайте его достижение как операционную ошибку, требующую оповещения.

Возврат результата

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

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

Форма запросов для генерации видео из текста и из изображения

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

Генерация видео из текста

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

  • model: minimax-h3
  • prompt: описание сцены
  • duration, aspect_ratio и любые другие элементы управления выводом

Поскольку нет никакой привязки, качество подсказки доминирует в результате. Описывайте поведение камеры («медленное приближение», «статичный кадр на штативе») и освещение («контровой свет в золотой час»), а не нагромождайте прилагательные о качестве. Расплывчатые прилагательные высшего уровня мало что дают; конкретные физические описания дают много.

Генерация видео из изображения

Вариант из изображения добавляет ссылку на исходное изображение в тот же запрос. Обычно вы указываете URL изображения или идентификатор загруженного ресурса в поле изображения рядом с подсказкой, и модель анимирует от этого начального кадра.

client.submit(
    "Gentle wind moves the hair, subtle camera push forward",
    duration=5,
    image_url="https://example.com/portraits/source.jpg",
)

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

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

Практическое эмпирическое правило

Выбирайте генерацию из текста, когда вам нужны новые сцены — B-roll, эмоциональные фрагменты, концептуальные визуализации. Выбирайте генерацию из изображения, когда важна согласованность: анимация продуктовых фото, оживление портретов персонажей или превращение кадров раскадровки в движущиеся планы. Режим — это различие в нагрузке, а не в интеграции, поэтому один класс клиента обслуживает оба, если только принимает необязательный параметр изображения.

Отладка частых ошибок

Когда вызов minimax-h3 идёт не так, причина почти всегда в одном из четырёх мест. Проверяйте в этом порядке.

1. Аутентификация

Симптом: ответ 401 или 403, или тело ошибки утверждает, что учётные данные недействительны.

  • Убедитесь, что заголовок Authorization присутствует и имеет вид Bearer <key> с одним пробелом между.
  • Проверьте, что переменная окружения действительно содержит значение — завершающий перевод строки, вставленный в переменную окружения, незаметно для логов испортит заголовок.
  • Убедитесь, что ключ принадлежит тому же проекту HiAPI, который вы ожидаете, и не был перевыпущен.

Самый быстрый тест: повторно запустите предыдущий необработанный curl. Если curl работает, а Python нет, ошибка в вашем клиенте, а не в вашей учётной записи.

2. Некорректная нагрузка

Симптом: ответ 400 или 422, или сообщение валидации с указанием параметра.

  • Убедитесь в Content-Type: application/json и что тело — валидный JSON — лишняя завершающая запятая классический виновник.
  • Проверьте, что model точно minimax-h3.
  • Убедитесь, что duration и aspect_ratio в пределах поддержки модели.
  • В режиме изображения убедитесь, что ссылка на изображение доступна и в принимаемом формате.

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

3. Опрос никогда не завершается

Симптом: статус остаётся в очереди или в обработке после разумного времени, или цикл вечный.

  • Записывайте полный ответ статуса — значение статуса может не совпадать с тем, что предполагает ваш код.
  • Проверьте, какое поле вы читаете. Если ваш терминальный набор проверяет "completed", а API возвращает "succeeded", ваш цикл будет работать вечно. Распечатайте сырой ответ на раннем этапе разработки.
  • Убедитесь, что ID задачи скопирован точно, без усечения или пробелов.
  • Добавьте реальный дедлайн; застрявший цикл без верхнего предела — баг вашего кода, а не API.

4. Тайм-ауты и временные сетевые ошибки

Симптом: ошибки соединения, тайм-ауты чтения или ответы 5xx при отправке или опросе.

  • Убедитесь, что каждый вызов передаёт явный timeout — у многих клиентов по умолчанию значение отсутствует, то есть зависший сокет может блокировать навсегда.
  • Различайте тайм-аут соединения и тайм-аут чтения; отправка с тайм-аутом чтения могла фактически создать задачу. Если вернулся ID запроса, запишите его из заголовков ответа и проверьте, не появилась ли задача, прежде чем слепо повторять.
  • Для 5xx при опросе повторяйте — задача, вероятно, в порядке. Для 5xx при отправке проверьте, что задача не создана, чтобы избежать дублирования генерации.

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

Приведение к готовности к production

Рабочий скрипт — это не рабочий сервис. Видеозадачи достаточно медленны, чтобы production-трафик перекрывался, повторялся и иногда падал так, как никогда не выявит один ручной запуск. Большую часть веса несут четыре паттерна.

Повторы с задержкой — но только там, где безопасно

Стратегия повторов зависит от того, какой вызов не удался:

  • Опрос по своей природе безопасен для повторов. Неудачная проверка статуса не имеет побочных эффектов, поэтому повторяйте с экспоненциальной задержкой и джиттером, ограничиваясь несколькими попытками.
  • Отправка не может повторяться слепо. Тайм-аут не означает, что задача не создана. Прежде чем повторять, проверьте, существует ли уже задача для этого запроса (используйте ID запроса из заголовков ответа, если доступен, или короткое окно сверки). Либо сделайте свои отправки идемпотентными, кэшируя ID задачи по хешу нагрузки, чтобы повторённый запрос возвращал существующую задачу, а не запускал новый рендеринг.
  • Сбои на уровне модели — терминальный статус failed — обычно не следует автоматически повторять с той же нагрузкой. Одинаковый вход склонен падать одинаково. Запишите, оповестите и передайте человеку или изменённой подсказке.

Добавляйте джиттер в каждую паузу задержки. Без него партия синхронно повторяющих воркеров создаёт синхронные пики, делая плохую ситуацию хуже.

Логируйте ID задачи повсюду

ID задачи — единственная постоянная связь между вашей системой и сгенерированным видео. В момент успешной отправки запишите его в логи со структурированными полями — task_id, модель, длительность, временная метка отправки. Когда пользователь сообщает о потерянном видео, поиск по ID задачи найдёт полную историю за секунды. Также записывайте терминальный статус и прошедшее время, чтобы вы могли отвечать на вопрос «сколько это обычно занимает» данными, а не памятью.

Установите явный бюджет тайм-аутов

Думайте с точки зрения общего бюджета на всю операцию, а не только тайм-аута каждого запроса. У задачи три фазы — отправка, ожидание, загрузка — и каждой нужны границы. Разумная структура:

  • Короткие тайм-ауты для запросов отправки и опроса, чтобы быстро обнаруживать мёртвые соединения.
  • Общий реальный предел времени опроса, установленный по самой длинной поддерживаемой вами длительности и разрешению с запасом.
  • Ограниченная загрузка с потоковой записью, чтобы большие файлы не исчерпывали память или не подвешивали воркер.

Когда бюджет исчерпан, чисто провалите задачу, освободите слот параллелизма и сообщите понятную ошибку. Предсказуемый сбой лучше, чем запрос, который висит, пока платформа не перезапустит контейнер.

Отделите отправку от потребления

Дизайн «сначала отправка, затем опрос» естественно отображается на архитектуру очередей: ваш Web-обработчик отправляет и возвращает ID задачи, фоновый воркер опрашивает и сохраняет результат, клиент опрашивает вашу конечную точку статуса. Это отделяет задержку, видимую пользователю, от времени рендеринга, делает ограничения параллелизма легко исполняемыми и означает, что всплеск отправок не исчерпает пул потоков вашего Web-слоя.

Справившись с этими четырьмя пунктами, вы заставите асинхронную форму minimax-h3 работать с вами, а не против вас: задачи отслеживаются, повторы безопасны, сбои видны, и ничто не висит бесконечно.

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

Все статьи →

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

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

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