배경 제거 API 레퍼런스

요청 파라미터, 응답 형식과 remove.bg API와의 차이를 확인하세요. 파일, URL, Base64 입력 예제와 각 방식의 제한 사항을 살펴볼 수 있습니다.

POST https://removebgtool.net/v1.0/removebg

curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'image_file=@image.jpg' \
  -F 'size=auto' \
  'https://removebgtool.net/v1.0/removebg' -o no-bg.png

요청

X-API-Key를 보내세요. image_file은 multipart/form-data를, image_url 또는 image_file_b64는 JSON이나 URL 인코딩 본문을 사용합니다. 이미지 소스는 하나만 지정하세요. 기본값은 crop=false, format=auto이며 투명은 PNG, 불투명은 JPG입니다. bg_color는 CSS 색상명 또는 3/4/6/8자리 16진수를 받습니다. JPG는 투명 영역을 흰색으로 합성합니다.

curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'image_url=https://example.com/photo.jpg' \
  -F 'format=png' \
  'https://removebgtool.net/v1.0/removebg' -o result.png

# JSON input and JSON output
curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{"image_file_b64":"YOUR_PADDED_BASE64","format":"png"}' \
  'https://removebgtool.net/v1.0/removebg'

import requests

with open('image.jpg', 'rb') as image:
    response = requests.post(
        'https://removebgtool.net/v1.0/removebg',
        headers={'X-API-Key': 'YOUR_API_KEY'},
        files={'image_file': image},
        data={'size': 'auto'},
        timeout=180,
    )
response.raise_for_status()
with open('no-bg.png', 'wb') as output:
    output.write(response.content)

import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('image_file', new Blob([await readFile('image.jpg')]), 'image.jpg');
form.append('size', 'auto');
const response = await fetch('https://removebgtool.net/v1.0/removebg', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: form,
  signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(await response.text());
await writeFile('no-bg.png', Buffer.from(await response.arrayBuffer()));

응답

HTTP 200은 이미지 바이트를 반환합니다. Accept: application/json은 data.result_b64와 크기를 반환합니다. 헤더는 X-Width, X-Height, X-Credits-Charged, X-Foreground-Top/Left/Width/Height, X-Request-ID입니다. 전경 좌표는 정규화된 입력 캔버스 기준이며 분류와 X-Type은 제공하지 않습니다. GET /v1.0/account는 data.attributes.credits와 api.free_calls(0)을 반환합니다.

{
  "data": {
    "result_b64": "...",
    "result_width": 625,
    "result_height": 400,
    "credits_charged": 1
  }
}

제한 사항과 차이점

입력은 22 MB 이하, 50 MP 이하, 각 변 33~9999픽셀의 단일 프레임 JPG/PNG/WebP입니다. HTTPS URL은 공개 직접 링크이며 443 포트를 사용해야 하고 리디렉션과 사설망은 거부됩니다. size 기본값은 preview(0.25 MP), medium=1.5 MP, hd=4 MP, full/4k/auto=25 MP, 50MP=50 MP입니다. PNG와 auto는 10 MP로 제한되며 확대하지 않습니다. remove.bg와 달리 auto는 잔액에 따라 크기를 정하지 않습니다.

API 호출은 기존 계정 크레딧을 사용합니다. 현재 이미지당 차감량은 대시보드와 X-Credits-Charged에 표시됩니다. 미리보기와 전체 해상도 비용은 같으며 별도의 월간 무료 API 한도는 제공하지 않습니다.

오류와 재시도

400 입력·매개변수 오류, 402 크레딧 부족, 403 키·요금제 오류, 409 멱등성 충돌·처리 중·만료, 415 미지원 인코딩, 429 호출 제한, 502/503 상위 서비스 오류·혼잡, 504 시간 초과입니다. 429/503의 Retry-After를 따르고 일시적 5xx에는 지수 백오프를 사용하세요. 키는 서버에 보관하세요.

{
  "errors": [
    {
      "title": "Insufficient credits.",
      "code": "insufficient_credits"
    }
  ]
}

Idempotency-Key는 선택 사항입니다. 같은 키·이미지·매개변수로 성공 결과를 10분간 추가 차감 없이 다시 받을 수 있습니다. 재응답은 기존 X-Credits-Charged와 X-Idempotent-Replayed: true를 반환합니다. 처리 중이면 409입니다. 실패·만료 키도 예약 상태로 남으므로 새 과금 요청은 새 키로 보내세요. 헤더가 없으면 각 요청은 별개입니다. 클라이언트 시간 제한은 180초로 설정하세요.

마이그레이션 체크리스트

1. API 지원 요금제에서 키를 만드세요. 2. /v1.0/removebg를 유지하고 도메인을 바꾸세요. 3. 입력 제한과 미지원 매개변수를 확인하세요. 4. 이미지·오류 처리·과금을 시험하세요. 5. 운영 환경을 전환하세요. remove.bg와 독립된 서비스입니다.이전 가이드 보기 →

인터페이스가 호환되어도 AI 결과가 같다는 뜻은 아닙니다. 이전 전에 실제 이미지로 테스트하세요.