Remove BG

개요

Remove BG는 모든 이미지에서 배경을 제거하고 투명 PNG를 반환합니다. 하나의 endpoint, 하나의 필수 필드, 하나의 응답 형태. 제품 페이지, 디자인 도구, 광고 크리에이티브 파이프라인, 대규모로 깔끔한 컷아웃이 필요한 모든 워크플로우를 위해 설계되었습니다.

Endpoint

POSThttps://api.codia.ai/v1/open/remove_bg

인증은 bearer 토큰으로 수행합니다. codia.ai/dashboard/developer에서 키를 받으세요.

요청

필드	타입	필수	설명
`image_url`	string	예	공개적으로 접근 가능한 소스 이미지 URL.

예시

bash

curl 'https://api.codia.ai/v1/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{
    "image_url": "your image url"
  }'

응답

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "image_url": "https://processed-image-url.com/result.png"
  }
}

필드	설명
`code`	성공 시 `0`. 0이 아닌 값은 입력 또는 처리 오류를 나타냅니다.
`message`	사람이 읽을 수 있는 상태 메시지.
`data.image_url`	투명 배경이 적용된 결과 PNG의 CDN URL. 다운로드하여 자체 저장소에 보관하세요; URL은 장기 유효하지 않습니다.

출력 특성

형식 — 알파 채널이 포함된 PNG.
해상도 — 플랜의 최대값까지 입력과 동일(모든 티어에서 HD).
엣지 품질 — 서브픽셀 매팅, 전경 색상 오염 제거, 배경 그림자 번짐 없음.
주체의 셀프 섀도 — 유지됩니다(예: 머그의 그늘진 밑면).

성능

설정	값
일반적인 처리 시간	~600 ms
엔드투엔드 지연 시간	800 – 1200 ms
동시성	플랜에 따라 다름; 일반적인 플랜은 수백 건의 병렬 요청 지원

지원되는 입력

입력	권장 사항
일반 형식	JPEG, PNG, WEBP
최소 해상도	긴 변 400 px
최대 크기	플랜에 따라 다름; 기본값 25 MB
기존 알파가 있는 이미지	의도한 투명도를 보존하려면 호출 전에 흰색으로 평면화
극단적인 모션 블러	작동하지만 엣지가 부드러워짐
주체/배경 색상 충돌 (예: 흰색 위의 흰색)	사용 가능하지만 사람의 검토 고려

에러 코드

`code`	의미
`0`	성공.
`40001`	`image_url` 누락 또는 접근 불가.
`40002`	지원하지 않는 형식.
`40003`	이미지가 크기 제한 초과.
`42900`	레이트 리밋 초과 — 대기 후 재시도.
`50000`	일시적 서버 오류 — 백오프 후 재시도.

0이 아닌 code는 항상 분기 신호로 처리하세요: 일시적 오류에는 재시도, 입력 오류에는 빠른 실패.

통합 패턴

제품 업로드 (동기식)

const res = await fetch('https://api.codia.ai/v1/open/remove_bg', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${CODIA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image_url: sourceUrl }),
}).then((r) => r.json())

if (res.code === 0) {
  await saveToBucket(res.data.image_url)
}

배치 수집 (비동기식)

대규모 카탈로그의 경우 플랜의 동시성 제한에서 워커 풀을 실행하고 일시적 실패를 재시도하세요. 최소 해상도 미만의 이미지는 호출을 낭비하지 않도록 건너뛰세요.

합성

개발 중에 반환된 PNG를 어두운 배경(예: #111)에 합성하여 엣지 프린징을 확인하세요. 깔끔한 컷아웃은 견딥니다; 헤일로가 보이면 입력을 검사하세요.

FAQ

URL 대신 업로드할 수 있나요?

현재 endpoint는 URL이 필요합니다. 멀티파트 업로드가 필요하면 [email protected]로 연락하세요 — 로드맵에 있으며 엔터프라이즈 플랜에서는 현재 이용 가능합니다.

출력 URL은 영구적인가요?

아닙니다. 결과를 다운로드하여 자체 버킷에 저장하세요 — URL은 검색할 수 있을 만큼 유효하지만 만료됩니다.

이미지 크기에 따라 가격이 달라지나요?

아닙니다. 가격은 성공적인 호출당 정액입니다.

미사용 크레딧이 이월되나요?

네 — 유료 플랜에서 미사용 크레딧은 월별로 이월됩니다. 가격을 참조하세요.

드리운 그림자를 유지할 수 있나요?

기본값은 드리운 그림자를 포함하여 모든 배경을 제거합니다. 그림자 유지는 설정 플래그를 통해 엔터프라이즈 배포에서 이용 가능합니다.

다음 단계

PDF to Visual Struct — PDF 문서의 구조적 변환.
Visual Struct — 이미지의 구조적 변환.
전체 endpoint 레퍼런스는 /api#remove-background에서 확인하세요.