Как использовать API FLUX.1 Fill Pro: Inpainting по маске с помощью curl и Python

flux-1-fill-pro — это модель hiapi для inpainting на основе маски: вы отправляете исходное изображение, чёрно-белую маску и промпт, и перерисовываются только белые области. В этом руководстве приведены готовые к использованию запросы curl и Python, асинхронный процесс, а также результаты одного реального запуска с точки зрения границ маски и размера выходного изображения. Вам нужно получить API-ключ в dashboard.

Структура запроса

Модель работает на унифицированном API задач. Создайте задачу с помощью POST https://api.hiapi.ai/v1/tasks, опрашивайте GET /v1/tasks/<taskId>, затем читайте data.output[0].url. Следующие входные параметры взяты со страницы модели и из документации API:

Поле	Тип	Описание
input.image	URL, обязательно	Исходное изображение. JPEG, PNG, GIF или WebP.
input.mask	URL, обязательно	Чёрный цвет сохраняет исходное изображение, белый — перерисовывается. Размер должен совпадать с исходным изображением.
input.prompt	string, обязательно	Описывает новое содержимое в белой области. Не более 4 000 символов.
input.steps	int, 15–50	По умолчанию 50.
input.guidance	number, 1.5–100	По умолчанию 60.
input.seed	int	При одинаковых входных данных фиксированный seed даёт согласованные результаты.
input.output_format	jpg | png	По умолчанию jpg.
input.prompt_upsampling	bool	По умолчанию false. Оставьте выключенным, чтобы сохранить ваши точные формулировки.

image и mask — это URL, а не base64 или загрузка файлов. Разместите их там, где API сможет получить их по http(s).

Минимальный запрос curl

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418739459-82bb18075f29c864-mask.png",
      "prompt": "Большая живописная картина маслом с туманным горным озером в утренней дымке, в тонкой чёрной рамке, ровно висящая на стене; сохранить диван, пол и освещение без изменений.",
      "steps": 30,
      "guidance": 60,
      "seed": 42,
      "output_format": "png"
    }
  }'

Ответ — {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}. Опрашивайте этот ID, пока data.status не станет success или fail.

Python: создание, опрос, загрузка

import os, time, requests

API = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def inpaint(image_url, mask_url, prompt, **opts):
    body = {"model": "flux-1-fill-pro",
            "input": {"image": image_url, "mask": mask_url, "prompt": prompt, **opts}}
    r = requests.post(f"{API}/v1/tasks", headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:
        try:
            d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=20).json()["data"]
        except requests.RequestException:
            time.sleep(5)          # transient network error: poll the same taskId again
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error", d))
        time.sleep(5)

url = inpaint(
    "https://example.com/room.jpg",
    "https://example.com/room-mask.png",
    "Пейзаж в рамке с тонкой чёрной рамкой; сохранить комнату без изменений.",
    steps=30, seed=42, output_format="png",
)
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Скачайте результат сразу. URL вывода содержит expireAt, а файлы хранятся временно, поэтому не сохраняйте эту ссылку как постоянный адрес.

Замечания для продакшена

• Опрос или callback. Для пакетных задач добавьте в тело задачи "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} и дедуплицируйте уведомления по ID задачи. Оставьте опрос как резервный вариант.
• Повторяйте опрос, а не создание. Новый POST создаёт и тарифицирует новую задачу. Если запрос опроса завершился ошибкой, опросите тот же taskId ещё раз.
• Маска должна соответствовать исходному изображению. Маска должна точно совпадать по размеру с исходным изображением, поэтому создавайте её из того же файла (инструмент многоугольников, вывод сегментации), а не масштабируйте скриншот.
• Фиксируйте seed при подборе параметров. Используйте один и тот же seed и меняйте только steps или guidance, чтобы каждое различие было вызвано этим параметром.

Стоимость за изображение указана на странице цен — проверьте её перед запуском на большом объёме материалов.

Что показал один реальный запуск

Я один раз выполнил приведённый выше запрос curl для примера фотографии комнаты с этой страницы (1600×900) и её прямоугольной маски (белая рамка в области x 840–1240, y 160–580). Настройки: steps: 30, guidance: 60, seed: 42, output_format: png.

• Время. Задача находилась в состоянии handling около 25 секунд, затем archiving, и примерно через 38 секунд от начала достигла success.
• Размер вывода отличается от исходного изображения. Возвращённый PNG был 1440×810, а не 1600×900. Соотношение сторон совпадает, но размеры в пикселях отличаются. Если вы хотите скомпоновать результат с исходным изображением, сначала измените размер одного из них — не предполагайте масштаб 1:1.
• За пределами маски всё осталось без изменений. После масштабирования исходного изображения до 1440×810 и вычисления разницы с выводом 81% пикселей внутри белой рамки изменились более чем на 8 уровней (0–255), а за пределами рамки — только 0,03% пикселей. На расстоянии более 12 px от края маски максимальная разница составила 11 уровней. Диван, подушки, растение, пол и свет из окна не были перерисованы.
• Область действия промпта. Промпт описывал только картину и то, что нужно сохранить, и результатом стал сюжет с горным озером в рамке, заполнивший белую рамку.
• Неверные URL завершаются ошибкой при опросе, а не при создании. Другой запрос, в котором image и mask были заданы как строки, не являющиеся URL, вернул 200 и taskId, после чего задача примерно через 3 секунды завершилась со status: fail и error.code: TASK_FAILED. То, что ваш POST успешен, не означает, что входные данные корректны, поэтому обязательно проверяйте финальный статус.

Не тестировалось: несоответствие размеров маски и исходного изображения, маски с серыми (мягкими) значениями, маски с альфа-каналом, а также экстремальные значения guidance или steps. Документация утверждает, что маска должна совпадать по размеру с исходным изображением, а я тестировал только жёсткий бинарный прямоугольник. Я не запускал несколько seed, поэтому не могу сказать, насколько заполнение меняется между запусками.

Когда выбирать Fill Pro

Используйте её, когда редактирование должно останавливаться на жёстких границах, которые контролируете вы, например, этикетки продуктов, линии стен или швы одежды. Для редактирования, описываемого текстом, без маски используйте модели на основе чистого промпта. Руководство по inpainting изображений и удалению объектов сравнивает их. Чтобы стереть что-то по маске без промпта, см. руководство по Bria Eraser.

Связанное

• Страница модели FLUX.1 Fill Pro
• Справочник по API flux-1-fill-pro
• Цены
• Как использовать API Bria Eraser
• Руководство по FLUX.2 image-to-image

Часто задаваемые вопросы

Обязательны ли image и mask?

Да. Текущая документация указывает image, mask и prompt как обязательные.

Какой цвет модель перерисовывает?

Белый. Чёрные пиксели сохраняют исходное изображение.

Должна ли маска совпадать по размеру с исходным изображением?

Документация говорит, что да. В моём запуске я использовал совпадающую пару и не тестировал несовпадение.

Каким получается размер вывода?

В моём запуске исходное изображение 1600×900 вернуло PNG 1440×810 с тем же соотношением сторон.