Введение
Возможности эндпоинта
Находит объект из prompt, удаляет всё остальное и возвращает PNG с прозрачным фоном.
Основные входные данные
image_url — фото, prompt — описание нужного объекта. autocrop обрезает холст по объекту, refine_edges дополнительно очищает края. Обе опции по умолчанию выключены.
Результат
Один прозрачный PNG размером с фото, если autocrop не включён.
| Характеристика | Значение |
|---|---|
| Ввод | Изображение |
| Вывод | Изображение |
| Эндпоинт | Редактирование изображения |
| Вход | Одно фото и текстовое описание объекта |
| Выход | Прозрачный PNG |
| Холст | Размер фото или обрезка с autocrop |
| Очистка краёв | Дополнительный проход по желанию ( |
Ключевые возможности и особенности
Один из двух людей по описанию
В сцене бара с двумя людьми мы запросили "the woman in the cream sweater". Она вернулась на прозрачном холсте полного размера 1536×864 с сохранёнными краями волос и свитера; мужчина и полка с бутылками исчезли.
Один бокал с плотной обрезкой
При включённом autocrop запрос "the wine glass in front of the man" дал PNG 130×307 только с бокалом. Огни бара сквозь чашу сохранились — учитывайте это при размещении на новом фоне.
Без рисования маски
Не нужно рисовать кистью или ставить рамку. Короткой фразы с цветом, положением или деталью одежды достаточно, чтобы отличить похожие объекты.
Параметры запроса
| Параметр | Обязательно | Описание |
|---|---|---|
image_url | Да | Фото с объектом: загрузка JPEG, PNG, WebP или прямая ссылка. Без autocrop вырезка сохраняет размеры фото. Не менее 1 символов |
prompt | Да | Обязательное поле. Опишите один объект, например "the red car" или "the woman in the cream sweater". Не менее 1 символов · Не более 500 символов |
refine_edges | Нет | По умолчанию выключено. Дополнительный проход удаляет остатки фона и уточняет прозрачность краёв; полезно для волос и мягких контуров. По умолчанию: |
autocrop | Нет | По умолчанию выключено: вырезка возвращается в размере фото. При включении холст плотно обрезается по объекту. По умолчанию: |
Стоимость
$0.024 / изображение
Фиксированная цена за извлечение; описание, очистка краёв и обрезка на неё не влияют. Неудачные запросы не оплачиваются.
Сценарии использования
Один товар из насыщенного кадра
Извлеките одну бутылку, сумку или туфлю из постановочного фото для каталога без ручной ретуши остальной сцены.
Один человек из группового фото
Обычное удаление фона оставляет всех на переднем плане. Здесь вы называете нужного человека, а остальные удаляются вместе с фоном.
Материалы для коллажей и миниатюр
Обрежьте вырезку по объекту и поместите на новый фон, миниатюру видео или слайд.
Руководство по промптам и практические советы
Опишите один объект
Укажите в prompt короткую фразу, например "the red car" или "the woman on the right". Для похожих объектов добавьте цвет, положение или деталь одежды.
Выберите холст
Выключите autocrop для вырезки размером с фото, которую можно вернуть на прежнее место. Включите для плотно обрезанного PNG для карточки товара или стикера.
При необходимости очистите края
Включите
refine_edgesдля дополнительного удаления фона: оно убирает лишние пиксели и уточняет прозрачность краёв, особенно волос и мягких контуров.
Введение
Object Extractor выделяет один объект на фото по текстовому описанию и возвращает на прозрачном фоне. Обычное удаление фона оставляет всё на переднем плане, а этот эндпоинт — только названный объект.
Запрос
{
"image_url": "https://example.com/bar.jpg",
"prompt": "the woman in the cream sweater",
"refine_edges": true,
"autocrop": false
}
image_url и prompt обязательны. refine_edges добавляет проход удаления фона, очищающий оставшиеся пиксели по краям. autocrop обрезает холст по объекту вместо сохранения полного размера фото.
Результаты тестирования
В сцене бара 1536×864 запрос "the woman in the cream sweater" примерно через 17 секунд вернул только женщину в 1536×864 с чистыми краями волос и свитера. С ней сохранились бокал в руке и узкая полоска стола, на который она опиралась. С включённым autocrop запрос "the wine glass in front of the man" вернул PNG 130×307; видимый сквозь стекло фон остался внутри. Кружка в двух руках вернулась с пропусками на месте пальцев. Запрос без описания вернул фото без изменений.
Порядок работы
Извлечение объекта идёт в асинхронном режиме: создайте задачу, опрашивайте её до завершения и скачайте PNG из хранилища SpicyAPI. Каждое извлечение оплачивается по фиксированной цене, неудачные запросы — бесплатно.
Советы
- Уточняйте похожие объекты: "the taller bottle on the left" лучше, чем "the bottle".
- Оставьте
autocropвыключенным, если хотите вернуть вырезку на прежнее место. - Для всех объектов сразу проще использовать Background Remover (
/models/background-remover-v1).
Быстрый старт API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/object-extractor-v1/edit",
"input": {
"image_url": "https://example.com/reference.png",
"prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Аутентификация, полная схема, опрос статуса и обработка ошибок описаны в справочнике API.




