API로 이미지 배경 제거하는 방법: 누끼 따기를 자동화하기

사진 한 장의 배경을 손으로 지우는 데는 몇 분이 걸립니다. 앱에 올라오는 모든 상품 이미지, 프로필 사진, 썸네일에 같은 작업을 하려면 배경 제거 API가 필요합니다. HTTP 요청 하나를 보내면 누끼가 완성된 이미지가 돌아옵니다.

이 가이드는 배경 제거 API를 제대로 연동하는 방법을 보여 줍니다. 바로 실행되는 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 키, 쿼리 문자열 값 중 어느 것으로도 보낼 수 있습니다.

주의할 점이 하나 있습니다. -o는 상태와 상관없이 본문을 저장합니다. 키가 틀렸거나 이미지가 잘못되었다면, 저장된 "PNG"는 사실 JSON 오류입니다. 파일을 믿기 전에 상태 코드를 확인하세요.

3단계: Python으로 200, 202, 오류 처리하기

배경 제거 API는 모든 이미지가 한 번의 HTTP 요청 안에 끝난다고 보장할 수 없습니다. 큐가 유난히 붐비고 이미지 처리에 약 55초 이상 걸리면, removebackground.dev는 이미지 대신 작업 ID와 함께 202 Accepted로 응답합니다. 작업은 계속 실행되며, 그 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의 각 항목에는 고유한 상태가 있고, 실패하면 오류 코드가 붙습니다.
• http(s) URL이 아닌 항목과 중복된 URL은 제외되며 요금이 부과되지 않습니다. 둘 중 하나라도 0보다 크면 위치가 아닌 input으로 결과를 매칭하세요.
• 계정당 동시에 열어 둘 수 있는 배치 작업은 최대 3개입니다. done이 true가 되면 해당 배치는 더 이상 집계되지 않습니다.
• 배치 도중 크레딧이 바닥나면, 완료된 이미지는 그대로 차감되고 나머지는 out_of_credits와 함께 skipped로 표시되며 요금이 부과되지 않습니다.
• API에는 취소 엔드포인트, 웹훅, ZIP 다운로드가 없으므로 폴링이 기본 패턴입니다. 작업 조회는 무료이며 요청 한도도 적용되지 않습니다.

바로 실행할 수 있는 스크립트가 필요하다면 Python 일괄 처리 가이드에서 폴더에서 폴더로 이어지는 전체 워크플로를 설명합니다.

6단계: 안전하게 재시도하고 요금을 예측 가능하게 유지하기

이중 결제는 네트워크 타임아웃에서 생깁니다. 클라이언트가 포기하고 재시도하면 이미지 한 장에 작업이 두 개 생깁니다. 해결책은 Idempotency-Key 헤더입니다. UUID처럼 255자 이하의 고유한 문자열을 이미지나 배치마다 하나씩 사용합니다. 같은 키로 같은 요청을 다시 보내면 첫 요청이 만든 작업이 Idempotent-Replayed: true 헤더와 함께 반환되고, 새로운 요금은 부과되지 않습니다. 다른 이미지에 같은 키를 재사용하면 409 idempotency_key_reused로 응답합니다.

요금 규칙은 간단합니다. 이미지가 성공하면 1크레딧, 실패하면 무료입니다. 처리 전에 거부된 요청, 읽을 수 없는 이미지, 제공업체 자체 재시도 후의 실패는 무료이며, 완료된 결과는 보관 중인 동안 다시 다운로드해도 무료입니다.

설계 시 고려할 제한

분당 60장 이상을 처리해야 한다면 batch 엔드포인트를 쓰면 됩니다. 요청 하나로 최대 100장을 처리할 수 있습니다. 결과는 다운로드하는 즉시 자체 버킷에 저장하세요. 48시간이 지나면 결과 링크가 410으로 응답합니다. 제공업체 문서에 따르면 업로드된 이미지는 모델 학습에 사용되지 않습니다.

remove.bg API에서 마이그레이션하기

remove.bg의 단독 웹사이트와 셀프 서비스 API는 2026년 12월 1일 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는 16:9 비율의 3840 x 2160 px, 최소 너비 640 px를 권장하며, 컴퓨터에서는 최대 50 MB의 JPG 또는 PNG를 받지만 모바일 앱에서는 2 MB까지만 받습니다.

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는 https://removebackground.dev/mcp에서 MCP 서버도 운영하므로, ChatGPT, Claude, Cursor, VS Code, n8n에서 사진을 올리고 배경 제거를 요청할 수 있습니다. Claude Code에서는 명령어 하나면 됩니다:

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

그런 다음 Claude Code에서 /mcp를 입력해 로그인하세요. 서버는 세 가지 도구를 제공합니다: remove_background, 몇 초 이상 걸리는 작업을 위한 get_job, 그리고 check_credits입니다. 이미지 1장당 API와 같은 1크레딧이 듭니다.

비용

removebackground.dev는 구독 없는 종량제입니다. 크레딧은 만료되지 않고, 실패한 이미지는 무료이며, 신규 계정에는 무료 크레딧 50개가 제공됩니다. API에서 1크레딧은 원본 해상도 배경 제거 1회 성공에 해당합니다.

가격은 USD 기준이며, 사용하지 않은 크레딧은 30일 이내에 환불받을 수 있습니다. Scale을 넘는 대량 요금은 요청 시 제공됩니다. 최신 정보는 요금 페이지를 확인하세요.

마무리

탄탄한 배경 제거 연동은 몇 가지 습관으로 정리됩니다. 키는 서버에 두고, 본문을 저장하기 전에 상태를 확인하고, 202를 받으면 다시 보내지 말고 작업을 기다리고, 모든 POST에 Idempotency-Key를 보내고, 대량 작업에는 batch 엔드포인트를 사용하세요.

OpenAPI 3.1 명세를 포함한 전체 레퍼런스는 API 문서에 있습니다. 이미지뿐 아니라 영상도 다룬다면, YouTube 자막 추출 API 비교와 음성 인식 API 연동 가이드에서 텍스트에 같은 실서비스 패턴을 적용한 내용을 볼 수 있습니다.