Как удалить фон с изображения через API

Удалить фон вручную занимает несколько минут на одно фото. Чтобы делать это для каждого загруженного товара, аватарки или превью в вашем приложении, нужен API для удаления фона: на входе один HTTP-запрос, на выходе готовое вырезанное изображение.

В этом руководстве показано, как правильно его интегрировать. Вы получите рабочий код на cURL, Python и JavaScript, узнаете о полезных параметрах вывода, о том, как обрабатывать медленные изображения и массовые задачи и как повторять запросы, не платя дважды. В примерах используется removebackground.dev, наш родственный продукт, но подходы применимы к любому провайдеру.

Как работает API для удаления фона

Вы отправляете изображение, провайдер запускает модель сегментации, которая отделяет объект от фона, и вы получаете новое изображение. Основа результата это альфа-канал: значение для каждого пикселя, которое показывает, насколько этот пиксель относится к объекту. Полностью непрозрачные пиксели это объект, полностью прозрачные это фон, а промежуточные значения отвечают за мягкие края, такие как волосы, шерсть и стекло.

На основе этой маски API может вернуть несколько вариантов:

• Прозрачный вырез, обычно PNG или WebP без фона
• Объект на сплошном цвете, сведённый в JPG для маркетплейсов, которые требуют белый фон
• Саму маску, изображение в оттенках серого для вашего собственного конвейера композитинга
• Обрезанную или уменьшенную версию, подогнанную под объект и под точный размер

Запрос это простая часть. Интеграция в продакшене должна также справляться с изображениями, которые обрабатываются дольше обычного, большими пакетами, лимитами запросов, повторами и защитой API-ключа от пользователей.

На что смотреть при выборе API для удаления фона

Прежде чем писать код, проверьте эти пункты на своих изображениях и своём трафике.

Шаг 1: Создайте API-ключ

Зарегистрируйтесь на removebackground.dev и создайте ключ на странице аккаунта. Новые аккаунты получают 50 бесплатных кредитов, этого хватит, чтобы запустить примеры ниже и проверить сервис на своих изображениях.

Сохраните ключ в переменной окружения на сервере:

export REMOVEBG_API_KEY="your_api_key"

Каждый вызов передаёт ключ в заголовке x-api-key, и каждый вызов расходует кредиты этого аккаунта. Создавайте отдельный ключ для каждого приложения или окружения, чтобы можно было отозвать один, не ломая остальные.

Шаг 2: Удалите фон с помощью cURL

Эндпоинт для обработки в реальном времени: POST https://removebackground.dev/v1/remove. Самый быстрый тест это загрузка файла:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' \
  -o photo-no-bg.png

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

Эндпоинт принимает изображение четырьмя способами. Отправьте один из них:

Если в запросе несколько вариантов, приоритет у image_file, затем image_file_b64, затем image_url, затем сырое тело. Параметры можно передавать как поля формы, ключи JSON или значения query string.

На что обратить внимание: -o сохраняет тело ответа независимо от статуса. Если ключ неверный или изображение некорректное, ваш "PNG" на самом деле окажется ошибкой в JSON. Проверяйте код статуса, прежде чем доверять файлу.

Шаг 3: Обработка 200, 202 и ошибок на Python

API для удаления фона не может гарантировать, что каждое изображение будет готово в рамках одного HTTP-запроса. Когда очередь необычно загружена и обработка изображения занимает больше примерно 55 секунд, removebackground.dev отвечает 202 Accepted с ID задачи вместо изображения. Задача продолжает выполняться, а результат вы получаете по ID.

Главное правило: никогда не отправляйте изображение повторно после 202. Это запустит вторую задачу и может стоить второго кредита. Вот полная версия на Python, которая отправляет изображение один раз и повторяет только безопасные вызовы:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
KEY = os.environ["REMOVEBG_API_KEY"]  # keep the key on your server
EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}


def save(res, stem):
    """Save an image response with the right extension; raise on anything else."""
    mime = res.headers.get("Content-Type", "").split(";")[0]
    if res.status_code != 200 or mime not in EXT:
        raise RuntimeError(f"HTTP {res.status_code}: {res.text[:500]}")
    path = stem + EXT[mime]
    with open(path, "wb") as f:
        f.write(res.content)
    return path


def remove_background(image_url, stem="result", max_wait=300):
    s = requests.Session()
    s.headers["x-api-key"] = KEY
    # One key per image: a retry with the same key returns the same job, never a second charge.
    idem = {"Idempotency-Key": str(uuid.uuid4())}

    for attempt in range(3):
        try:
            res = s.post(f"{API}/v1/remove", data={"image_url": image_url},
                         headers=idem, timeout=(10, 120))
            break
        except requests.ConnectionError:
            if attempt == 2:
                raise
            time.sleep(2)

    if res.status_code != 202:
        return save(res, stem)  # 200 is the image; anything else raises

    # 202: still processing. Wait for the same job.
    job_id = res.json()["id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(2)  # the API sends Retry-After: 2
        res = s.get(f"{API}/v1/jobs/{job_id}/result", timeout=30)
        if res.status_code == 409 and res.json()["error"]["code"] == "not_ready":
            continue
        return save(res, stem)  # the image, or the job's own error
    raise TimeoutError(f"Job {job_id} is still running. Check /v1/jobs/{job_id} later.")


print(remove_background("https://example.com/photo.jpg"))

Нужны Python 3 и requests (pip install requests). Две детали легко упустить. Во-первых, остановка скрипта не останавливает задачу: она всё равно может завершиться и будет оплачена, а результат появится в Studio вашего аккаунта. Во-вторых, GET /v1/jobs/:id/result отвечает 409 not_ready, пока задача выполняется, так что считайте это сигналом "подождать", а не ошибкой.

Тот же процесс на JavaScript (Node.js)

Тот же процесс на Node.js 18 или новее, со встроенными fetch, FormData и Blob и загрузкой локального файла:

import { readFile, writeFile } from "node:fs/promises"
import { randomUUID } from "node:crypto"

const API = "https://removebackground.dev"
const KEY = process.env.REMOVEBG_API_KEY // server side only
const EXT = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp" }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function save(res, stem) {
  const mime = (res.headers.get("content-type") || "").split(";")[0]
  if (res.status !== 200 || !EXT[mime]) {
    throw new Error("HTTP " + res.status + ": " + (await res.text()).slice(0, 500))
  }
  const path = stem + EXT[mime]
  await writeFile(path, Buffer.from(await res.arrayBuffer()))
  return path
}

export async function removeBackground(filePath, stem = "result", maxWaitMs = 300000) {
  const form = new FormData()
  form.append("image_file", new Blob([await readFile(filePath)]), "upload")
  form.append("format", "png")

  const res = await fetch(API + "/v1/remove", {
    method: "POST",
    // Reuse the same Idempotency-Key if you retry this POST.
    headers: { "x-api-key": KEY, "Idempotency-Key": randomUUID() },
    body: form,
  })
  if (res.status !== 202) return save(res, stem)

  const { id } = await res.json()
  const deadline = Date.now() + maxWaitMs
  while (Date.now() < deadline) {
    await sleep(2000)
    const result = await fetch(API + "/v1/jobs/" + id + "/result", {
      headers: { "x-api-key": KEY },
    })
    if (result.status === 409) {
      const body = await result.json()
      if (body.error && body.error.code === "not_ready") continue
      throw new Error("Job " + id + ": " + body.error.code)
    }
    return save(result, stem)
  }
  throw new Error("Job " + id + " is still running. Check /v1/jobs/" + id + " later.")
}

console.log(await removeBackground("photo.jpg"))

API принимает CORS-запросы, что удобно для инструментов и тестирования. Но это не делает безопасным вызов с веб-страницы, где лежит ваш ключ. Подробнее об этом в разделе о безопасности ниже.

Шаг 4: Управление выводом

Большинству приложений не нужен сырой вырез в полном разрешении. Им нужно квадратное фото товара на белом фоне, маленькое превью или маска. Если сразу запросить у API итоговый файл, второй этап обработки не понадобится. Вот параметры /v1/remove:

Каждый параметр стоит тот же 1 кредит, а неизвестные параметры молча игнорируются, так что опечатка не вызовет ошибку. Квадратное изображение для маркетплейса с товаром по центру и отступом 10% выглядит так:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@product.jpg' \
  -F 'crop=1:1' -F 'padding=10%' \
  -F 'width=1000' -F 'height=1000' \
  -F 'format=jpg' -F 'bg_color=white' \
  -o product-square.jpg

Успешный ответ также содержит полезные заголовки. X-Credits-Remaining показывает баланс после обработки изображения. X-Matte-Confidence (от 0 до 1) показывает, насколько уверенно построена маска, а X-Matte-Ambiguous-Ratio даёт долю мягких пикселей, таких как волосы, стекло или смаз от движения. Если логировать эти два значения, можно отправлять вырезы с низкой уверенностью на ручную проверку, а не проверять каждое изображение.

Шаг 5: Пакетная обработка изображений

Для импорта каталогов и повторной обработки не отправляйте сотни отдельных запросов. POST /v1/batch ставит в очередь до 100 публичных URL изображений как одну задачу, с теми же параметрами, что и /v1/remove, и сразу отвечает 202:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
s = requests.Session()
s.headers["x-api-key"] = os.environ["REMOVEBG_API_KEY"]

urls = ["https://example.com/front.jpg", "https://example.com/back.jpg"]

job = s.post(f"{API}/v1/batch",
             json={"image_urls": urls, "format": "png", "size": "hd"},
             headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
job.raise_for_status()
job_id = job.json()["id"]  # save it: it's how you resume after a restart

while True:
    time.sleep(3)
    status = s.get(f"{API}/v1/jobs/{job_id}", timeout=30).json()
    if status["done"]:
        break

print(status["status"], "credits charged:", status["credits_charged"])
for item in status["items"]:
    if item["status"] != "succeeded":
        print("failed:", item["input"], item.get("error"))
        continue
    img = s.get(item["result_url"], timeout=60)
    with open(f"out-{item['position']}.{item['format']}", "wb") as f:
        f.write(img.content)

Несколько правил из документации, которые стоит учесть:

• Статус задачи в итоге становится succeeded, partial (часть изображений не обработана) или failed. У каждого элемента в items свой статус, а при сбое код ошибки.
• Записи, которые не являются URL http(s), и повторяющиеся URL отбрасываются и не оплачиваются. Если какое-то из этих чисел больше 0, сопоставляйте результаты по input, а не по позиции.
• На аккаунт может быть открыто не более 3 пакетных задач. Пакет перестаёт учитываться, когда done равно true.
• Если кредиты закончились посреди пакета, готовые изображения остаются оплаченными, а остальные помечаются как пропущенные с out_of_credits, бесплатно.
• В API нет эндпоинта отмены, вебхуков и скачивания ZIP, поэтому рабочий подход это опрос. Чтение задачи бесплатно и не ограничено лимитом запросов.

Нужен готовый скрипт, который можно запустить как есть? В руководстве по пакетной обработке на Python разобран полный процесс из папки в папку.

Шаг 6: Безопасные повторы и предсказуемая оплата

Сетевые таймауты это источник двойных списаний. Ваш клиент не дождался ответа, повторил запрос, и теперь на одно изображение есть две задачи. Решение это заголовок Idempotency-Key: любая уникальная строка длиной до 255 символов, например UUID, по одной на изображение или пакет. Если вы снова отправите тот же запрос с тем же ключом, вы получите задачу, созданную первым запросом, с заголовком Idempotent-Replayed: true, и без нового списания. Повторное использование ключа для другого изображения вернёт 409 idempotency_key_reused.

Оплата подчиняется простому правилу: 1 кредит, если изображение обработано успешно, и ничего, если нет. Запросы, отклонённые до обработки, нечитаемые изображения и сбои после собственных повторов провайдера бесплатны, а повторное скачивание готового результата бесплатно, пока он хранится.

Лимиты, которые нужно учесть

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

Переход с API remove.bg

Отдельный сайт и API самообслуживания remove.bg прекращают работу 1 декабря 2026 года в 09:00 CET. Его API переходит к Leonardo.Ai, и для этого придётся менять интеграцию. Если не хотите ничего переписывать, у removebackground.dev есть эндпоинт, совместимый с remove.bg, и переход занимает одну строку:

Вы сохраняете тот же заголовок X-Api-Key (с ключом removebackground.dev), те же названия параметров, те же заголовки ответа и тот же формат ошибок:

curl -H "X-Api-Key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' -F 'size=auto' \
  -F 'crop=true' -F 'crop_margin=10%' -F 'bg_color=ffffff' \
  -o no-bg.jpg https://removebackground.dev/v1.0/removebg

Знайте различия, прежде чем переключаться:

• Нет 202. Совместимый эндпоинт ждёт до 110 секунд, затем возвращает таймаут 503. Задача продолжает выполняться и оплачивается в случае успеха, поэтому слепой повтор такого запроса запустит вторую задачу.
• Нет ключей идемпотентности на этом эндпоинте. Если нужны безопасные повторы, со временем переходите на /v1/remove.
• Некоторые параметры принимаются, но игнорируются: type и type_level (объект определяется автоматически), semitransparency и параметры теней (тени не добавляются).
• Любой размер стоит 1 кредит, включая полное разрешение.

В руководстве по миграции есть код до и после для cURL, Python, Node и PHP, а также шаги для Zapier, Make и n8n.

Не храните API-ключ на клиенте

Эта ошибка стоит реальных денег. Если ваш ключ находится в веб-странице, мобильном приложении, публичном репозитории или URL, любой может его прочитать и потратить ваши кредиты.

• Чтобы ваши пользователи могли удалять фон, передавайте их изображения через свой бэкенд и вызывайте API оттуда.
• Добавьте в этом бэкенде собственную авторизацию и лимиты расходов для каждого пользователя.
• Используйте отдельный ключ для каждого приложения или окружения.
• Если ключ утёк, отзовите его на странице аккаунта. Он сразу перестанет работать. Провайдер хранит только хеш каждого ключа, поэтому создайте новый, а не пытайтесь восстановить старый.

Пример: вырезы для превью на YouTube

Если вы делаете инструменты для авторов, превью очевидный сценарий. Превью чаще всего видят в маленьком размере, поэтому вырез должен на нём читаться: одно лицо или товар, крупно, с чётким краем на простом фоне. YouTube рекомендует 3840 x 2160 px в формате 16:9 с минимальной шириной 640 px и принимает JPG или PNG до 50 МБ с компьютера, но только до 2 МБ из мобильного приложения.

Со стороны API это один вызов, который возвращает прозрачный PNG, обрезанный по объекту и готовый для холста 16:9:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@me.jpg' \
  -F 'crop=true' -F 'padding=5%' \
  -o me-cutout.png

Для выреза снимайте отдельное фото, а не берите кадр из видео, ведь кадры часто смазаны движением, и оставляйте правый нижний угол свободным, потому что там YouTube показывает длительность видео. На странице о превью для YouTube разобрана дизайнерская часть, а наше руководство о том, как набрать первые 1 000 подписчиков, объясняет, почему превью так важны.

Удаление фона из ChatGPT, Claude или Cursor

Не для каждой задачи нужен код. У removebackground.dev также есть MCP-сервер по адресу https://removebackground.dev/mcp, так что можно загрузить фото в ChatGPT, Claude, Cursor, VS Code или n8n и попросить удалить фон. В Claude Code это одна команда:

claude mcp add --transport http removebackground https://removebackground.dev/mcp

Затем введите /mcp в Claude Code, чтобы войти. Сервер предоставляет три инструмента: remove_background, get_job для удалений, которые занимают больше нескольких секунд, и check_credits. Каждое изображение стоит 1 кредит, как и через API.

Сколько это стоит

removebackground.dev работает по модели оплаты по факту, без подписки. Кредиты не сгорают, неудачные изображения бесплатны, а новые аккаунты получают 50 бесплатных кредитов. Через API 1 кредит равен одному успешному удалению фона в полном разрешении.

Цены указаны в USD, неиспользованные кредиты можно вернуть в течение 30 дней. Цены для объёмов больше Scale доступны по запросу. Актуальные условия смотрите на странице с ценами.

Итоги

Надёжная интеграция удаления фона сводится к нескольким привычкам: храните ключ на сервере, проверяйте статус перед сохранением тела ответа, дожидайтесь задачи вместо повторной отправки после 202, отправляйте Idempotency-Key с каждым POST и используйте пакетный эндпоинт для массовой обработки.

Полный справочник, включая спецификацию OpenAPI 3.1, находится в документации API. Если вы работаете не только с изображениями, но и с видео, наше сравнение API для расшифровки YouTube и руководство по интеграции распознавания речи используют те же продакшен-подходы для текста.