HiAPI
Блог

Руководство

Как использовать minimax-h3-image для генерации изображений по тексту через HiAPI API: curl и Python

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

Что охватывает это руководство и что нужно подготовить заранее

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

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

Предварительные требования

  • Аккаунт HiAPI. Прежде всего нужен проект и API-ключ — каждый запрос ниже требует аутентификации.
  • Храните ключ в безопасном месте. Поместите его в переменную окружения (HIAPI_API_KEY), а не в файл исходного кода, чтобы один и тот же код работал локально и в CI.
  • Идентификатор модели. В руководстве используется minimax-h3-image и его возможность text-to-image. Рассматривайте имя модели и путь задачи как конфигурационные значения в коде, а не как разбросанные по всюду магические строки.
  • Инструменты. Для первого запроса — curl, для второго — Python 3.9+ и requests. Другие библиотеки не нужны.
  • Способ просмотра изображения. Вы получите тело ответа, содержащее данные изображения или ссылку на изображение — прежде чем предполагать какую-либо схему, вручную проверьте поля ответа.

Привычка, которую стоит выработать сейчас

Сначала создайте успешный запрос вне кода вашего приложения. Работающая команда curl — это эталон истины: всякий раз, когда версия на Python ведёт себя странно, сверяйтесь с ней. Если вызов через curl успешен, а через Python — нет, проблема в вашем клиенте, а не в модели или сети.

Создание рабочего запроса генерации изображения по тексту с помощью curl

Начните с минимально возможного запроса, затем добавляйте по одной настройке за раз. Запрос генерации состоит из трёх частей: эндпоинт, заголовки аутентификации и JSON-тело запроса.

Запрос

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image",
    "task": "text-to-image",
    "prompt": "Керамическая чаша на льняной скатерти, мягкий свет из северного окна, объектив 50 мм, малая глубина резкости",
    "size": "1024x1024",
    "n": 1
  }'

В этой команде есть три момента, на которые стоит обратить внимание:

  • Ключ передаётся в заголовке Authorization как bearer token. Никогда не помещайте его в URL или тело запроса, иначе он попадёт в логи и историю командной оболочки.
  • model и task описывают, что вам нужно — семейство моделей и возможность. Указывайте оба явно, даже если существуют значения по умолчанию; явный запрос лучше выдерживает испытание временем.
  • prompt — это обычная строка. Всё остальное (size, n) — это настройки изображения, а не описание субъекта.

Интерпретация ответа

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

curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

При итерациях помещайте тело запроса в файл (request.json) — так подсказка остаётся читаемой, а изменение подсказки превращается в однострочный diff, а не в угадывание кавычек.

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

Подтвердите весь процесс end-to-end

Сохраните возвращённое изображение, откройте его и проверьте, что получили именно то, что запросили. Ответ 200 с правдоподобным JSON-телом не означает корректное изображение — именно на этом этапе проблемы с подсказкой и параметрами обнаруживаются дешевле всего.

Перенос запроса на Python

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

import os
import requests

HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"


def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
    """Создаёт изображение с помощью minimax-h3-image через HiAPI."""
    payload = {
        "model": "minimax-h3-image",
        "task": "text-to-image",
        "prompt": prompt,
        "size": size,
        "n": n,
    }
    response = requests.post(
        ENDPOINT,
        headers={
            "Authorization": f"Bearer {HIAPI_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=(5, 120),  # таймаут подключения, таймаут чтения
    )
    response.raise_for_status()
    return response.json()

В этой функции есть четыре намеренных решения:

  • Кортежный таймаут. Таймаут подключения короткий, потому что медленное установление соединения означает проблему; таймаут чтения более щедрый, потому что генерация изображения по определению требует времени. Единое значение таймаута заставляет вас плохо обрабатывать один из режимов отказа.
  • json=payload. Позвольте библиотеке сериализовать тело запроса. Вручную склеенные JSON-строки — идеальная среда для ошибок с кавычками.
  • raise_for_status() перед парсингом. Проверка статуса не опциональна — разбор тела ответа с ошибкой как успешного — самый запутанный тип бага в таких интеграциях.
  • Возвращайте обычный dict. Позже вы сможете украсить его типизированной моделью; сначала убедитесь, что знаете, какие поля фактически содержит ответ.

Изолируйте поиск ключа

Если переменная отсутствует, os.environ["HIAPI_API_KEY"] немедленно выбросит исключение. Это сделано намеренно: сбой при запуске, а не при первом запросе пользователя. В более крупной кодовой базе разрешайте ключ один раз при загрузке конфигурации, а затем передавайте настроенный клиент, вместо чтения переменной окружения в точке вызова.

Подключите запуск

if __name__ == "__main__":
    result = generate_image("Красный воздушный змей над влажным пляжем во время отлива, пасмурное освещение")
    print(result)

Запустите это и сравните с выводом curl. Структура тела ответа должна совпадать. Если она не совпадает, вы обнаружили расхождение, которое стоит выяснить, прежде чем продолжать разработку.

Обрабатывайте ошибки, а не угадывайте

Самая распространённая ошибка интеграции — повторять ошибку, которая никогда не завершится успехом. Разделите отказы на три категории и обрабатывайте их по-разному.

Ошибки аутентификации и авторизации

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

Ошибки валидации запроса

Обычно это ответы уровня 400: неизвестные значения model или task, size, не поддерживаемый моделью, n вне допустимого диапазона, пустая подсказка, некорректный JSON. Они также не подлежат повтору — тот же запрос завершится так же. Полезная работа — показать сообщение об ошибке как есть разработчику, который написал запрос, а не проглатывать его в общее исключение.

Транзиентные ошибки сервера и сети

Ответы 429 и 5xx, а также сбросы соединения и таймауты чтения — это действительно те случаи, которые можно повторять. Обрабатывайте их с ограниченной экспоненциальной задержкой и джиттером:

import time, random, requests

def post_with_retry(session, url, payload, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            r = session.post(url, json=payload, timeout=(5, 120))
            if r.status_code in (429, 500, 502, 503, 504):
                raise requests.HTTPError(f"Транзиентная ошибка {r.status_code}", response=r)
            r.raise_for_status()
            return r.json()
        except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
            if attempt == max_attempts - 1:
                raise
            time.sleep(min(2 ** attempt + random.random(), 30))

Два предостережения. Во-первых, HTTPError, вызванный не 429 ответом 4xx, должен немедленно пробрасываться наружу — не позволяйте предложению except поглощать ошибки валидации. Во-вторых, следуйте любым указаниям о повторе, содержащимся в ответе, а не изобретайте задержку самостоятельно.

Повторы здесь не идемпотентны

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

Практическая гигиена подсказок и параметров

Смысл этих привычек — сопоставимость: когда вы меняете что-то одно, вы должны уметь определить, вызвано ли изменение вывода именно этим.

Пишите подсказки, которые называют содержимое кадра

Описывайте в порядке: субъект, сцена, освещение, композиция. Конкретные существительные и фотографические термины (например, «мягкий свет из северного окна», «малая глубина резкости») несут больше сигнала, чем нагромождение эстетических прилагательных. Избегайте обилия отрицательных подсказок; описывайте то, что должно присутствовать.

Меняйте только одну переменную за раз

Держите небольшой файл подсказок для каждого проекта и редактируйте его между запусками, а не переписывайте с нуля. Если какой-то запуск разочаровал, меняйте либо подсказку, либо настройку — не оба сразу. Иначе вы не узнаете, какое изменение сработало.

Рассматривайте настройки как явный контракт

size и n влияют как на вывод, так и на стоимость. Зафиксируйте их в объекте конфигурации, а не протаскивайте литералы через все точки вызова, чтобы изменение соотношения сторон для всей функции было одной правкой. Если вам нужно несколько изображений для сравнения, запрашивайте их одним вызовом, а не несколькими — меньше сетевых обращений, логи легче читать.

Храните подсказки вместе с выводами

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

Задавайте seed для сравнений

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

Версионируйте подсказки

Относитесь к тексту подсказки как к коду: храните в файлах, проверяйте изменения и записывайте, какая версия подсказки породила какой ресурс. Это превращает вопрос «Почему во вторник на прошлой неделе изображения стали хуже?» в вопрос, на который можно ответить.

Чек-лист перед запуском в продакшен

Работающий запрос — это только лёгкая часть. Следующие проверки отличают демонстрацию от интеграции.

  • Устанавливайте таймауты для каждого вызова. Явно задавайте таймаут подключения и таймаут чтения, никогда не используйте значения по умолчанию. Эндпоинт генерации без таймаута чтения в конечном итоге подвесит воркер.
  • Ограниченные повторы, только для повторяемых ошибок. Ограничьте число попыток, добавьте джиттер и убедитесь, что ошибки валидации и аутентификации полностью обходят путь повторов.
  • Управление ключами. Читайте ключи из окружения или хранилища секретов, никогда из исходного кода. Ротация без изменения кода.
  • Структурированное логирование. Записывайте идентификатор модели, подсказку (или её хеш плюс ссылку), настройки, HTTP-статус, количество попыток и любые идентификаторы запроса из ответа. Без этого проблемы с изображениями будут невоспроизводимы.
  • Видимость затрат. Генерация оплачивается по объёму вывода, поэтому использование зависит от того, сколько изображений вы запрашиваете и как часто повторяете. Заранее определите, выполняются ли запросы на пользователя, на задачу или в фоне, и отслеживайте объём соответственно — смотрите актуальную панель цен на сайте, чтобы узнать текущие тарифы, а не закладывайте в код предположения.
  • Определите поведение при отказе. Решите, что увидит пользователь, если генерация не удалась после последней попытки: состояние ошибки, заглушку или задание в очереди на повтор. Неопределённый fallback превращается в неопределённый пользовательский опыт.
  • Зафиксируйте схему тела ответа. Сохраняйте и проверяйте поля ответа, на которые вы полагаетесь, чтобы изменения тела ответа проявлялись как явные ошибки, а не молчаливый None.

Финальный этап проверки

Выполните команду curl, функцию на Python и намеренно повреждённый запрос (сначала неверный ключ, затем неверный параметр) и убедитесь, что каждый из них даёт ожидаемый отказ. Именно этот последний шаг показывает, что обработка ошибок реальна, а не декоративна.

После того как запрос аутентифицирован, портирован, разумно повторяется и логируется, эту интеграцию можно оставить позади остального приложения.

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

Все статьи →

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

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

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