API удаления фона: прозрачные PNG для товаров

У вас есть несколько сотен фотографий товаров на серых столах и подоконниках, и магазин, маркетплейс или дизайнер хочет получить каждую как прозрачный PNG. SpicyAPI Background Remover делает это одним вызовом: вы отправляете URL фотографии и получаете основной объект на прозрачном PNG с исходными шириной и высотой. Остальная работа за вами: убедиться, что у файла действительно есть альфа-канал, проверить края на фонах, где он будет стоять, и выгрузить плоские копии, которые требует каждое место назначения.

Сначала попробуйте в Playground

Откройте Playground background-remover-v1. Перетащите фото товара в Input image, проверьте цену и нажмите Run model. Посмотрите прозрачный результат на светлом и тёмном фоне, прежде чем использовать то же фото в коде.

Что принимает и возвращает эндпоинт

Выход сохраняет размеры исходного холста, поэтому вырезанный объект можно поставить на новый фон без масштабирования. Используйте возвращённый альфа-канал как границу выреза; сохранение того же холста не гарантирует, что каждый край или цвет переднего плана останется неизменным. Подробности есть на странице модели Background Remover.

Сначала посмотрите настоящий результат

Пример со страницы модели: матовый флакон с пипеткой на сером студийном фоне, 1024 × 1536 пикселей. Это файлы «до» и «после» с этой страницы; «после» показан здесь на фоне страницы.

Запуск скрипта проверки из следующих разделов на этой паре даёт цифры хорошего результата: у выхода есть альфа-канал, размер совпадает с исходным, около 78% пикселей полностью прозрачны, около 22% непрозрачны и лишь около 0.35% — полупрозрачные пиксели краёв. Рамка объекта — 335 × 1 234 пикселя. На тёмно-синем фоне кончик пипетки, шлифованная манжета и матовые стеклянные плечики не дают светлой каймы.

Сделайте вызов

Установите spicyapi и pillow командой python -m pip install spicyapi pillow. Задайте SPICY_API_KEY и IMAGE_URL — прямой URL вашего исходного изображения, затем запустите этот пример. Он просит подтвердить цену, создаёт задачу, ждёт её, сохраняет вырезанный объект и записывает превью на светлом и тёмном фоне.

import os
import urllib.request
import uuid
from io import BytesIO
from pathlib import Path

from PIL import Image
from spicyapi import SpicyClient, output_assets

client = SpicyClient()
model = "spicyapi/background-remover-v1/edit"
inputs = {"image_url": os.environ.get("IMAGE_URL", "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png")}

quote = client.quote_task(model=model, input_data=inputs)
if input(f"Maximum ${quote['maxCharge']}. Create? [y/N] ") != "y":
    raise SystemExit("Stopped without creating a task.")

task = client.create_task(model=model, input_data=inputs, idempotency_key=str(uuid.uuid4()),
                          quote_id=quote["quoteId"], expected_cost=quote["estimatedCost"])
print("Task:", task["taskId"])  # keep this ID: a timeout does not cancel the task
task = client.wait_for_terminal(task["taskId"])
if task["state"] != "succeeded":
    raise RuntimeError(str(task.get("errorMessage", task["state"])))

asset = output_assets(task)[0]
request = urllib.request.Request(asset["url"], headers={"User-Agent": "SpicyAPI-Blog-Example/1.0"})
with urllib.request.urlopen(request, timeout=120) as response:
    data = response.read()
Path("cutout.png").write_bytes(data)

with Image.open(BytesIO(data)) as image:
    if image.format != "PNG":
        raise RuntimeError("Expected a PNG cutout.")
    rgba = image.convert("RGBA")
alpha = rgba.getchannel("A")
values = list(alpha.getdata())
print({"size": rgba.size, "alpha_min_max": alpha.getextrema(),
       "clear_fraction": sum(v <= 8 for v in values) / len(values),
       "solid_fraction": sum(v >= 247 for v in values) / len(values),
       "soft_fraction": sum(8 < v < 247 for v in values) / len(values),
       "subject_box": alpha.getbbox()})
for name, colour in [("light", "#f5f2e8"), ("dark", "#162235")]:
    Image.alpha_composite(Image.new("RGBA", rgba.size, colour), rgba).convert("RGB").save(name + ".jpg")

Чтобы повторить тот же запрос после потерянного ответа, используйте его ключ идемпотентности заново, а не создавайте новый (справка по идемпотентности). О загрузке локальных файлов см. Python SDK и документацию по медиа.

Проверьте прозрачность, декодировав файл

Белое превью ничего не доказывает. Это может быть настоящий вырез на белой странице, непрозрачное изображение с белым фоном или шахматная клетка, нарисованная прямо в пикселях. Декодируйте файл и прочитайте его альфа-канал. Спецификация PNG определяет, как хранится альфа; на практике вам нужно знать, могут ли после декодирования некоторые пиксели быть прозрачными, а не то, что говорит имя файла.

Пример показывает распределение альфа и записывает композиты на кремовом и тёмно-синем фоне для проверки с помощью Pillow. Сравните сообщённые размеры с вашим исходником.

Обратите внимание на пороги. Считать непрозрачной только альфа 255 — значит вводить себя в заблуждение: в выходе для флакона с пипеткой около 14% пикселей имеют альфа от 1 до 254, но почти все они равны 254, то есть визуально непрозрачны. Если считать прозрачной альфа до 8, а непрозрачной — от 247, то мягкая доля останется для того, что вас действительно интересует: сглаженные края, волосы и по-настоящему полупрозрачный материал.

Как читать отчёт:

• Отсутствие альфа-канала или alpha_min_max равный (255, 255) означает, что прозрачности нет: изучите конвейер, прежде чем проверять края.
• clear_fraction около 0 на фото, у которого был фон, или solid_fraction около 0 означает, что объект потерян или результат — дымка.
• Несовпадение размера обычно указывает на исходник, повёрнутый по EXIF, или на изменение размера в вашем коде, поскольку эндпоинт сохраняет размеры.
• Большой soft_fraction нормален для стекла, ткани и волос и тревожен для матовой кружки. Задавайте пороги для каждой категории товаров после просмотра пилотного набора, а не одно глобальное число.
• Рамка объекта, касающаяся края холста на фото, которое вы обрезали с запасом, говорит о том, что остался второй объект.

Подготовьте фото, не меняя товар

Решите, что считать товаром, до съёмки или обрезки: лента, упаковка и контактная тень либо входят, либо нет, а инструмент не может угадать задание, которое никогда не было записано. Не дорисовывайте отколотый край и не придумывайте недостающий логотип; дефект, который объявление должно показать, остаётся на фото.

• Обрежьте, чтобы убрать конкурирующие объекты, но оставьте поле вокруг каждого выступающего элемента, чтобы ручка или ремешок не были срезаны до того, как их увидит API.
• Перекрывающиеся объекты обрезкой не исправить, потому что скрытую границу придётся угадывать. Переснимите, а перекрытия, прозрачные витринные подставки и обрезанные объекты направляйте на отдельную линию исключений, чтобы они не забивали обычную партию.
• Отправляйте самый чистый файл. Повторные экспорты в JPEG оставляют блочные артефакты именно там, где краю нужна детальность; храните рабочую копию без потерь. Цветовые профили конвертируйте осознанно, потому что небрежная конвертация меняет цвет товара до того, как кто-либо посмотрит на вырез.

Проверяйте край там, где изображение будет использоваться

Положите вырез на настоящий целевой фон, а не только на страницу, где вы его проверяете. Вырез, который чисто выглядит на кремовом, может показать бледную кайму на тёмно-синем; эта кайма — цвет исходного фона, оставшийся в частично прозрачных пикселях. Проверяйте в размере доставки, чтобы понять, важен ли дефект, и при 100%, чтобы увидеть его форму. В двух композитах скрипта используются кремовый и тёмно-синий; замените их цветами вашего бренда.

Смотрите на те области, по которым узнаётся такой товар, а не на каждый пиксель одинаково: внутреннюю часть ручки кружки, край и основание, шнурки и подошвы, щетину, кончик пипетки. Сравнивайте исходник, альфа и композит в одном масштабе и с одной обрезкой. Отклоняя файл, назовите утраченную деталь и место назначения («проём ручки заполнен на тёмном композите»), чтобы следующий человек знал, нужно ли обрезать, ретушировать или переснимать.

Три ситуации требуют решения, а не повторной попытки:

• Отверстия внутри силуэта. Проём ручки или просвет между перекладинами стула относятся к фону. Проверка только по контуру может выглядеть правильной, хотя отверстие заполнено. Проверьте его на тёмном композите.
• Тени. Контактная тень «сажает» товар на поверхность; длинная падающая тень тянет в вырез текстуру фона. Решите, оставляет ли мастер тень и будет ли макет рисовать свою. Если добавляете свою, смягчите или уберите тень, уже имеющуюся в исходнике, чтобы две не конфликтовали.
• Стекло и полупрозрачный материал. Цвет бутылки включает свет фона, проходящий сквозь неё, поэтому никакой вырез не даст физически правильную бутылку на любом новом фоне; бледное студийное отражение, которое естественно выглядит на белом, на тёмном может выглядеть неверно. Для полупрозрачного пластика и ткани сохраняйте частичную альфа, а не обрезайте её порогом до 0 или 255, и не эродируйте всю маску ради удаления каймы: вы утончите товар и потеряете тонкие детали. Ретушируйте локально на копии.

Исправляйте сбой на том этапе, который его вызвал

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

Подтолкнуть инструмент промптом нельзя, поэтому рычаги — это входная фотография и то, что вы делаете после вызова. Если одна категория всё время даёт сбои, меняйте способ её съёмки, а не повторяйте запросы.

Сведите в плоский файл для мест, где нужен сплошной фон

Маркетплейсы часто просят JPEG на белом. У JPEG нет альфа, поэтому экспорт мастера в JPEG заполняет прозрачную область цветом по умолчанию, который никто не утверждал. Сводите на выбранный цвет, храните PNG как мастер и масштабируйте равномерно (никогда не растягивайте ширину и высоту независимо). Файл light.jpg, который записывает скрипт, — это ровно этот шаг на кремовом; для белого поменяйте цвет в цикле или экспортируйте отдельный плоский JPEG из графического редактора. Проверяйте плоский файл, а не только мастер: передискретизация, цветовая конвертация и сжатие добавляют собственные дефекты. Если кайма появляется только после загрузки в ваш магазин или CMS, сравните декодированные пиксели мастера, вашего экспорта и миниатюры платформы; причина часто в масштабировании или повторном сжатии платформой, а не в вырезе.

Когда другой маршрут — правильный инструмент

Для простого выреза Background Remover — самый дешёвый маршрут в этой таблице, и он сохраняет размер исходного холста. Выбирайте другой маршрут, когда нужно то, чего он намеренно не предлагает.

Если генеративная модель возвращает PNG, это не делает его прозрачным: PNG может содержать непрозрачный белый фон. Декодируйте каждый результат тем же скриптом. Там, где важны точные пиксели товара (этикетки, логотипы, текст на упаковке), выбирайте маршрут извлечения, а не генеративную перерисовку.

Пропустите партию, не утопив проверяющих

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

• Отправляйте с ограниченной параллельностью и держите отдельную очередь загрузки, чтобы медленная загрузка никогда не запускала повторное извлечение. Повторяйте неудавшуюся загрузку для уже имеющегося результата, пока его ссылка действительна. Устройство очереди разбирает руководство по обратному давлению.
• Для каждой ревизии исходника храните собственный ID ассета, контрольную сумму исходника, ID задачи, место результата и решение проверки. Одного SKU недостаточно: у товара несколько ракурсов и пересъёмок.
• Считайте «succeeded» признаком «готово к проверке», а не «публиковать». Запускайте скрипт автоматически, затем отправляйте человеку только помеченные файлы и выборку. Категории, прошедшие пилот (твёрдые предметы на нейтральных фонах), можно перевести на более лёгкую линию с периодической выборкой для выявления дрейфа; отражающие, прозрачные и неоднозначные предметы остаются на полной проверке. Проверяйте главные изображения кампаний раньше второстепенных ракурсов, а не в порядке завершения.
• Об уведомлениях о завершении см. руководство «Polling vs Webhook» для асинхронных задач; в любом случае результат попадает на тот же шаг проверки.
• Останавливайтесь, когда сбои имеют общую причину. Десять потерянных проёмов ручек — это сведения об исходном наборе, а не десять поводов для повторных попыток.

Сколько стоит принятое изображение

Сто вырезов стоят $0.48, тысяча — $4.80. Важна цифра затрат на принятый мастер. В качестве планового примера: партия из 100 первых вырезов плюс 10 заново обрезанных — это 110 × $0.0048 = $0.528; если проверку проходят 95, получается около $0.0056 за принятое изображение.

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

Храните исходник, мастер и экспорты раздельно

Храните исходное фото, прозрачный мастер PNG и каждую сведённую копию для доставки как отдельные файлы с именами по их назначению (например, <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream), а ретушированные версии держите отдельно от нетронутого результата API, чтобы позднюю кайму можно было отнести на счёт выреза или экспорта. Сохраняйте у каждого мастера утверждённый целевой размер, чтобы одобрение в размере карточки не приняли за одобрение в размере главного изображения.

Фиксируйте каждый отказ в одной категории: не тот объект, потерянная деталь, кайма, остаток фона или дефект экспорта. Подсчёт важен, только если он что-то меняет: правило обрезки, ручную линию для стекла, исправленный пресет экспорта. Давайте фотографу конкретные правила съёмки («держать всю ручку в кадре; без подарочной коробки за проёмом», «более тёмный фон для светлых товаров»), а не «сделай проще для ИИ».

Вопросы

Есть ли бесплатный API для удаления фона?

Для этого эндпоинта нет: каждый завершённый выход стоит $0.0048, поэтому пилот на 100 фото обойдётся в $0.48. Если бесплатность обязательна, самостоятельный хостинг открытого инструмента вроде rembg избавляет от платы за изображение, но тогда вы сами его запускаете и настраиваете; хостируемый маршрут даёт стабильный эндпоинт и предсказуемую стоимость.

Делает ли сохранение результата в PNG фон прозрачным?

Нет. PNG может нести альфа, но может содержать и непрозрачный белый фон. Декодируйте файл и прочитайте альфа-канал, затем проверьте композиты на светлом и тёмном фоне. Переименование JPEG в .png ничего не добавляет.

Можно ли велеть ему сохранить ручку, волосы или тень?

В этой задаче нет: её вход — только URL изображения. Обрежьте исходник, переснимите или ретушируйте локально. Если нужен результат по промпту, используйте маршрут правки изображений из таблицы выше и затем проверьте товар и альфа.

С чего начать?

Выберите один характерный товар и одно место назначения. Отправьте фото, декодируйте PNG, проверьте края на двух фонах, сведите утверждённую производную в плоский файл и попросите дизайнера открыть её в настоящем макете. Затем прогоните более сложные позиции пилотного набора и запишите, каким нужна пересъёмка или ручная линия, прежде чем планировать весь каталог.

Поручите вызов Agent

Используйте Agent, когда хотите, чтобы он подготовил входные данные и вернул результат, а вы утверждали цену и творческие решения.

• CLI: сохраните тот же входной объект как input.json и выполните npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait. CLI запрашивает подтверждение цены; сохраните возвращённый ID задачи для восстановления.
• MCP: попросите вашего ассистента использовать spicyapi_task_create для spicyapi/background-remover-v1/edit, затем spicyapi_task_wait. Сервер MCP перед созданием запрашивает подтверждение цены.
• Skill: установите командой npx skills add spicyapi-ai/spicy-skill, затем попросите $spicyapi выполнить тот же рабочий процесс и остановиться для вашего одобрения. Skill использует настроенное подключение CLI или MCP.