HiAPI
Блог

Руководство

Как вызывать minimax-h3-image для преобразования изображения в изображение через curl и Python на hiapi

Nov 13, 2026
Обложка блога hiapi.ai: абстрактная призматическая геометрическая композиция на тёмно-зелёном фоне, разделённая чистыми диагональными линиями на плоские цветовые плоскости
На этой странице

Что ожидает эндпоинт преобразования изображения в изображение

Прежде чем писать код, полезно понять структуру вызова преобразования изображения в изображение. Эндпоинт 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.

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

Все статьи →

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

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

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