Руководство
Как вызывать minimax-h3-image для преобразования изображения в изображение через curl и Python на hiapi
На этой странице
Что ожидает эндпоинт преобразования изображения в изображение
Прежде чем писать код, полезно понять структуру вызова преобразования изображения в изображение. Эндпоинт minimax-h3-image для преобразования изображения в изображение принимает ваше референсное изображение (одно или несколько) и текстовый промпт, а возвращает новый результат генерации, который следует промпту и при этом опирается на референсное изображение.
Концептуально каждый запрос состоит из трёх частей:
- Маршрутизация модели — вы адресуете
minimax-h3-imageчерез задачуimage-to-image, и всё это через единый эндпоинт hiapi. Вам не нужны отдельные учётные данные или хосты для каждой возможности. - Входные данные — строка промпта, одно или несколько референсных изображений (URL или base64-нагрузка), а также параметры генерации, такие как уровень разрешения.
- Контракт вывода — вызов асинхронный. Вы получаете идентификатор задачи, затем опрашиваете статус и при завершении задачи получаете URL сгенерированного изображения.
Последний пункт важен. Преобразование изображения в изображение — это не блокирующий вызов, который отдаёт пиксели в том же ответе. Считайте вызов отправки «постановкой задания в очередь» и с самого начала проектируйте клиент вокруг жизненного цикла задачи. Если сначала спроектировать синхронное поведение, позже придётся переписывать код интеграции.
Поскольку всё проходит через единый интерфейс hiapi, заголовки запросов, аутентификация и обёртка ответов одинаковы для всех моделей и задач. Изучите это один раз для minimax-h3-image — и тот же шаблон применим в других местах платформы.
Минимальный работающий запрос
Начните с минимального запроса, который докажет, что ваши учётные данные, эндпоинт и структура нагрузки корректны. Не спешите сразу добавлять все необязательные поля.
Минимальное тело запроса содержит:
- имя модели
minimax-h3-image - тип задачи
image-to-image prompt, описывающий желаемое преобразование- одно поле референсного изображения
- один уровень разрешения
Концептуально нагрузка выглядит примерно так:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "преврати этот эскиз в чистый производственный рендер на белом фоне",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
Отправьте его, убедитесь, что вернулся id задачи, и вручную опросите статус один-два раза, чтобы увидеть переходы состояний. Если id задачи получен, значит связность и аутентификация в порядке, и можно переходить к построению настоящего клиента. Если нет — остановитесь и прочитайте тело ответа с ошибкой: обычно оно прямо указывает на проблемное поле.
Сохраните этот запрос как дымовой тест. Когда последующие изменения сломают ваш конвейер, повторный запуск этого минимального запроса сразу покажет, проблема в вашей нагрузке или в окружающем коде.
Вызов через curl
curl — самый быстрый способ увидеть сырой запрос и ответ. Запишите JSON-тело в файл, чтобы при редактировании не бороться с кавычками shell.
cat > payload.json <<'JSON'
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "переделай эту фотографию в стиль акварельной иллюстрации",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
JSON
curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
--data @payload.json
Основную работу выполняют два заголовка: Authorization с bearer-токеном и Content-Type: application/json. Держите оба вне системы контроля версий — читайте ключ из переменной окружения, а не вставляйте его в команду.
При успешной отправке захватите возвращённый id задачи и опрашивайте его:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
В ответе есть поле статуса, а после завершения — результат. С помощью jq извлеките только нужные вам поля:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'
Это также самый простой способ отладки нагрузки: curl точно покажет, что вы отправили и что вернулось, без чего-либо, скрытого клиентской библиотекой.
Вызов через Python
Версия на Python должна повторять поток curl: отправить, захватить id, опрашивать до конечного состояния, получить результат. Используйте requests и Session, чтобы переиспользование соединений и заголовки по умолчанию обрабатывались один раз.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
def submit(prompt: str, image: str, resolution: str = "1024") -> str:
body = {
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": prompt,
"image": image,
"resolution": resolution,
},
}
resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()["id"]
def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"Задача {task_id} не завершилась за {timeout} секунд")
if __name__ == "__main__":
task_id = submit(
"преврати это изображение в плоский векторный постер",
"https://example.com/reference.png",
)
print("Отправлено:", task_id)
result = poll(task_id)
print(result)
Ключевые детали: raise_for_status() превращает HTTP-ошибки в исключения, а не в молчаливый сбой; цикл опроса имеет и дедлайн, и интервал; конечное состояние проверяется явно. Разбирайте URL изображения из объекта результата только после того, как статус достиг конечного состояния, и никогда раньше.
Использование нескольких референсных изображений
Одного референсного изображения часто недостаточно. Возможно, вы хотите сохранить лицо с одной фотографии, позаимствовав композицию с другой, или совместить текстуру и контур. Преобразование изображения в изображение в minimax-h3-image поддерживает несколько референсных входов через поле изображения во множественном числе.
Структурно объект input может нести одно референсное изображение в поле image, а когда их несколько — в массиве images:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "сохрани человека с первого изображения и используй стиль фона со второго изображения",
"images": [
"https://example.com/person.png",
"https://example.com/background.png"
],
"resolution": "1024"
}
}
Порядок имеет значение. Индекс референса 0 — ваш основной объект, последующие элементы — вспомогательный контекст, поэтому формулируйте промпт в соответствии с порядком отправки. Если полученный результат игнорирует какое-то референсное изображение, обычно причина в неоднозначности промпта, а не в сломанном поле — пусть промпт явно указывает, какое изображение определяет какое свойство.
Практические правила работы с несколькими референсами:
- Держите количество небольшим. Используйте только те референсные изображения, которые действительно нужны конкретному промпту; лишние размывают контроль.
- По возможности согласовывайте соотношение сторон, чтобы модели не приходилось примирять конфликтующие композиции.
- В одном запросе последовательно используйте либо публичные URL, либо base64, не смешивайте способы передачи.
Во время интеграции отправьте один запрос с двумя изображениями и убедитесь, что оба референса заметно повлияли на вывод, прежде чем строить поверх этого более сложную логику.
Выбор уровня разрешения
Поле resolution выбирает уровень вывода для преобразования изображения в изображение в minimax-h3-image. Это не просто косметический переключатель — оно меняет объём вычислений, задержку ответа и размер нагрузки, с которой вам в итоге придётся работать.
Как выбирать компромисс:
- Выбирайте минимальный уровень, достаточный для целевого сценария. Миниатюре в списке не нужен тот же уровень, что и главному баннеру. Понижать разрешение высококачественного вывода постфактум — это пустая трата времени и денег.
- Ожидайте, что задержка растёт с разрешением. Более высокий уровень делает больше работы на каждый запрос, поэтому ваш бюджет тайм-аутов и интервалов опроса должен отражать выбранный уровень.
- Следите за размером нагрузки. Референсные входы в base64 и высокоразрешённые выходы увеличивают объём передачи; если вы перекачиваете много изображений, обращайте внимание на тела запросов и ответов.
Биллинг следует за запрошенным уровнем разрешения — запросы оплачиваются по уровню, на котором они выполняются, поэтому слишком большой уровень для мелких случаев незаметно увеличивает расходы. Смотрите актуальные тарифы на панели цен, а не полагайтесь на жёстко заданные предположения.
Разумная стратегия интеграции: на этапе разработки использовать средний уровень ради скорости, а когда промпты и набор референсов устоялись, поднять ключевые активы на более высокий уровень. Изменение разрешения на позднем этапе обесценит ваши измерения задержки, поэтому проводите бенчмарки на том уровне, который действительно планируете использовать в продакшене.
Обработка асинхронного жизненного цикла
Каждый вызов преобразования изображения в изображение на hiapi следует одному циклу: отправить, захватить id задачи, опрашивать до конечного состояния, затем получить результат. Сделать этот цикл надёжным — это большая часть работы продакшен-клиента.
Отправка и запись
Считайте id задачи вашим постоянным дескриптором. Записывайте его сразу, как только приходит ответ на отправку, прежде чем делать что-либо ещё — если процесс упадёт во время опроса, этот id позволит вам восстановиться, а не генерировать заново.
Опрос с задержкой
Фиксированный опрос раз в две секунды подходит для интерактивного использования, но расточителен для длинных пакетов. Начинайте с короткого интервала и постепенно увеличивайте его, ограничивая максимальный интервал, чтобы всё ещё своевременно обнаруживать завершение.
def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
return min(current * factor, cap)
Уважайте конечные состояния
Выходите из цикла только при успехе или неудаче. Считать любой непустой ответ «завершённым» — самая распространённая асинхронная ошибка: вы будете читать результат, которого ещё нет.
Задавайте границы всему
Устанавливайте тайм-аут для каждого HTTP-вызова и общий дедлайн для задачи. Если дедлайн прошёл, выбрасывайте понятную ошибку, а не продолжайте холостой цикл. Для временных сетевых ошибок повторяйте опрос с задержкой; не отправляйте запрос заново вслепую, это создаёт дублирующую работу.
Очистка
Как только результат получен, своевременно сохраните URL изображения или байты в собственное хранилище. Результат задачи — временный дескриптор, а не долгосрочный CDN вашего приложения.
Устранение неполадок и производственный чек-лист
Вот сбои, с которыми разработчики сталкиваются в первую очередь при использовании преобразования изображения в изображение в minimax-h3-image, и проверки, которые их предотвращают.
Сбои при первом запуске
- 401 / 403 — bearer-токен отсутствует, истёк или содержит лишние пробелы по краям. Убедитесь, что переменная окружения экспортирована в оболочке, которая выполняет запрос.
- 422 или ошибка валидации — проверьте тело ответа с ошибкой; обычно оно указывает поле. Частая причина —
promptна верхнем уровне, а не внутриinput. - Некорректный JSON — проверьте файл нагрузки с помощью
jq .перед отправкой.
Сбои во время выполнения
- Задача никогда не завершается — убедитесь, что при опросе вы используете реально полученный id, а не заполнитель. Проверьте, достаточно ли ваш дедлайн велик для выбранного уровня разрешения.
- Пустой результат у «завершённой» задачи — читайте поле статуса внимательно; тела ответов возвращаются и для состояний сбоя.
- Референсное изображение игнорируется — прежде чем винить модель, перепроверьте формулировку промпта и порядок референсных изображений.
Чек-лист перед запуском в продакшен
- API-ключ и базовый URL читаются из переменных окружения и никогда не коммитятся в репозиторий.
- У каждого HTTP-вызова есть явный тайм-аут.
- Опрос использует ограниченную задержку с жёстким общим дедлайном.
- Конечные состояния обрабатываются явно; не происходит проваливания в ветку разбора результата.
- Результаты скачиваются и сохраняются вашим приложением, а не подключаются по горячей ссылке из ответа задачи.
- Промпты с несколькими референсами указывают, какое изображение управляет каким свойством.
- Уровень разрешения протестирован на значениях, которые вы планируете использовать в продакшене.
- Журналы записывают id задачи, чтобы сбойные задания можно было отследить и восстановить.
Всякий раз, когда что-то идёт не так, повторно запускайте тот минимальный запрос — он изолирует, проблема в вашей нагрузке или в окружающем коде. Имея структуру запроса, клиенты на curl и Python, обработку нескольких референсов и дисциплинированный цикл опроса, вы обладаете всем необходимым для надёжного запуска преобразования изображения в изображение в minimax-h3-image на hiapi.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий