remove.bg API 마이그레이션 가이드

1

먼저 읽어 주세요

같지 않은 네 가지.

size의 기본값은 remove.bg와 같이 preview입니다 — 다만 여기서 preview는 최대 640 px의 무료 워터마크 이미지입니다(remove.bg: 워터마크 없는 0.25 메가픽셀). size를 한 번도 지정하지 않는 연동은 워터마크가 있는 미리보기를 받게 됩니다. 워터마크 없는 결과를 받으려면 size=auto 또는 유료 등급을 넘기세요.
저희는 SDK 수준의 호환성을 주장하지 않습니다. 서드파티 클라이언트 세 개 — PyPI의 removebg 패키지, 공식 npm remove.bg 패키지, removebg-cli — 가 2026년 9월 22일 저희 테스트를 통과했지만, 릴리스마다 회귀 테스트를 하지는 않습니다. 저희가 지원하는 경로는 직접 작성한 HTTP 클라이언트입니다.
shadow_type, shadow_opacity, add_shadow, semitransparency는 허용되고 검증되지만 출력을 바꾸지 않습니다 — 차량이 아닌 피사체에 대한 remove.bg의 동작과 같습니다. 차량 전용 모델은 없습니다.
호출 한 번은 이미지 1장으로 계산되어 키의 한도인 분당 40장에 포함됩니다(remove.bg는 500장). 429는 Retry-After에 따라 처리하거나, 한도를 늘리려면 문의해 주세요.

2

마이그레이션 전후 비교

같은 요청을 두 서비스에 각각 보냈을 때.

remove.bg

1curl -X POST "https://api.remove.bg/v1.0/removebg" \2  -H "X-Api-Key: REMOVEBG_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png

PixMiller

1curl -X POST "https://api.pixmiller.com/v1.0/removebg" \2  -H "X-Api-Key: PIXMILLER_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png6# 200 OK → image bytes, written straight to out.png7# X-Credits-Charged: 1   X-Width: 1200   X-Height: 1600   X-Type: product

3

파라미터 지원 현황

파라미터	상태	설명
`image_file`	동일	Multipart 업로드. JPG / PNG / WebP, 최대 20 MB (remove.bg: 22 MB).
`image_url`	동일	공개된 이미지 URL. 저희 쪽에서 가져오며 동일하게 20 MB까지 허용합니다.
`image_file_b64`	동일	요청 본문에 담는 base64 인코딩 이미지. remove.bg와 동일합니다.
`size`	차이 있음	값과 기본값(preview), 메가픽셀 상한은 모두 동일합니다 — 다만 preview는 워터마크 없는 0.25 MP가 아니라 최대 640 px의 무료 워터마크 이미지입니다. medium / hd / 4k / full / 50MP는 각각 1 크레딧이고, auto는 크레딧이 남아 있는 동안 유료 등급을 사용합니다.
`format`	동일	auto / png / jpg / webp / zip — zip에는 remove.bg와 동일하게 color.jpg와 alpha.png가 들어 있습니다. Accept: application/json은 base64 봉투를 반환합니다. PNG 출력은 1,000만 픽셀로 제한됩니다.
`type, type_level`	차이 있음	허용됩니다. type은 저희 자체 모델에 매핑됩니다. X-Type은 person, product, animal, car, other 중 하나의 대분류를 반환하며, type_level=2와 latest도 같은 대분류를 반환합니다.
`crop, crop_margin`	동일	동일한 margin 문법과 동일한 50% / 500 px 상한으로 피사체에 맞춰 잘라냅니다.
`roi`	동일	remove.bg와 동일하게 픽셀 또는 퍼센트로 지정하는 관심 영역.
`scale, position`	동일	remove.bg와 동일한 피사체 크기(10%–100% 또는 original)와 위치.
`channels`	동일	rgba(기본값), 또는 마스크만 받으려면 alpha.
`bg_color`	동일	기본값은 투명입니다. # 유무에 관계없이 3 / 4 / 6 / 8자리 hex 또는 색상 이름을 쓸 수 있습니다.
`bg_image_file, bg_image_url`	동일	출력 영역을 덮도록 비율을 유지한 채 확대되고 가운데에 놓입니다. bg_color와 함께 쓸 수 없습니다.
`add_shadow, shadow_type, shadow_opacity`	효과 없음	remove.bg의 값 범위로 검증하지만 그림자는 전혀 그려지지 않습니다.
`semitransparency`	효과 없음	허용됩니다. 반투명 영역은 항상 자동으로 처리됩니다.

모든 파라미터는 remove.bg가 정한 값 범위로 검증하므로, 잘못된 값은 조용히 무시되지 않고 400 invalid_parameter로 응답합니다 — remove.bg의 응답과 똑같습니다.

4

동작이 다른 부분

상태 코드 remove.bg와 동일하게 이미지 바이트와 함께 200 OK — == 200을 검사하는 코드는 그대로 동작합니다. (PixMiller 자체 /api/v1/remove 엔드포인트는 201과 JSON을 반환하지만, 이 호환 경로는 의도적으로 그렇게 하지 않습니다.)

응답 본문 remove.bg와 똑같이 이미지 바이트입니다. Accept: application/json을 보내면 remove.bg의 base64 봉투 형식으로 받을 수 있고, format=zip을 쓰면 color.jpg와 alpha.png를 받습니다.

Response headers X-Credits-Charged, X-Width, X-Height, X-Type, X-Foreground-Top / -Left / -Width / -Height, X-RateLimit-Limit / -Remaining / -Reset을 모두 반환합니다. X-Type은 remove.bg의 더 세분화된 분류가 아니라 대분류(person / product / animal / car / other)입니다.

오류 오류는 remove.bg의 JSON:API 형식을 따릅니다: {"errors":[{"title":"…","code":"…"}]} — 배열이므로 errors[0].title을 예전과 똑같이 읽을 수 있습니다. 키가 없으면 403 auth_failed, 키가 틀리면 403 invalid_api_key, 잔액이 비어 있으면 402, 제한에 걸리면 429입니다.

크레딧 preview는 무료이고, 유료 등급은 이미지당 1 크레딧입니다. 결과를 가져온 뒤에만 차감되므로 실패한 호출에는 크레딧이 들지 않습니다. 월 무료 할당량은 없습니다.

요청 제한 키당 분당 40장(remove.bg: 500장). 호출 한 번은 이미지 1장으로 계산되며, X-RateLimit-Limit / -Remaining / -Reset은 이 이미지 단위 한도를 보여 줍니다. 429는 Retry-After에 따라 처리하세요.

5

잔액 확인

account 엔드포인트는 data.attributes.credits에 해당 키의 남은 크레딧 잔액을 담아 반환하므로, remove.bg 기준으로 작성한 잔액 확인 코드의 구조를 그대로 쓸 수 있습니다. 월 무료 할당량이 없으므로 free_calls는 항상 0입니다.

GET /v1.0/account

1curl "https://api.pixmiller.com/v1.0/account" \2  -H "X-Api-Key: PIXMILLER_KEY"

6

오류

400 invalid_parameter size / format / crop / scale 등의 값이 remove.bg의 허용 범위를 벗어났거나 이미지 소스가 없습니다. title에 해당 파라미터 이름이 표시됩니다.

400 file_too_large 입력 이미지가 20 MB를 초과합니다.

400 unknown_foreground 이미지에서 전경 피사체를 찾을 수 없습니다.

402 insufficient_credits 유료 등급을 요청했지만 잔액이 비어 있습니다. 크레딧은 차감되지 않습니다.

403 auth_failed / invalid_api_key X-Api-Key 헤더가 없거나(auth_failed) 잘못된 경우(invalid_api_key) — remove.bg와 같이 401이 아니라 403입니다.

429 rate_limit_exceeded 요청 제한을 초과했습니다. Retry-After 헤더에 따라 다시 시도하세요.

502 result_fetch_failed 스토리지에서 결과를 가져오지 못했습니다. 크레딧은 차감되지 않았습니다 — 요청을 다시 시도하세요.

의미는 상태 코드가 담고 있으며, code에는 remove.bg가 쓰던 값을 그대로 사용합니다 — errors[0].code로 분기하는 코드는 그대로 동작합니다.

remove.bg 대안 문의하기