의도적으로 지루한 API
최고의 이미지 API는 지루합니다. 이미지를 주면 결과를 받고, 제품 개발을 계속하면 됩니다. Remove BG는 그 기준으로 설계되었습니다.
curl 'https://api.codia.ai/v1/open/remove_bg' \
-H 'Authorization: Bearer {codia_api_key}' \
-H 'Content-Type: application/json' \
--data '{ "image_url": "https://example.com/product.jpg" }'{
"code": 0,
"message": "ok",
"data": {
"image_url": "https://processed-image-url.com/result.png"
}
}이것이 전부입니다. 하나의 endpoint. 하나의 필수 필드. 하나의 응답 형태. 이 글의 나머지는 그 표면적을 그렇게 작게 유지하기 위해 무엇을 트레이드했는지, 그리고 실제 이미징 파이프라인 내에서 API가 어떻게 동작하는지에 대한 내용입니다.
컷아웃에서 "깔끔함"이란
배경 제거 파이프라인의 안이한 버전은 썸네일 크기에서는 괜찮아 보이지만 밝은 배경이나 깔끔한 카탈로그 레이아웃에서는 무너지는 소프트 알파 채널이 있는 이미지를 반환합니다. Remove BG는 그 반대를 목표로 합니다: 고객이 제품 페이지에서 확대했을 때 견딜 수 있는 컷아웃.
구체적으로, 엣지 품질 패스는 중요한 세 가지를 수행합니다:
- 윤곽선의 서브픽셀 알파. 마스크는 임계값 처리가 아닌 매팅됩니다 — 가는 머리카락, 얇은 주얼리 와이어, 레이스, 유리 테두리가 가장 가까운 전체 픽셀에서 잘리지 않고 부드러운 엣지를 유지합니다.
- 전경의 색상 오염 제거. 엣지 근처의 픽셀은 종종 원래 배경에서 녹색 또는 빨간색 번짐을 가집니다. API는 해당 색조를 제거하여 주체가 헤일로 없이 모든 새 배경에 깔끔하게 합성됩니다.
- 그림자 번짐 없음. 원본에 흰색 표면 위의 그림자가 있으면 그림자는 배경과 함께 사라집니다. 그림자를 유지하고 싶다면(일부 이커머스 팀은 그렇게 합니다), 주체 자체의 셀프 섀도 — 신발의 그늘진 밑면, 머그의 어두운 면 — 는 그대로 유지됩니다.
실용적 테스트: 반환된 PNG를 #111 배경에 합성하세요. 밝은 프린지가 보이면 컷아웃이 깔끔하지 않은 것입니다. Remove BG는 제품, 사람, 반려동물, 음식, 가구, 차량에서 이 테스트를 통과해야 합니다. 모션 블러가 있는 피사체와 주체가 복잡한 배경과 색상 팔레트를 공유하는 이미지에서는 어려움을 겪습니다.
지연 시간 예산
공식 처리 시간은 약 600ms입니다. 이 수치는 모델의 추론 시간에 가벼운 I/O를 더한 것이며, 요청부터 반환된 URL까지의 엔드투엔드 지연 시간은 이미지 크기와 리전에 따라 800–1200ms에 가깝습니다. 배치 워크로드의 경우 API는 잘 병렬화됩니다 — 레이트 리밋이 적용되기 전에 단일 키에서 수백 건의 요청을 동시에 보낼 수 있으며, 이는 일반적으로 인터랙티브 제품 업로드 플로우에 충분합니다.
동기식 UI에 통합하는 경우 — 사용자가 이미지를 드래그하고 즉시 결과를 보고 싶어하는 경우 — 800ms는 좋은 느낌입니다. 50,000개 SKU 카탈로그를 야간에 수집하는 경우, 워커 풀을 실행하고 일시적 실패 시 재시도하며 레이트 리밋에 맞춰 동시성을 조절하세요.
API가 적합한 곳
자주 등장하는 다섯 가지 통합 패턴:
1. 이커머스 제품 업로드. 판매자가 제품 사진을 업로드하면 Remove BG를 호출하고, 투명 PNG를 원본 옆에 저장하고, 템플릿 시스템이 브랜드 배경(리스팅용 흰색, 히어로 샷용 그라데이션, 캠페인 페이지용 시즌 색상)에 합성하게 합니다. 모델을 다시 실행할 필요가 없습니다.
2. 디자인 도구 자산 파이프라인. 이미지를 캔버스에 드래그하면 배경이 사라집니다. 이것이 Figma / Canva 모델이며, 우리가 튜닝한 지연 시간 예산입니다.
3. 사진 앱. 온디바이스 모델이 점점 좋아지고 있지만 크기가 크고, 구형 하드웨어에서 느리며, 업데이트 비용이 높습니다. 앱이 이미 다른 것을 위해 네트워크 라운드트립을 하고 있다면, API 컷아웃이 종종 올바른 선택입니다 — 더 작은 바이너리, 더 나은 결과, 더 쉬운 개선.
4. 광고 크리에이티브 자동화. 제품 피드로 구동되는 가변 배경 광고 템플릿: 배경을 한 번 제거하고, N번 합성하고, N개의 크리에이티브를 출하합니다. Remove BG가 "한 번" 단계입니다.
5. AI 생성 파이프라인. 생성기가 단순한 배경에 주체를 생성하고, 두 번째 파이프라인이 장면에 합성합니다. 이 단계에서 깔끔한 알파는 사용 가능한 출력과 명백한 AI 번짐의 차이입니다.
실패 모드와 처리 방법
모든 이미지 API에는 잘 처리하지 못하는 입력이 있습니다. 주의할 것들:
- 매우 낮은 해상도 이미지(긴 변 ~400px 미만). 모델이 엣지를 매팅하려면 충분한 신호가 필요합니다; 그 이하에서는 컷아웃이 양자화되어 보입니다. 사용자 대면 제품을 만들고 있다면 호출 전에 너무 작은 이미지를 거부하세요.
- 투명한 입력. 소스에 이미 알파 채널이 있으면 모델이 투명 영역을 배경으로 해석합니다. 기존 투명도를 보존하려면 먼저 흰색에 평면화하세요.
- 극단적인 모션 블러. 레이싱 카, 액션 스포츠. 모델이 주체를 유지하지만 선명한 촬영보다 엣지가 더 부드러워집니다.
- 주체-배경 색상 충돌. 흰 시트 위의 흰 드레스; 검은 소파 위의 검은 개. 결과는 여전히 사용 가능하지만 엣지 신뢰도가 떨어집니다. 이런 경우가 사람의 검토 단계가 필요한 케이스입니다.
응답에는 code 필드가 포함됩니다. 0은 성공입니다. 0이 아닌 값(사람이 읽을 수 있는 message와 함께)은 입력 문제를 알립니다 — 접근 불가능한 URL, 지원하지 않는 형식, 너무 큰 이미지, 레이트 리밋 초과. 0이 아닌 값을 재시도(네트워크 오류) 또는 빠른 실패(입력 오류) 신호로 처리하세요.
가격 및 운영 참고 사항
공개 플랜은 성공적인 호출당 과금되며, 롤오버 크레딧으로 한 달에 사용하지 않은 볼륨이 사라지지 않습니다. 대량 사용 — 월 수천만 건의 이미지 — 의 경우 엔터프라이즈 티어는 전용 키, 커스텀 레이트 리밋, 우선 큐가 포함된 정액 커밋입니다. 무료 측에는 사이즈 티어가 없습니다: 품질은 모든 플랜에서 동일하며, 변수는 볼륨과 SLA뿐입니다.
출력 이미지는 다운로드하고 캐시할 수 있을 만큼 충분히 유효한 CDN URL에서 제공됩니다. 핫링크하지 마세요; 결과를 가져와서 자체 버킷에 저장하고 거기서 서빙하세요. URL은 요청에 한정되며 장기 유효하지 않습니다.
빠르게 시작하기
- codia.ai/dashboard/developer에서 키를 받으세요.
- 아무 제품 사진에 대해 위의
curl을 실행하세요. data.image_url을 다운로드하고, 어두운 배경에 합성한 후 엣지를 확대하세요.- 잘 보인다면 — 그래야 하고 — 업로드 후 단계로 파이프라인에 연결하세요.
전체 레퍼런스, 에러 코드, 볼륨 가격은 /api#remove-background에 있습니다.
목표는 지루한 API였습니다. 하나의 endpoint, 빠르고 깔끔한 컷아웃, 부하에서 안정적. 연결한 후에 그것에 대해 생각할 필요가 없다면, 그것이 승리입니다.