API удаления фона: один запрос на входе, готовый PNG на выходе.

Отправка изображения

POST /v1/remove принимает изображение четырьмя способами. Используйте один из них; если в запросе их несколько, приоритет у image_file, затем image_file_b64, затем image_url, затем необработанное тело запроса. Эти примеры берут ключ из переменной окружения REMOVEBG_API_KEY (задайте её через export REMOVEBG_API_KEY=…); обратите внимание на двойные кавычки — благодаря им оболочка подставляет значение.

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

Каждый пример сохраняет тело ответа в файл. Этот файл является изображением, только если статус 200; см. Обработка ответа.

Обработка ответа

Большинство одиночных изображений возвращаются готовыми в том же ответе. Если очередь необычно загружена и обработка занимает дольше примерно 55 секунд, вместо этого вы получите 202 Accepted с id задачи. Задача продолжает выполняться: заберите результат по id. Повторная отправка изображения запустит вторую задачу и может стоить ещё один кредит.

Полный пример

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

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: resending with the same key returns the same job, never a second
    # charge, so this POST is safe to retry after a timeout or a dropped connection.
    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 = the image; anything else raises

    # 202: still processing. Wait for the same job; never send the image again.
    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 it later at /v1/jobs/{job_id}.")


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

• Остановка скрипта не останавливает задачу; она может завершиться, и кредит будет списан. Результат появится в вашей Студии.
• Лимиты времени выбираете вы, это не наше обещание; большинство изображений готовы за несколько секунд.
• Эндпоинт, совместимый с remove.bg, ведёт себя иначе: он никогда не отвечает 202 (см. ниже).

Пакеты от начала до конца

1. Отправка

curl -X POST https://removebackground.dev/v1/batch \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "image_urls": ["https://example.com/front.jpg", "https://example.com/back.jpg"], "format": "png", "size": "hd" }'

До 100 публичных URL изображений плюс любые параметры /v1/remove. Два URL-заглушки выше стоили бы до 2 кредитов, будь они настоящими изображениями. Ответ приходит сразу:

202 Accepted
{
  "id": "3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77",
  "status": "queued",
  "total": 2,
  "invalid": 0,
  "duplicates": 0,
  "status_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77"
}

invalid считает записи, которые не являются http(s)-URL, а duplicates — повторы; и те и другие отбрасываются и не оплачиваются. Сохраните id: по нему можно вернуться к задаче после перезапуска.

2. Опрос задачи

Вызывайте GET /v1/jobs/:id каждые несколько секунд, пока done не станет true. status меняется с queued на processing и завершается как succeeded, partial (часть изображений не обработана) или failed. Элемент, который обрабатывается повторно, показывает retrying.

{
  "id": "3f6c2a9e-…",
  "status": "partial",
  "done": true,
  "total": 2, "succeeded": 1, "failed": 1, "skipped": 0,
  "credits_charged": 1,
  "items": [
    { "position": 0, "input": "https://example.com/front.jpg", "status": "succeeded",
      "removal_id": "…", "width": 1600, "height": 1200, "format": "png",
      "result_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-…/result?item=0" },
    { "position": 1, "input": "https://example.com/back.jpg", "status": "failed",
      "error": { "code": "fetch_failed", "message": "…" } }
  ]
}

3. Скачивание результатов

GET /v1/jobs/:id/result?item=N для каждого успешного элемента (или используйте его result_url). item — это position, считая с нуля. Позиции идут по вашему списку после удаления неверных и повторяющихся URL, поэтому если любой из счётчиков больше 0, сопоставляйте результаты по input, а не по индексу.

• Пакет перестаёт учитываться в лимите 3 открытых пакетов, как только done становится true.
• В API нет эндпоинта отмены, вебхуков и скачивания в ZIP. Пакеты, запущенные на странице пакетной обработки, можно там же отменить или скачать в ZIP.

Повторы, дубликаты и оплата

Передавайте Idempotency-Key — и повторы не спишут кредиты дважды. Добавьте заголовок Idempotency-Key (любая уникальная строка длиной до 255 символов, например UUID) к POST /v1/remove или POST /v1/batch — один ключ на изображение или пакет. Если вы снова отправите тот же запрос с тем же ключом, то получите задачу, созданную первым запросом, с Idempotent-Replayed: true: без новой задачи и без нового списания, даже если первый запрос ещё выполняется. Тот же ключ с другим изображением или параметрами вернёт 409 idempotency_key_reused. Ключи привязаны к вашему аккаунту и не истекают.

Без ключа каждый POST создаёт новую задачу, и каждая успешная задача стоит 1 кредит (у совместимого с remove.bg POST /v1.0/removebg ключей нет). Чтение задачи (GET /v1/jobs/…) всегда бесплатно и безопасно для повторов.

IDEMPOTENCY_KEY=$(uuidgen)   # one per image; send the same one on every retry

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

За что списывается кредит

Когда повторять запрос

Лимиты и хранение

Сколько хранятся результаты

Каждый результат хранится приватно в вашем аккаунте 48 ч после создания, затем удаляется. До этого его можно бесплатно скачать снова через GET /v1/jobs/:id/result или в Студии. После этого ссылки на результат отвечают 410 result_unavailable; повторная обработка изображения — это новая задача. Записи о статусе задач остаются доступными и после удаления изображения. Как обрабатываются загрузки, см. в политике конфиденциальности; мы не используем ваши изображения для обучения моделей.

Безопасность

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

• API поддерживает CORS, чтобы работать из инструментов и серверного кода. Но это не делает размещение ключа на веб-странице безопасным: там его может прочитать кто угодно.
• Все ключи одного аккаунта тратят общий баланс кредитов. Создавайте отдельный ключ для каждого приложения или окружения на странице аккаунта, чтобы можно было отозвать один, не затронув остальные.
• Если ключ утёк, сразу отзовите его на странице аккаунта (он мгновенно перестанет работать) и создайте новый. Мы храним только хеш каждого ключа, поэтому не можем показать его вам снова.

Решение проблем