Руководство
Как вызывать flux-2/text-to-image через API HiAPI: руководство по curl и Python
Практическое руководство по вызову: идентификатор модели, параметры prompt и aspect ratio, поля ответа и обработка ошибок
На этой странице
Что flux-2/text-to-image предоставляет через API
Прежде чем писать первую строку кода, полезно понять, к чему именно вы подключаетесь. В HiAPI flux-2/text-to-image — это не отдельный SDK, который нужно устанавливать, и не новый сервис с собственной аутентификацией. Это идентификатор модели, который вместе с описанием желаемого изображения (prompt) передаётся в общий эндпоинт генерации изображений.
Эта ментальная модель важна, потому что она очерчивает границы интеграции. Вашему коду нужны три вещи:
- Учётные данные для аутентификации в API HiAPI.
- Эндпоинт, принимающий запросы на генерацию изображений.
- JSON-полезная нагрузка, содержащая
model(со значениемflux-2/text-to-image) иprompt.
Всё остальное — соотношение сторон, предпочтения по выводу и любые другие параметры, которые предоставляет модель, — существует в этой нагрузке как дополнительные поля. Именно поэтому переключение с другой модели текст-в-изображение на flux-2/text-to-image обычно требует изменения одной строки конфигурации, а не переписывания кода: конверт запроса остаётся прежним, меняется только значение model.
Эндпоинт принимает ваш запрос, прогоняет его через модель и возвращает структурированный ответ, содержащий сгенерированное изображение (обычно URL или закодированную нагрузку) и метаданные задания. Для базового вызова не нужно опрашивать отдельную очередь заданий — с точки зрения клиента цикл запрос/ответ синхронный, но базовая генерация всё равно занимает время, поэтому тайм-аут вашего HTTP-клиента следует задать достаточно щедрым.
Запомните эту картину: один эндпоинт, одна полезная нагрузка, одна строка модели. Остальная часть руководства наполнит нагрузку и укрепит вызов.
Сборка рабочего запроса через curl
Самый быстрый способ убедиться, что учётные данные и структура нагрузки корректны, — один вызов curl. Получите успешный ответ в терминале до того, как возьмётесь за Python: это изолирует проблемы аутентификации и нагрузки от ошибок на уровне языка.
Сначала поместите ключ в переменную окружения, чтобы он не остался в истории shell в открытом виде:
export HIAPI_API_KEY="your_api_key_here"
Затем отправьте запрос:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/text-to-image",
"prompt": "старый маяк на гранитном утёсе на рассвете, мягкий туман, широкий план",
"aspect_ratio": "16:9"
}'
Что стоит проверить при запуске:
- Эндпоинт и ключ берутся из панели управления вашей учётной записи HiAPI. Копирование эндпоинта из панели вместо повторного ввода позволяет избежать самой частой тихой ошибки — запрос уходит не туда, куда ожидалось.
-sSсохраняет вывод аккуратным, но по-прежнему показывает ошибки уровня curl, такие как сбои DNS или TLS.- Заголовок
Authorizationиспользует стандартную схему bearer. Никаких лишних пробелов и кавычек вокруг раскрытия переменной. Content-Type: application/jsonобязателен; без него тело запроса может быть отклонено ещё до того, как его увидит модель.
При успешном вызове вы увидите JSON-ответ в терминале. Пропустите его через форматтер для читаемости:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"flux-2/text-to-image","prompt":"рыжая лиса на свежем снегу, на уровне глаз","aspect_ratio":"1:1"}' \
| python3 -m json.tool
Как только это заработает, у вас будет заведомо исправная базовая линия. Любые последующие сбои в Python можно сравнивать с этим вызовом, который вы подтвердили как рабочий.
Параметры prompt и aspect ratio
Два поля запроса влияют на результат сильнее всего: prompt и aspect_ratio. Меняйте по одному за раз, иначе вы не сможете определить, что именно вызвало увиденное изменение.
Prompt
Prompt — это описание изображения на естественном языке. Пишите его как компактное описание сцены, а не список ключевых слов — примерно в порядке: субъект, обстановка, освещение и композиция. Сравните:
- Расплывчато:
маяк - Конкретно:
старый маяк на гранитном утёсе на рассвете, мягкий туман, широкий план
При экспериментах держите формулировку явной и стабильной. Если вы переписываете prompt и меняете соотношение сторон в одном цикле итерации, у вас два переменных фактора и одно наблюдение. Зафиксируйте prompt, меняйте по одному слову за раз и записывайте фактические изменения.
Полезные привычки:
- Ставьте самого важного субъекта в начало строки.
- Описывайте освещение и атмосферу конкретными, а не абстрактными словами.
- Храните в кодовой базе небольшой набор эталонных промптов и перезапускайте их при изменении чего-либо ещё, чтобы отличать изменения в поведении модели от изменений в промпте.
Соотношение сторон
aspect_ratio управляет формой вывода — широкий формат для пейзажей и баннеров, квадрат для аватаров и миниатюр, вертикальный для постеров и мобильных макетов. Модель принимает строки пропорций, такие как 16:9, 1:1 или вертикальные эквиваленты; используйте пропорции, задокументированные в документации модели, а не придумывайте произвольные.
Поскольку соотношение сторон — это одно дискретное поле, его проще всего перебирать. Напишите цикл, который сохраняет prompt неизменным, запрашивает одно и то же изображение в трёх пропорциях и затем сравнивает композицию бок о бок. Вы быстро узнаете, какие пропорции обрезают субъект, а какие дают ему пространство.
Одно замечание: соотношение сторон меняет эффективную композицию, а не только холст. Prompt, написанный для широкого кадра, может выглядеть слабо в квадратной рамке. После выбора пропорции пересмотрите prompt один раз для компенсации.
Перенос вызова на Python
Вызов curl напрямую переносится на Python. Цель — небольшая функция, которая принимает prompt и соотношение сторон, читает ключ из окружения и возвращает разобранный JSON — production-форма, а не одноразовый скрипт.
import os
import requests
IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"
def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # fail fast if unset
payload = {
"model": MODEL,
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
response = requests.post(
IMAGE_ENDPOINT,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
Пояснения к такому написанию:
- Используйте переменные окружения, а не литералы.
os.environ[...]немедленно выбрасываетKeyErrorпри отсутствии переменной, что гораздо лучше, чем отправить пустой bearer-токен и потом разбираться с непонятной ошибкой аутентификации. json=payloadпозволяетrequestsсериализовать тело запроса за вас и установитьContent-Type. Не собирайте JSON-строку вручную.- Явный тайм-аут. Генерация изображений не мгновенная; тайм-аут клиента по умолчанию создаст вам проблемы под нагрузкой. Задавайте его осознанно.
raise_for_status()превращает ответы, отличные от 2xx, в исключения, которые можно перехватить и классифицировать, а не в тело ошибки, которое выглядит как данные.
Вызов:
result = generate_image(
"старый маяк на гранитном утёсе на рассвете, мягкий туман, широкий план",
aspect_ratio="16:9",
)
print(result)
Если вы предпочитаете httpx, форма идентична — замените импорт и сохраните те же заголовки, нагрузку json= и параметр тайм-аута. Важна нагрузка, и она остаётся такой же, как в версии на curl.
Чтение ответа
Успешный вызов возвращает JSON-объект. Вместо того чтобы угадывать имена полей, сначала изучите реальный ответ, а затем пишите парсер на основе того, что вы фактически увидели. Запустите вашу функцию и выведите ключи верхнего уровня:
result = generate_image("рыжая лиса на свежем снегу, на уровне глаз", "1:1")
print(result.keys())
Поля, которые вы обычно используете, делятся на две группы:
- Само изображение. Ответ содержит сгенерированное изображение — обычно это URL, который вы можете скачать или предоставить, иногда закодированные данные изображения. Читайте точное имя поля из вашего собственного ответа, сохраняйте это значение и обрабатывайте его в зависимости от формы. Если это URL, считайте его краткосрочным: скачивайте или копируйте в собственное хранилище своевременно, а не сохраняйте ссылку в базу данных в предположении, что она будет разрешаться и в следующем месяце.
- Метаданные. Ожидайте сопутствующие поля, описывающие процесс генерации, — использованную модель, запрошенное соотношение сторон или размеры, а также идентификатор запроса. Записывайте их вместе с изображением. Когда пользователь сообщает, что изображение «выглядит неправильно», метаданные подскажут, какой prompt и пропорция его создали, без необходимости восстанавливать это из состояния приложения.
Безопасный шаблон извлечения:
image_ref = result.get("image") or result.get("data")
if not image_ref:
raise ValueError(f"no image in response; keys={list(result.keys())}")
Это намеренно защитный подход. Имена полей стабильны в рамках модели, но написание доступа с громким сбоем, указывающим фактические ключи, предотвращает тихое распространение None в ваш UI. Как только имена полей подтверждены по реальному ответу, сузьте код до прямого чтения.
Наконец, не выбрасывайте сырой ответ. Храните его (или логируйте для части запросов), пока интеграция не стабилизируется, — при возникновении проблем ниже по потоку он станет источником истины.
Частые ошибки и способы их исправления
Большинство сбоев при первом запуске относится к нескольким категориям. Обрабатывайте их по классу HTTP-статуса, а не по совпадению текста сообщения, который может измениться без предупреждения.
Ошибки аутентификации (401 / 403)
Ключ отсутствует, имеет неверный формат или не хватает прав доступа. Проверяйте по порядку: действительно ли HIAPI_API_KEY установлен в окружении, видимом вашему процессу; является ли заголовок в точности Authorization: Bearer <key> без лишних пробелов и кавычек; не отправили ли вы случайно ключ из другого окружения. Если curl работает, а Python нет, выведите отправляемые заголовки и сравните посимвольно.
Неверный формат нагрузки (400)
Тело запроса отклонено до генерации. Частые причины: невалидный JSON (вручную собранная строка с висячей запятой), отсутствие prompt или неверный Content-Type. Решение — использовать json=payload в Python и -d с валидным JSON в curl. Выводите в лог нагрузку, которую собираетесь отправить, и читайте её как человек.
Неподдерживаемый или недопустимый параметр (400 / 422)
Имя поля или значение, которое не принимает модель, — опечатка в aspect_ratio, незадокументированная пропорция или лишнее поле, скопированное из примера другой модели. Сведите нагрузку к минимуму (model, prompt), затем добавляйте поля по одному, чтобы найти проблемное.
Ограничение частоты (429)
Вы отправляете запросы быстрее, чем позволяет лимит учётной записи. Это временно. Не повторяйте в плотном цикле — используйте экспоненциальную задержку с ограничением числа попыток. Если вы работаете пакетно, добавляйте небольшую задержку между вызовами, а не отправляйте всё сразу.
Ошибки на стороне сервера (5xx) и тайм-ауты
Они временны и вне вашего контроля. Повторяйте с экспоненциальной задержкой и убедитесь, что тайм-аут достаточно длинный, чтобы медленная генерация не была ошибочно классифицирована как сбой. Тайм-аут чтения, сработавший пока модель ещё работает, приводит к повторной попытке, которая тратит запрос впустую.
Сосредоточение классификации в одном месте поддерживает сопровождаемость:
def classify(status: int) -> str:
if status in (401, 403):
return "auth" # fix config, do not retry
if status in (400, 422):
return "payload" # fix request, do not retry
if status == 429:
return "rate_limit" # retry with backoff
if status >= 500:
return "server" # retry with backoff
return "other"
Обёртка вызова для production
Функция выше работает, но реальной интеграции нужны три вещи, которых у неё пока нет: повторные попытки, отличающие временные сбои от постоянных, тайм-ауты, отражающие реальность, и логи, позволяющие восстановить произошедшее. Небольшая обёртка покрывает все три.
import logging
import time
log = logging.getLogger(__name__)
def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
delay = 1.0
for attempt in range(1, attempts + 1):
try:
return generate_image(prompt, aspect_ratio)
except requests.HTTPError as exc:
status = exc.response.status_code
kind = classify(status)
log.warning("flux-2 call failed", extra={
"attempt": attempt, "status": status,
"kind": kind, "aspect_ratio": aspect_ratio,
})
if kind in ("auth", "payload"):
raise # retrying will not help
if attempt == attempts:
raise
time.sleep(delay)
delay *= 2
Почему каждая часть важна:
- Повторяйте только то, что имеет смысл повторять. Ошибки аутентификации и нагрузки детерминированы — их повторение тратит время и скрывает настоящие баги. Ограничения частоты, серверные ошибки и тайм-ауты получают экспоненциальную задержку.
- Логируйте структурированные поля, а не прозу. Номер попытки, статус, класс ошибки и использованные параметры позволяют группировать сбои позже. Никогда не логируйте API-ключи.
- Ограничивайте число попыток. Неограниченный цикл повторных попыток превратит один сбой в зависший рабочий процесс.
- Держите тайм-ауты явными и щедрыми. Передавайте их из конфигурации, чтобы можно было увеличить их в известные медленные периоды без изменения кода.
Ещё две окупающиеся привычки: сохраняйте хеш (model, prompt, aspect_ratio) для каждого сгенерированного изображения, чтобы можно было воспроизвести любой вывод; держите небольшой набор эталонных промптов в тестовом наборе и прогоняйте их после любых изменений в обёртке. В сочетании они превращают фрагменты руководства в нечто эксплуатационно пригодное.
Когда форма запроса зафиксирована и обработка ошибок на месте, смена модели в дальнейшем требует лишь однострочного изменения поля model — в этом весь смысл вызова flux-2/text-to-image через единый интерфейс.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий