HiAPI
Блог

Руководство

Как использовать flux-3 через API HiAPI: curl, Python и рабочие примеры запросов

Nov 10, 2026
Обложка: полупрозрачные стеклянные панели переслаиваются, преломляя светлый фон в прохладные синие полосы, — сбалансированная по пустому пространству абстрактная геометрическая композиция.
На этой странице

Что даёт использование 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-форму.

Контроль затрат и типичные ошибки

Делаем расходы предсказуемыми

Генерация изображений тарифицируется за запрос, конкретная сумма зависит от модели и настроек — сверяйтесь с актуальной панелью цен в консоли, а не полагайтесь на захардкоженные допущения. Именно инженерная дисциплина защищает бюджет:

  • Устанавливайте лимиты на пользователя и на задачу в своём коде. Платформа применяет ограничения уровня аккаунта; ваше приложение должно применять ограничения уровня продукта, чтобы один вышедший из-под контроля клиент не исчерпал аккаунт.
  • Активно кешируйте. Хешируйте нормализованный промпт вместе с настройками и переиспользуйте сохранённые результаты. В сценариях редактора и предпросмотра одинаковые запросы встречаются часто.
  • Генерируйте в разрешении, в котором отдаёте. Рендерите тот размер, который будете показывать; избегайте дорогостоящего шаблона «отрендерить большое, затем уменьшить».
  • Привязывайте перегенерацию к явному действию пользователя. Автоматическая перегенерация на каждое нажатие клавиши в поле промпта — самый частый незаметный множитель затрат.
  • Логируйте модель, настройки и задержку каждого вызова. Без этого вы не сможете понять, какая функция обходится дорого.
  • Валидируйте вход до отправки. Отклоняйте пустые или аномально длинные промпты на клиенте, чтобы никогда не платить за заведомо провальные запросы.

Отладка сбоев, с которыми вы реально столкнётесь

Проходите этот список по порядку — он решает большинство инцидентов.

  1. 401 / 403 — аутентификация. Загружен ли ключ в то окружение, где реально выполняется запрос? Ключ, доступный в вашей оболочке, может отсутствовать в контейнере. Убедитесь, что префикс Bearer и имя заголовка указаны точно.
  2. 404 — неверный путь или модель. Версионированные пути и идентификаторы моделей меняются. Сверьте эндпоинт с документацией посимвольно.
  3. 422 / 400 — нагрузка отклонена. Тело ошибки укажет проблемное поле. Частые подозреваемые: неверный тип, отсутствие prompt или неподдерживаемый параметр. Уберите необязательные настройки и отправьте повторно, чтобы изолировать проблему.
  4. 429 — сработало ограничение частоты. Отступите с джиттером и повторите; не повторяйте сразу в цикле. Отличайте это от исчерпания квоты уровня аккаунта, где повтор не поможет.
  5. Таймауты. Если запрос выполняется слишком долго, значит вы блокируете там, где следует опрашивать. Перейдите на асинхронный поток и осознанно задайте таймауты клиента.
  6. Задача застряла в pending. Опрашивайте с дедлайном и считайте таймаут сбоем, заслуживающим оповещения, а не бесконечным ожиданием.

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

Сначала добейтесь работы вызова curl, перенесите его в клиент выше, сосредоточьте опрос и обработку ошибок в одном месте — остальная интеграция — обычный прикладной код. Актуальные возможности модели и цены смотрите в документации flux-3 и панели цен в консоли HiAPI.

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

Все статьи →

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

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

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