Как использовать API Bria Eraser: curl, Python и один рабочий запрос

bria-eraser удаляет объекты с фотографий. Вы отправляете изображение и чёрно-белую маску, и модель заполняет область маски подходящим фоном. Поля prompt нет. В этом руководстве показан один полностью рабочий запрос, код Python для его выполнения и детали, от которых зависит, сработает ли ваша маска. Ключ HiAPI нужно получить на панели управления.

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

Модель использует единый асинхронный эндпоинт POST /v1/tasks. Оба URL ниже являются публичными и были доступны на момент написания статьи:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-eraser",
    "input": {
      "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025379-46c31ddb2b52110d-e1-street-src.png",
      "mask_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025861-e5d2a17ae1d12d41-e1-street-mask.png",
      "mask_type": "manual"
    }
  }'

Этот вызов сразу возвращает идентификатор задачи, а не изображение:

{"code":200,"data":{"taskId":"tk-hiapi-01M5K80RFJN3J788MMJT7YDVNB"},"message":"success"}

Опрашивайте GET /v1/tasks/<taskId>, пока data.status не станет success, затем прочитайте data.output[0].url.

Python: отправить, опросить, скачать

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

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

def erase(image_url: str, mask_url: str, out_path: str) -> str:
    r = requests.post(API, headers=HEADERS, timeout=30, json={
        "model": "bria-eraser",
        "input": {"image_url": image_url, "mask_url": mask_url, "mask_type": "manual"},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: poll the SAME task id again
        if d["status"] == "success":
            img = requests.get(d["output"][0]["url"], timeout=60)
            img.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(img.content)
            return task_id
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(task_id)

Сохраняйте идентификатор задачи. Если какой-то опрос не удался, опросите этот же идентификатор снова. Не отправляйте задачу повторно, поскольку каждая отправка — это отдельная оплачиваемая задача.

Поля запроса

Поле	Обязательно	Описание
input.image_url	Да	Публичный URL http/https. JPEG, PNG или WEBP.
input.mask_url	Да	Чёрно-белое изображение с тем же соотношением сторон, что и исходное.Белые области удаляются, чёрные сохраняются.
input.mask_type	Нет	manual (по умолчанию) для масок, нарисованных кистью, automatic для масок, созданных инструментами сегментации.
input.preserve_alpha	Нет	По умолчанию false. Установите true, чтобы сохранить прозрачность входного изображения с альфа-каналом.

Продакшен: использование callback

Опрос подходит для тестирования. Для сервиса передайте callback верхнего уровня callback, чтобы HiAPI уведомил вас о завершении задачи:

{
  "model": "bria-eraser",
  "input": { "image_url": "...", "mask_url": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

Оставьте опрос в качестве запасного варианта на случай, если callback потеряется. URL выходных данных истекают, поэтому после успешного завершения задачи как можно скорее скопируйте файл в собственное хранилище.

Что я фактически запустил и увидел

В день написания статьи я выполнил запрос из раздела curl и опрашивал его до завершения.

• Последовательность статусов: handling → archiving → success. archiving появляется после completion работы, но до появления output. Считайте это «ещё не завершено» и продолжайте опрос.
• Время: задача от создания до завершения заняла 16 секунд. URL output появился через несколько секунд после этого.
• Выходные данные: PNG на temp.hiapi.ai, 1360 × 768, с альфа-каналом. Это тот же размер, что и у исходного изображения, что соответствует документации о сохранении исходного разрешения.
• Биллинг: на момент проверки цена этой модели в публичных данных о ценах составляла $0.0575 за изображение. Актуальные цены см. в разделе цены.
• Ошибка валидации: я намеренно отправил mask_type: "bogus". API отклонил запрос с HTTP 400:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: mask_type: value must be one of 'manual', 'automatic'"}

Я проверил только один запрос на одном изображении. Я не тестировал другие стили масок, очень большие изображения или маски с соотношением сторон, не совпадающим с изображением. Приведённые ниже пояснения об этих случаях взяты из документации модели, а не из моих тестов.

Советы по маске (из документации)

• Немного выходите за края объекта. Маска, точно повторяющая контур, часто оставляет ореол вокруг исходного объекта.
• Сохраняйте у маски то же соотношение сторон, что и у фотографии. Документация этого требует, но не говорит, что произойдёт в противном случае.
• Используйте automatic только для масок от инструментов сегментации или вырезания. Для масок, нарисованных кистью, используйте manual.

Какую страницу мне читать?

В этом руководстве описано удаление на основе маски с помощью специализированного эндпоинта. Для редактирования с помощью промптов с использованием универсальных моделей image-to-image см. инпейнтинг изображений и удаление объектов. Если нужно удалить весь фон, а не отдельный объект, см. руководство по удалению фона. Страница модели находится по адресу bria-eraser, а справочник по полям — в документации API.

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

Нужен ли bria-eraser промпт?

Нет. В документации указано, что промпт не требуется, и мой запрос содержал только изображение, маску и mask_type.

Какой цвет в маске будет удалён?

Белый будет удалён, чёрный сохранится.

Будет ли вывод меньше входа?

В моём запуске вывод был 1360 × 768, точно как исходное изображение.

Что использовать: опрос или callback?

Для тестирования — опрос. В продакшене используйте callback.url и when: "final", а опрос — как запасной вариант.