HiAPI
Блог

Руководство

Как вызывать flux-1-fill-pro через HiAPI API: curl, Python и асинхронный опрос

Nov 12, 2026
Обложка блога HiAPI: на тёмно-синем фоне три вложенные широкие стрелки последовательно продвигаются по горизонтали, передний край — абрикосово-оранжевый, в стиле плоской диаграммы сигнальных потоков.
На этой странице

Что делает 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, в полях изображений — частая причина; удалите их, если справочная документация явно не требует обратного.

Несовпадение маски и изображения

Проверьте в первую очередь: точно ли совпадают размеры маски и исходного изображения в пикселях? Затем проверьте полярность — убедитесь, что белая область — это та, которую вы хотите перегенерировать. Результат, выглядящий противоположно задуманному, почти всегда означает инвертированную маску, а не проблему с промптом.

Переполнение промпта

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

Тайм-аут задачи

Проверьте в первую очередь: размер полезной нагрузки. Слишком большое исходное изображение — самая частая причина того, что задача никогда не завершается. Уменьшите его, повторите один раз, и если тайм-аут сохраняется, сверьтесь со справочными ограничениями на маленьком тестовом изображении, прежде чем предполагать проблему сервиса.

Пустое или отсутствующее поле результата

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

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

Все статьи →

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

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

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