Руководство
Как вызывать flux-1-fill-pro через HiAPI API: curl, Python и асинхронный опрос
На этой странице
Что делает flux-1-fill-pro и когда его применять
flux-1-fill-pro — это модель редактирования изображений на основе заполнения. Вы передаёте ей исходное изображение и маску, отмечающую область, которую нужно перегенерировать, а она возвращает новое изображение, где эта область заменена. Область за пределами маски должна остаться неизменной — именно этим она отличается от чисто текстовых моделей генерации изображений или моделей полной стилизации.
Её стоит использовать, когда правка локальна и окружающий контекст важен:
- Удаление объектов — обведите маской ненужные элементы и позвольте модели восстановить то, что должно находиться за ними.
- Замена объектов — выделите маской область, опишите в промпте новое содержимое, сохраняя остальную часть сцены неизменной.
- Локальная ретушь — исправляйте текстуры, блики или мелкие дефекты, не перегенерируя всё изображение.
- Вставка в конвейер — программно дорабатывайте товарные изображения, миниатюры или сгенерированные материалы, где лишь одна область требует повторной обработки.
Она не подходит, когда вам нужна совершенно новая композиция по промпту или когда область маски настолько велика, что модель фактически генерирует изображение с нуля — в таких случаях стандартная конечная точка генерации поведёт себя предсказуемее.
Остальная часть руководства посвящена подключению flux-1-fill-pro к коду через HiAPI API: структура запроса, вызов через curl, эквивалент на Python и обработка асинхронных задач, в которой чаще всего ошибаются при первой интеграции.
Подготовка и настройка аутентификации
Прежде чем отправить первый запрос, убедитесь в трёх вещах.
API-ключ
Создайте ключ в своей учётной записи HiAPI и держите его вне системы контроля версий. В примерах ниже он читается из переменной окружения, поэтому фрагменты можно безопасно копировать:
export HIAPI_API_KEY="your_key_here"
В Python загружайте его таким же образом через os.environ. Если вы запускаете это в CI, передавайте его как секрет, а не коммитьте файл .env.
Идентификатор модели
Каждый запрос указывает модель по имени. В этом руководстве идентификатор — flux-1-fill-pro. Храните его как константу в коде, а не разбрасывайте строковые литералы — тогда для смены модели позже потребуется изменить одну строку.
Базовый URL
Все вызовы направляются на базовый URL HiAPI API, указанный в справочной документации платформы. Храните его вместе с ключом в конфигурации, чтобы промежуточная и производственная среды могли различаться без изменения кода.
Перед началом одно структурное замечание: запросы на заполнение несут данные изображения. Отправляйте изображения в кодировке base64 в формате JSON, а не пытайтесь протолкнуть их через загрузку формы; при этом держите тайм-аут запроса на стороне клиента достаточно большим — кодирование больших изображений добавляет задержку ещё до того, как запрос покинет ваш процесс. Сверьтесь с документацией платформы насчёт текущих ограничений на размер полезной нагрузки; если ваше исходное изображение превышает указанный предел, уменьшите его перед кодированием, а не допускайте, чтобы запрос отказывал на границе.
Структура запроса локальной перерисовки
Каждый вызов flux-1-fill-pro имеет одинаковый логический состав независимо от языка.
Исходное изображение
Изображение, которое вы редактируете, закодированное в строку. Оно определяет холст: его размеры задают систему координат, в которой находится маска, а его содержимое даёт модели контекст, благодаря которому заполнение выглядит правдоподобно.
Маска
Маска отмечает, какие области будут перегенерированы. Это самый частый источник путаницы, поэтому чётко определите, какое соглашение использует ваша полезная нагрузка: область, отмеченная маской, — это область, которую модели разрешено изменять. Стройте маску как отдельное изображение, где область для заполнения визуально явно отличается от области, которую нужно сохранить. Инвертирование маски — классическая ошибка: вы получите результат, где модель отредактировала всё, кроме нужной вам области.
Маска должна точно совпадать по размерам с исходным изображением. Маска, нарисованная в другом разрешении, либо будет отклонена, либо молча сместится — оба результата потратят один круговой обмен впустую.
Промпт
Текстовое описание того, что должно появиться внутри маски. Будьте конкретны и локальны: опишите содержимое и его отношения освещения или текстуры с окружающей средой, а не всю сцену. «Деревянная скамья, продолжающая отделку витрины, мягкий послеполуденный свет слева» даёт модели больше опоры, чем «более красивый фон».
Необязательные управляющие параметры
В зависимости от документированного набора параметров вы также можете передавать, например, seed для воспроизводимости или параметр интенсивности, управляющий степенью отклонения заполнения от исходных пикселей. С параметрами, отсутствующими в текущей справочной документации, обходитесь как с неподдерживаемыми, а не угадывайте их имена.
Все четыре — модель, промпт, исходное изображение, маска — передаются в одном и том же JSON-теле. Следующие два раздела отправляют именно его.
Рабочий запрос curl
Начните с curl, чтобы увидеть сырой конверт до того, как какая-либо клиентская библиотека его замаскирует.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
Где request.json выглядит так:
{
"model": "flux-1-fill-pro",
"prompt": "деревянная скамья, продолжающая отделку витрины, мягкий послеполуденный свет слева",
"image": "<base64-encoded source image>",
"mask": "<base64-encoded mask image>"
}
Есть два практических приёма для построения этого файла. Первый: генерируйте base64-полезную нагрузку командой, а не вставляйте вручную:
base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64
Затем склейте их небольшим шагом с jq или Python, чтобы собрать request.json. Ручное редактирование многомегабайтных base64-блоков в JSON — вот источник усечённых полезных нагрузок и загадочных ошибок 400.
Разбор ответа
Конверт ответа подсказывает, что делать дальше. Завершённая задача возвращает отредактированное изображение — обычно в виде URL- или base64-поля, в формате, указанном в текущей справочной документации. Поставленная в очередь задача возвращает идентификатор и статус, которые вы затем опрашиваете (см. ниже). Не предполагайте, что первый ответ всегда содержит пиксели; с первого дня пишите парсер так, чтобы он обрабатывал обе формы, иначе вам придётся его переписывать при первой же постановке задач в очередь под нагрузкой.
Проверяйте код состояния HTTP до разбора тела ответа. 4xx означает, что сам запрос неверен, и повтор не поможет; исправьте полезную нагрузку.
Тот же вызов на Python
Версия на Python — это тот же запрос, но удобнее в использовании. SDK не нужен — достаточно requests для обращения к конечной точке HiAPI.
import base64
import json
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "flux-1-fill-pro"
def b64(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("ascii")
def create_fill(source_path: str, mask_path: str, prompt: str) -> dict:
payload = {
"model": MODEL,
"prompt": prompt,
"image": b64(source_path),
"mask": b64(mask_path),
}
resp = requests.post(
f"{BASE_URL}/v1/images/edits",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=120,
)
if resp.status_code >= 400:
raise RuntimeError(f"HiAPI error {resp.status_code}: {resp.text}")
return resp.json()
timeout задан намеренно. Кодирование и загрузка больших изображений занимают больше времени, чем типичный JSON-вызов, а неограниченный запрос — вот почему скрипты молча зависают в пакетных задачах. Выброс исключения при 4xx с телом ответа превращает загадочный сбой в читаемый.
Держите идентификатор модели и конечную точку в конфигурации на уровне модуля, чтобы обновление версии требовало изменения в одном месте. Если вы обрабатываете много изображений, переиспользуйте requests.Session, чтобы соединения пулировались, а не переустанавливались при каждом вызове.
Разобранный словарь — это либо готовый результат, либо дескриптор задачи; последним занимается следующий раздел.
Обработка асинхронных задач и опрос
Запросы на заполнение могут быть медленными, поэтому API может вернуть дескриптор задачи вместо готового изображения. Правильный шаблон — цикл опроса с ограничением, а не фиксированный sleep и надежда.
Цикл
def wait_for_result(job: dict, *, interval=2.0, timeout=180.0) -> dict:
deadline = time.monotonic() + timeout
current = job
while time.monotonic() < deadline:
status = current.get("status")
if status in {"succeeded", "completed"}:
return current
if status in {"failed", "canceled", "cancelled"}:
raise RuntimeError(f"Job ended as {status}: {current}")
time.sleep(interval)
interval = min(interval * 1.5, 15.0) # мягкий откат
current = fetch_job(current["id"])
raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")
fetch_job использует ту же схему запроса, что и выше, обращаясь к документированной конечной точке статуса задачи с идентификатором задачи и вашими заголовками аутентификации.
Почему откат, а не фиксированный интервал
Плотный цикл опроса очереди без пользы молотит API. Начните с короткого интервала и удваивайте его до верхнего предела — это сохраняет быструю реакцию на раннее завершение, не тратя тысячи опросов на медленные задачи. Ограничьте интервал сверху, чтобы вы всё ещё замечали завершение в пределах нескольких секунд.
Почему тайм-аут и неудача — это разные вещи
Тайм-аут означает, что вы прекратили ждать, а не что задача не удалась. Сохраняйте идентификатор задачи при выбросе исключения, чтобы вызывающий код мог позже возобновить опрос, не переотправляя задачу и не платя дважды за одну и ту же работу. В вашем конвейере рассматривайте тайм-аут, неудачу задачи и HTTP-ошибку как три разных исключения — их сведение в одну общую ошибку сильно затрудняет разбор производственных инцидентов.
Отладка типичных сбоев
Большинство ответов с ошибками попадает в несколько категорий. Проверяйте их по порядку.
401 / 403 — аутентификация
Проверьте в первую очередь: точно ли заголовок Authorization: Bearer <key>, без кавычек и лишних пробелов из никогда не экспортированной переменной оболочки? Пустой $HIAPI_API_KEY даёт Bearer-токен, состоящий только из слова Bearer, и он терпит неудачу так же, как неверный ключ.
400 — неверный формат полезной нагрузки
Проверьте в первую очередь: остаётся ли тело допустимым JSON после склейки base64-строк? Выгрузите request.json и прогоните его через python -m json.tool. Префикс data:image/png;base64, в полях изображений — частая причина; удалите их, если справочная документация явно не требует обратного.
Несовпадение маски и изображения
Проверьте в первую очередь: точно ли совпадают размеры маски и исходного изображения в пикселях? Затем проверьте полярность — убедитесь, что белая область — это та, которую вы хотите перегенерировать. Результат, выглядящий противоположно задуманному, почти всегда означает инвертированную маску, а не проблему с промптом.
Переполнение промпта
Если незамаскированная область изменилась или заполнение выглядит глобальным, ваша маска может быть слишком большой, а промпт — слишком охватывающим всю сцену. Сузьте и то, и другое: подтяните маску к фактической области правки и описывайте только то, что находится внутри маски.
Тайм-аут задачи
Проверьте в первую очередь: размер полезной нагрузки. Слишком большое исходное изображение — самая частая причина того, что задача никогда не завершается. Уменьшите его, повторите один раз, и если тайм-аут сохраняется, сверьтесь со справочными ограничениями на маленьком тестовом изображении, прежде чем предполагать проблему сервиса.
Пустое или отсутствующее поле результата
Проверьте в первую очередь: обрабатываете ли вы форму ответа с постановкой в очередь. Парсер, читающий только завершённую форму, не увидит ничего при первом вызове. Во время разработки логируйте полный конверт ответа, чтобы увидеть форму до написания защитного кода.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий