Руководство
Как использовать flux-3 через API HiAPI: curl, Python и рабочие примеры запросов
На этой странице
Что даёт использование flux-3 через HiAPI
flux-3 — это модель генерации изображений, которая справляется как с текст-в-изображение, так и с изображение-в-изображение. Если вы создаёте продуктовую функцию, инструмент для дизайна или внутренний пайплайн, самое интересное обычно не сама модель, а то, насколько чисто вы можете поставить её за стабильный, предсказуемый интерфейс и сохранять это состояние при изменении требований.
Именно в этом ценность агрегирующих API-платформ. Вызов flux-3 через HiAPI означает, что вы:
- Интегрируетесь один раз. Единый базовый URL, единый способ аутентификации и одинаковая структура запросов и ответов для всех используемых моделей. Дальше смена или сравнение моделей — это изменение конфигурации, а не переписывание кода.
- Избавляетесь от инфраструктурной работы. Не нужно хостить модель, планировать ёмкость GPU или управлять холодным стартом на своей стороне. Вы отправляете HTTP-запрос и обрабатываете ответ.
- Централизованно управляете учётными данными. Один API key для выдачи, ротации и ограничения прав, вместо отдельных отношений с каждым вышестоящим провайдером.
- Получаете единую семантику ошибок. Коды состояния и обёртки ошибок одинаковы независимо от того, какая модель стоит за вызовом, что позволяет переиспользовать логику повторов и оповещений.
Применительно к flux-3 это означает, что вы можете перейти от прототипа в notebook сразу к production-эндпоинту, не меняя структуру клиентского кода. Оба режима генерации — текст-в-изображение и изображение-в-изображение — используют одну структуру запроса, поэтому поддержка обоих зависит только от того, какие поля вы заполняете, а не от того, какой SDK импортируете.
В статье используются следующие соглашения:
- Базовый URL: эндпоинт API HiAPI, указанный в консоли вашего аккаунта.
- Аутентификация: bearer-токен в заголовке
Authorization. - Тип содержимого: тело запроса в формате
application/json, изображения на входе передаются по URL или в виде данных в кодировке base64, в зависимости от ограничений на размер вашей нагрузки.
Храните ключ в переменных окружения — никогда не коммитьте его в систему контроля версий. В примерах ниже ключ читается из HIAPI_API_KEY, а идентификатор модели — из FLUX_MODEL, так что вы можете всё поменять, не трогая код.
Подготовка закончена, в следующем разделе разбирается само тело запроса.
Разбор структуры запроса: текст-в-изображение и изображение-в-изображение
Вызов flux-3 логически делится на три части: путь эндпоинта, заголовок аутентификации и JSON-тело. Тело запроса — это место, где два режима расходятся, и понимание этого различия позволяет использовать один клиент для обоих.
Общий каркас
Каждый запрос содержит в той или иной форме следующие поля:
- model — модель для вызова; здесь это ваш идентификатор flux-3.
- input — объект, несущий инструкции генерации.
- input.prompt — естественно-языковое описание желаемого. Обязательно в обоих режимах.
- Необязательные настройки генерации — например, размер выходного изображения, соотношение сторон или число шагов, в зависимости от возможностей, которые предоставляет модель. Задавайте только нужное; значения по умолчанию обычно достаточно разумны.
- Необязательное управление асинхронностью — флаги или колбэки, меняющие способ выполнения и доставки задачи (подробно в следующем разделе).
Текст-в-изображение
В режиме текст-в-изображение prompt — единственное содержательное поле. Вы описываете изображение, при желании ограничиваете геометрию выходного результата и отправляете. Исходного изображения нет, поэтому модель имеет максимальную свободу — а значит, качество промпта определяет качество результата.
Полезная привычка: пишите промпт так, как вы ставили бы задачу человеку-иллюстратору. В порядке: субъект, композиция, освещение, стиль и любые жёсткие ограничения (например, «никакого текста на изображении», «субъект по центру»). Расплывчатые промпты дают посредственный результат при любом числе шагов.
Изображение-в-изображение
В режиме изображение-в-изображение вы добавляете к промпту поле исходного изображения, и тогда промпт описывает преобразование относительно этого входа, а не сцену, создаваемую с нуля. В зависимости от интерфейса модели это может означать передачу URL изображения или закодированной нагрузки изображения, плюс любые параметры силы или управления, задающие степень отклонения результата от исходника.
Для вашего API-клиента практическая разница невелика: тот же эндпоинт, та же аутентификация, тот же объект input — только на одно поле больше. Именно в этом и замысел. Ваша функция generate() должна принимать необязательное исходное изображение и обрабатывать ветвление внутри, чтобы вызывающая сторона никогда не знала, какой режим она запустила.
Структура ответа
Ответ должен содержать идентификатор задачи, а по завершении — местоположение сгенерированного изображения. Считайте это местоположение непрозрачным значением: его можно получить или сохранить, но не делайте предположений о его содержимом. Некоторые ответы возвращаются сразу, другие представляют собой дескриптор задачи — именно поэтому асинхронная обработка должна быть заложена в дизайн с первого дня.
Параметры и асинхронные режимы
Выбор настроек генерации
Настройки генерации — это компромисс между качеством, задержкой и стоимостью. Следующие принципы применимы к большинству моделей изображений, включая flux-3:
- Разрешение и соотношение сторон влияют и на практическую пригодность результата, и на вычислительные затраты. Генерируйте в том размере, в котором реально отдаёте; уменьшение большого изображения тратит бюджет, а увеличение маленького тратит рендеринг.
- Шаги или управление качеством повышают точность до определённой точки, после чего выходят на плато. Измерьте на фиксированном промпте, найдите эту точку и остановитесь на ней.
- Управление детерминизмом (если доступно) важно для воспроизводимости. Если вам нужно перегенерировать тот же результат для QA или поддержки пользователей, записывайте настройки вместе с выходом.
Не угадывайте имена параметров или допустимые диапазоны — читайте документацию модели в консоли и опирайтесь на неё. Если поле отклонено, ответ с ошибкой укажет, какое именно.
Синхронный vs. асинхронный
Генерация изображений — не мгновенная операция. Есть два режима выполнения:
Синхронный (блокирующий). Вы отправляете запрос и держите соединение, пока изображение не будет готово. Это просто и подходит для коротких задач, скриптов и интерактивных инструментов, где пользователь смотрит на индикатор загрузки. Но это и хрупко: серверлесс-функции, балансировщики нагрузки и мобильные клиенты имеют таймауты, и длительный рендеринг обязательно упрётся в один из них.
Асинхронный (на основе задач). Вы отправляете запрос, сразу получаете идентификатор, а затем опрашиваете эндпоинт статуса или принимаете колбэк, пока задача не сообщит о завершении. Выбирайте этот режим в следующих случаях:
- Серверлесс- и edge-среды выполнения с жёстким лимитом длительности.
- Пакетные задачи, где нужно параллельно отправить множество рендеров.
- Любой пользовательский сценарий, где вы хотите сразу вернуть управление и передавать прогресс потоком.
Проектируйте клиент вокруг асинхронности, а простые сценарии оберните в синхронный удобный метод. Обратное — втискивание асинхронности в блокирующий клиент — редко заканчивается хорошо.
При опросе используйте экспоненциальную задержку с верхней границей, а не плотный фиксированный цикл, задайте общий лимит ожидания и считайте ошибкой, заслуживающей оповещения, задачу, которая никогда не достигает терминального состояния.
Рабочий запрос на curl
Начните с терминала; как только сырой HTTP-обмен станет понятен, версии на языках программирования окажутся простыми.
1. Настройка окружения
export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"
Поместите идентификатор модели в переменную — позже смена модели будет изменением одной строки.
2. Отправка запроса текст-в-изображение
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
}
}'
Флаг -sS оставляет вывод чистым, но по-прежнему показывает ошибки. Перед запуском сверьте точный путь с эндпоинтом, указанным в консоли — пути версионируются, ориентируйтесь на документацию.
3. Чтение возвращённых данных
Пропустите ответ через инструмент форматирования, чтобы он читался:
... | python -m json.tool
Обратите внимание на две вещи: идентификатор задачи и местоположение изображения или поле статуса, сообщающее, что задача всё ещё выполняется. Если вы видите статус, а не изображение, значит вы на асинхронном пути — запишите идентификатор и переходите к опросу.
4. Попробуйте изображение-в-изображение
Добавьте исходное изображение в объект input, оставив остальное без изменений:
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
"image": "https://example.com/source.jpg"
}
}'
Поскольку запрос отличается только одним полем, ваш первый успешный вызов уже проверил большую часть интеграции. Остальное — повторы, хранение, UI — обычная прикладная работа.
Тот же запрос на Python
Вызов curl напрямую переводится. Ниже — компактный переиспользуемый клиент, а не одноразовый скрипт.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def generate(prompt, image=None, timeout=60):
"""Submit a flux-3 generation job. Pass image= for image-to-image."""
payload = {"model": MODEL, "input": {"prompt": prompt}}
if image:
payload["input"]["image"] = image
resp = requests.post(
f"{BASE}/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=timeout,
)
resp.raise_for_status()
return resp.json()
Несколько намеренных решений:
- Одна функция, два режима. Параметр
imageпереключает поведение, вызывающей стороне не нужно ветвление. - Явный таймаут. Поведение
requestsпо умолчанию — бесконечное ожидание — именно так и забиваются пулы рабочих потоков. raise_for_status(). Позволяет сбоям HTTP-уровня всплывать в виде исключений, которые можно перехватить в одном месте.
Добавление вспомогательной функции опроса
Когда ответ несёт идентификатор задачи вместо готового изображения, дождитесь его:
def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
deadline = time.monotonic() + timeout
delay = initial
while time.monotonic() < deadline:
r = requests.get(
f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "failed"):
return data
time.sleep(delay)
delay = min(delay * factor, cap)
raise TimeoutError(f"job {job_id} did not finish in {timeout}s")
Скорректируйте имя поля статуса в соответствии со структурой ответа, описанной в документации. Сама структура — задержка с верхней границей, жёсткий дедлайн, проверка терминального состояния — и есть главное, и она применима без изменений при смене модели.
Собираем вместе
if __name__ == "__main__":
result = generate(
"A minimal studio photograph of a ceramic mug, soft side light"
)
if "id" in result and not result.get("output"):
result = wait_for(result["id"])
print(result)
Далее оберните generate своим слоем повторов и логирования — и интеграция приобретёт production-форму.
Контроль затрат и типичные ошибки
Делаем расходы предсказуемыми
Генерация изображений тарифицируется за запрос, конкретная сумма зависит от модели и настроек — сверяйтесь с актуальной панелью цен в консоли, а не полагайтесь на захардкоженные допущения. Именно инженерная дисциплина защищает бюджет:
- Устанавливайте лимиты на пользователя и на задачу в своём коде. Платформа применяет ограничения уровня аккаунта; ваше приложение должно применять ограничения уровня продукта, чтобы один вышедший из-под контроля клиент не исчерпал аккаунт.
- Активно кешируйте. Хешируйте нормализованный промпт вместе с настройками и переиспользуйте сохранённые результаты. В сценариях редактора и предпросмотра одинаковые запросы встречаются часто.
- Генерируйте в разрешении, в котором отдаёте. Рендерите тот размер, который будете показывать; избегайте дорогостоящего шаблона «отрендерить большое, затем уменьшить».
- Привязывайте перегенерацию к явному действию пользователя. Автоматическая перегенерация на каждое нажатие клавиши в поле промпта — самый частый незаметный множитель затрат.
- Логируйте модель, настройки и задержку каждого вызова. Без этого вы не сможете понять, какая функция обходится дорого.
- Валидируйте вход до отправки. Отклоняйте пустые или аномально длинные промпты на клиенте, чтобы никогда не платить за заведомо провальные запросы.
Отладка сбоев, с которыми вы реально столкнётесь
Проходите этот список по порядку — он решает большинство инцидентов.
- 401 / 403 — аутентификация. Загружен ли ключ в то окружение, где реально выполняется запрос? Ключ, доступный в вашей оболочке, может отсутствовать в контейнере. Убедитесь, что префикс
Bearerи имя заголовка указаны точно. - 404 — неверный путь или модель. Версионированные пути и идентификаторы моделей меняются. Сверьте эндпоинт с документацией посимвольно.
- 422 / 400 — нагрузка отклонена. Тело ошибки укажет проблемное поле. Частые подозреваемые: неверный тип, отсутствие
promptили неподдерживаемый параметр. Уберите необязательные настройки и отправьте повторно, чтобы изолировать проблему. - 429 — сработало ограничение частоты. Отступите с джиттером и повторите; не повторяйте сразу в цикле. Отличайте это от исчерпания квоты уровня аккаунта, где повтор не поможет.
- Таймауты. Если запрос выполняется слишком долго, значит вы блокируете там, где следует опрашивать. Перейдите на асинхронный поток и осознанно задайте таймауты клиента.
- Задача застряла в pending. Опрашивайте с дедлайном и считайте таймаут сбоем, заслуживающим оповещения, а не бесконечным ожиданием.
Одна привычка связывает весь список: логируйте полное тело ошибки, а не только код состояния. Тело ошибки обычно точно указывает, какое поле или ограничение стало проблемой, превращая полчаса отладки в исправление на одну строку.
Сначала добейтесь работы вызова curl, перенесите его в клиент выше, сосредоточьте опрос и обработку ошибок в одном месте — остальная интеграция — обычный прикладной код. Актуальные возможности модели и цены смотрите в документации flux-3 и панели цен в консоли HiAPI.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий