배경 제거 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초 이상 걸리면, 대신 작업 ID와 함께 202 Accepted를 받아요. 작업은 계속 실행되므로 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. 작업 폴링

done이 true가 될 때까지 몇 초마다 GET /v1/jobs/:id를 호출하세요. 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은 0부터 시작하는 position이에요. 위치는 잘못된 URL과 중복 URL을 제외한 목록 순서를 따르므로, 둘 중 하나라도 0보다 크면 인덱스가 아닌 input으로 결과를 매칭하세요.

• done이 true가 되면 해당 배치는 미완료 배치 한도 3개에 더 이상 포함되지 않아요.
• API에는 취소 엔드포인트, 웹훅, ZIP 다운로드가 없어요. 일괄 처리 페이지에서 시작한 배치는 그 페이지에서 취소하거나 ZIP으로 다운로드할 수 있어요.

재시도, 중복, 과금

Idempotency-Key를 보내면 재시도해도 두 번 과금되지 않아요. POST /v1/remove 또는 POST /v1/batch에 Idempotency-Key 헤더(UUID 같은 255자 이하의 고유 문자열)를 추가하세요. 키는 이미지나 배치마다 하나씩 사용해요. 같은 키로 같은 요청을 다시 보내면, 첫 요청이 만든 작업을 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를 허용해요. 그렇다고 웹 페이지에 키를 넣어도 안전한 것은 아니에요. 누구나 그 키를 읽을 수 있어요.
• 한 계정의 모든 키는 같은 크레딧 잔액을 사용해요. 계정 페이지에서 앱이나 환경마다 별도의 키를 만들면, 다른 키에 영향을 주지 않고 하나만 폐기할 수 있어요.
• 키가 유출되면 계정 페이지에서 즉시 폐기하고(바로 작동이 중지돼요) 새 키를 만드세요. 저희는 각 키의 해시만 저장하므로 키를 다시 보여 드릴 수 없어요.

문제 해결