배경 제거 API: 투명 제품 PNG 납품하기

회색 테이블과 창턱 위에서 찍은 제품 사진이 수백 장 있고, 쇼핑몰이나 마켓플레이스, 디자이너가 각각을 투명 PNG로 요청한다고 해 보겠습니다. SpicyAPI Background Remover는 호출 한 번으로 이를 처리합니다. 사진 URL을 보내면 원본과 같은 가로·세로 크기의 투명 PNG 위에 주요 피사체를 담아 돌려줍니다. 남는 일은 사용자 몫입니다. 파일에 정말 알파가 있는지 확인하고, 실제로 놓일 배경 위에서 가장자리를 점검하고, 납품처마다 요구하는 평면 사본을 내보내야 합니다.

먼저 Playground에서 해 보기

background-remover-v1 Playground를 엽니다. Input image에 제품 사진을 놓고 가격을 확인한 뒤 Run model을 누릅니다. 같은 사진을 코드에서 쓰기 전에, 투명한 결과를 밝은 배경과 어두운 배경 위에서 살펴보십시오.

엔드포인트가 받는 것과 돌려주는 것

출력은 원본 캔버스 크기를 유지하므로, 크기를 조정하지 않고 오려 낸 이미지를 새 배경 위에 놓을 수 있습니다. 오려 내는 경계에는 반환된 알파 채널을 사용하십시오. 캔버스가 같다고 해서 전경의 모든 가장자리나 색이 그대로라는 보장은 없습니다. 자세한 내용은 Background Remover 모델 페이지에 있습니다.

먼저 실제 결과 보기

모델 페이지의 예시는 회색 스튜디오 배경 위의 서리 낀 유리 스포이트 병이며, 크기는 1024 × 1536픽셀입니다. 해당 페이지의 변환 전과 후 파일이고, 여기서는 '후' 이미지를 페이지 배경 위에 표시했습니다.

다음 장들의 검사 스크립트를 이 쌍에 실행하면 좋은 결과의 수치가 나옵니다. 출력에는 알파 채널이 있고, 크기는 원본과 일치하며, 픽셀의 약 78%는 완전히 투명하고 약 22%는 불투명하며, 반투명한 가장자리 픽셀은 약 0.35%에 불과합니다. 피사체 상자는 335 × 1,234픽셀입니다. 어두운 남색 배경에 합성해도 스포이트 끝, 브러시드 칼라, 서리 낀 유리 어깨 부분에 밝은 테두리가 생기지 않습니다.

호출하기

python -m pip install spicyapi pillow로 spicyapi와 pillow를 설치합니다. SPICY_API_KEY를 설정하고, IMAGE_URL에 원본 이미지의 직접 URL을 지정한 다음 이 예제를 실행하십시오. 가격 확인을 요청하고, 작업을 만들어 끝날 때까지 기다리고, 오려 낸 이미지를 저장하고, 밝은 배경과 어두운 배경의 미리 보기를 기록합니다.

import os
import urllib.request
import uuid
from io import BytesIO
from pathlib import Path

from PIL import Image
from spicyapi import SpicyClient, output_assets

client = SpicyClient()
model = "spicyapi/background-remover-v1/edit"
inputs = {"image_url": os.environ.get("IMAGE_URL", "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png")}

quote = client.quote_task(model=model, input_data=inputs)
if input(f"Maximum ${quote['maxCharge']}. Create? [y/N] ") != "y":
    raise SystemExit("Stopped without creating a task.")

task = client.create_task(model=model, input_data=inputs, idempotency_key=str(uuid.uuid4()),
                          quote_id=quote["quoteId"], expected_cost=quote["estimatedCost"])
print("Task:", task["taskId"])  # keep this ID: a timeout does not cancel the task
task = client.wait_for_terminal(task["taskId"])
if task["state"] != "succeeded":
    raise RuntimeError(str(task.get("errorMessage", task["state"])))

asset = output_assets(task)[0]
request = urllib.request.Request(asset["url"], headers={"User-Agent": "SpicyAPI-Blog-Example/1.0"})
with urllib.request.urlopen(request, timeout=120) as response:
    data = response.read()
Path("cutout.png").write_bytes(data)

with Image.open(BytesIO(data)) as image:
    if image.format != "PNG":
        raise RuntimeError("Expected a PNG cutout.")
    rgba = image.convert("RGBA")
alpha = rgba.getchannel("A")
values = list(alpha.getdata())
print({"size": rgba.size, "alpha_min_max": alpha.getextrema(),
       "clear_fraction": sum(v <= 8 for v in values) / len(values),
       "solid_fraction": sum(v >= 247 for v in values) / len(values),
       "soft_fraction": sum(8 < v < 247 for v in values) / len(values),
       "subject_box": alpha.getbbox()})
for name, colour in [("light", "#f5f2e8"), ("dark", "#162235")]:
    Image.alpha_composite(Image.new("RGBA", rgba.size, colour), rgba).convert("RGB").save(name + ".jpg")

응답을 잃어버린 뒤 같은 요청을 다시 시도할 때는 새 키를 만들지 말고 그 요청의 멱등성 키를 재사용하십시오(멱등성 레퍼런스). 로컬 파일 업로드는 Python SDK와 미디어 문서를 참고하십시오.

파일을 디코딩해서 투명도 검증하기

흰색 미리 보기는 아무것도 증명하지 못합니다. 흰 페이지 위의 진짜 오려 낸 이미지일 수도, 흰 배경이 있는 불투명 이미지일 수도, 픽셀에 직접 그려 넣은 체크무늬일 수도 있습니다. 파일을 디코딩해서 알파 채널을 읽으십시오. 알파가 저장되는 방식은 PNG 사양에 정의되어 있습니다. 실무에서 알아야 할 것은 디코딩한 뒤 투명해질 수 있는 픽셀이 있는지이지, 파일 이름이 무엇이라고 하는지가 아닙니다.

이 예제는 알파의 분포를 보고하고, Pillow로 크림색과 어두운 남색 합성본을 기록해 검토할 수 있게 합니다. 보고된 크기를 원본과 비교하십시오.

임곗값에 주의하십시오. 알파 255만 불투명으로 세면 오해하기 쉽습니다. 스포이트 병 출력에서는 픽셀의 약 14%가 알파 1~254에 있지만 거의 대부분이 254이고, 이는 눈으로 보면 불투명입니다. 알파 8 이하를 투명, 247 이상을 불투명으로 취급하면 '부드러운' 비율에는 정말 관심 있는 것, 즉 안티앨리어싱된 가장자리, 머리카락, 진짜 반투명한 소재만 남습니다.

보고서 읽는 법:

• 알파 채널이 없거나 alpha_min_max가 (255, 255)이면 투명도가 없다는 뜻입니다. 가장자리를 검토하기 전에 파이프라인을 조사하십시오.
• 배경이 있던 사진에서 clear_fraction이 0에 가깝거나 solid_fraction이 0에 가깝다면, 피사체가 사라졌거나 결과가 뿌연 안개 같은 상태입니다.
• 크기가 맞지 않으면 대개 EXIF로 회전된 원본이거나 사용자 코드의 크기 조정 때문입니다. 엔드포인트는 크기를 유지하기 때문입니다.
• soft_fraction이 큰 것은 유리, 천, 머리카락에서는 정상이지만 무광 머그잔에서는 경고 신호입니다. 임곗값은 하나의 전역 수치가 아니라, 파일럿 세트를 살펴본 뒤 제품 카테고리별로 정하십시오.
• 넉넉하게 자른 사진에서 피사체 상자가 캔버스 가장자리에 닿는다면 두 번째 물체가 남았을 가능성이 있습니다.

제품을 바꾸지 않고 사진 준비하기

촬영이나 자르기 전에 무엇을 제품으로 볼지 정하십시오. 리본, 포장, 접촉 그림자는 포함하거나 제외하거나 둘 중 하나이며, 문서로 작성된 적 없는 지침을 도구가 짐작할 수는 없습니다. 깨진 테두리를 다시 그리거나 없는 로고를 만들어 넣지 마십시오. 상품 페이지에서 보여 줘야 하는 결함은 사진에 그대로 둡니다.

• 경쟁하는 물체를 없애려고 자르되, 손잡이나 스트랩이 API에 닿기 전에 잘려 나가지 않도록 모든 끝부분 둘레에 여백을 남기십시오.
• 겹친 물체는 자르기로 해결되지 않습니다. 가려진 경계를 추측해야 하기 때문입니다. 다시 촬영하고, 겹침, 투명 진열대, 잘린 피사체는 예외 레인으로 보내 일반 배치를 막지 않게 하십시오.
• 가장 깨끗한 파일을 제출하십시오. JPEG를 반복해서 내보내면 가장자리에 디테일이 필요한 바로 그 자리에 블록 아티팩트가 생깁니다. 무손실 작업 사본을 보관하십시오. 색상 프로파일은 의도를 가지고 변환하십시오. 부주의한 변환은 누군가 오려 낸 결과를 검토하기도 전에 제품의 색을 바꿔 버립니다.

이미지를 쓸 곳에서 가장자리 검토하기

오려 낸 이미지를 검토하는 페이지 위에서만이 아니라 실제 납품 배경 위에 놓아 보십시오. 크림색 위에서는 깨끗해 보이는 이미지도 어두운 남색 위에서는 옅은 테두리가 보일 수 있습니다. 이 테두리는 반투명 픽셀에 남은 원본 배경의 색입니다. 결함이 문제가 되는지 보려면 납품 크기에서, 모양을 보려면 100%에서 확인하십시오. 스크립트의 합성본 두 개는 크림색과 어두운 남색을 쓰니, 브랜드 색으로 바꾸십시오.

모든 픽셀을 똑같이 볼 것이 아니라, 이런 종류의 제품을 알아보게 하는 부분을 살펴보십시오. 머그잔 손잡이 안쪽, 테두리와 굽, 신발 끈과 밑창, 솔 털, 스포이트 끝 같은 곳입니다. 원본, 알파, 합성본을 같은 배율과 같은 자르기 범위에서 비교하십시오. 파일을 반려할 때는 잃어버린 특징과 납품처를 적으십시오("어두운 합성본에서 손잡이 구멍이 채워짐"). 그래야 다음 사람이 자르기, 보정, 재촬영 중 무엇을 해야 하는지 알 수 있습니다.

재시도가 아니라 판단이 필요한 상황이 세 가지 있습니다.

• 실루엣 안쪽의 구멍. 손잡이 구멍이나 의자 난간 사이의 틈은 배경에 속합니다. 윤곽선만 확인하면 구멍이 채워져 있어도 괜찮아 보일 수 있습니다. 어두운 합성본에서 확인하십시오.
• 그림자. 접촉 그림자는 제품을 바닥에 안정감 있게 붙여 주지만, 길게 드리운 그림자는 배경 질감을 오려 낸 이미지 안으로 끌고 들어옵니다. 마스터에 그림자를 남길지, 레이아웃에서 직접 그릴지 정하십시오. 직접 추가한다면 원본에 이미 있는 그림자를 약하게 하거나 지워서 두 그림자가 충돌하지 않게 하십시오.
• 유리와 반투명 소재. 병의 색에는 배경에서 투과된 빛이 포함되어 있으므로, 어떤 새 배경에서나 물리적으로 맞는 병을 만들어 주는 오려 내기는 없습니다. 흰색 위에서는 자연스러운 옅은 스튜디오 반사가 어두운 배경에서는 이상해 보일 수 있습니다. 반투명 플라스틱과 천은 알파를 0이나 255로 임곗값 처리하지 말고 부분 알파를 유지하십시오. 테두리를 없애려고 마스크 전체를 깎아 내지도 마십시오. 제품이 가늘어지고 세부 특징을 잃습니다. 사본에서 국소적으로 보정하십시오.

원인이 된 단계에서 실패 바로잡기

다시 실행하기 전에 분류하십시오. 같은 호출을 반복하면 비용이 들고, 이런 경우 대부분은 아무것도 달라지지 않습니다.

도구를 유도할 프롬프트가 없으므로 조절 수단은 입력 사진과 호출 후의 작업뿐입니다. 어떤 카테고리가 계속 실패한다면 요청을 반복하지 말고 촬영 방식을 바꾸십시오.

단색 배경이 필요한 납품처를 위해 평면화하기

마켓플레이스는 흰 배경의 JPEG를 요구하는 경우가 많습니다. JPEG에는 알파가 없으므로, 마스터를 JPEG로 내보내면 아무도 승인하지 않은 기본 색이 투명 영역을 채웁니다. 선택한 색 위에서 평면화하고, PNG는 마스터로 보관하며, 크기는 균일하게 조정하십시오(가로와 세로를 따로 늘리지 마십시오). 스크립트가 기록하는 light.jpg가 바로 이 단계를 크림색 위에서 한 결과입니다. 흰색으로 하려면 반복문 안의 색을 바꾸거나 이미지 편집기에서 평면화한 JPEG를 따로 내보내십시오. 마스터만이 아니라 평면 파일도 확인하십시오. 리샘플링, 색 변환, 압축은 각자의 결함을 더합니다. 쇼핑몰이나 CMS에 업로드한 뒤에만 테두리가 나타난다면, 마스터, 내보낸 파일, 플랫폼 썸네일의 디코딩된 픽셀을 비교하십시오. 원인은 오려 내기가 아니라 플랫폼의 크기 조정이나 재압축인 경우가 많습니다.

다른 경로가 맞는 도구인 경우

단순한 오려 내기라면 Background Remover가 이 표에서 가장 저렴한 경로이며 원본 캔버스 크기를 유지합니다. 이 도구가 의도적으로 제공하지 않는 것이 필요할 때는 다른 경로를 쓰십시오.

생성형 모델이 PNG를 돌려준다고 해서 투명해지는 것은 아닙니다. PNG는 불투명한 흰 배경을 담을 수 있습니다. 모든 결과를 같은 스크립트로 디코딩하십시오. 제품의 정확한 픽셀이 중요한 경우(라벨, 로고, 포장 문구)에는 생성형 재작성보다 추출 경로를 택하십시오.

검토자가 허우적대지 않게 배치 처리하기

모델 호출은 저렴하고 빠르며, 병목은 검토입니다. 카탈로그를 대표하는, 권리가 정리된 사진 열두 장 정도로 파일럿을 시작하십시오. 깨끗한 단순 형태 하나, 손잡이나 구멍이 있는 것, 광택이 있는 것, 가는 가장자리가 있는 것, 경쟁하는 물체가 있는 것을 하나씩 넣습니다. 어떤 카테고리는 가벼운 검토로 넘기고 어떤 카테고리는 항상 사람이 볼지를 파일럿이 정해 줍니다.

• 동시 실행 수에 상한을 두고 제출하며 다운로드 큐는 따로 두어, 느린 다운로드가 재추출을 일으키지 않게 하십시오. 다운로드가 실패하면 링크가 유효한 동안 기존 결과를 대상으로 다시 시도하십시오. 큐 설계는 백프레셔 가이드에서 다룹니다.
• 원본 리비전마다 자체 에셋 ID, 원본 체크섬, 작업 ID, 출력 위치, 검토 결정을 저장하십시오. SKU만으로는 부족합니다. 제품 하나에는 여러 각도와 재촬영본이 있습니다.
• "succeeded"는 "검사할 준비가 됨"이라는 뜻이지 "게시"라는 뜻이 아닙니다. 스크립트를 자동으로 실행하고, 사람에게는 표시된 파일과 샘플만 보내십시오. 파일럿을 통과한 카테고리(중립 배경 위의 단순한 물체)는 드리프트를 잡기 위한 주기적 샘플링을 곁들여 더 가벼운 레인으로 옮길 수 있습니다. 반사되는 것, 투명한 것, 모호한 것은 계속 전수 검토합니다. 캠페인 대표 이미지는 완료 순서가 아니라 보조 각도보다 먼저 검토하십시오.
• 완료 알림은 비동기 작업의 폴링과 Webhook 비교 가이드를 참고하십시오. 어느 쪽이든 결과는 같은 검사 단계로 들어갑니다.
• 실패가 같은 원인을 공유하면 멈추십시오. 손잡이 구멍을 열 번 잃었다면 그것은 원본 세트에 대한 정보이지, 열 번 재시도할 이유가 아닙니다.

승인된 이미지 한 장당 비용

오려 내기 100장은 $0.48, 1,000장은 $4.80입니다. 중요한 수치는 승인된 마스터당 지출입니다. 계획 예시로, 첫 오려 내기 100장에 다시 자른 10장을 더한 배치는 110 × $0.0048 = $0.528이고, 95장이 검토를 통과하면 승인된 이미지당 약 $0.0056입니다.

검토 시간은 보통 API보다 비용이 더 듭니다. 유용한 수단은 상류에 있습니다. 검토 시간 대부분이 유리병에 들어간다면, 그 촬영의 조명을 개선하는 편이 어떤 가격 차이보다 더 많이 절약합니다. 완료된 오려 내기를 반려해도 그것은 여전히 완료되어 과금된 출력입니다. 실패하거나 만료된 작업은 홀드가 해제됩니다.

원본, 마스터, 내보내기를 분리해 보관하기

원본 사진, 투명 PNG 마스터, 평면화한 각 납품 사본을 별도 파일로 보관하고 용도에 맞는 이름을 붙이십시오(예: <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream). 보정한 버전은 손대지 않은 API 출력과 따로 보관해, 나중에 테두리가 생겼을 때 오려 내기와 내보내기 중 어디가 원인인지 추적할 수 있게 하십시오. 승인된 납품 크기도 각 마스터와 함께 저장해, 카드 크기 승인이 대표 이미지 크기 승인으로 오해되지 않게 하십시오.

반려는 하나의 분류로 기록하십시오. 잘못된 피사체, 잃어버린 특징, 테두리, 남은 배경 조각, 내보내기 결함 중 하나입니다. 건수는 무언가를 바꿀 때만 의미가 있습니다. 자르기 규칙, 유리용 수동 레인, 고친 내보내기 프리셋 같은 것입니다. 사진가에게는 "AI가 처리하기 쉽게 해 주세요"가 아니라 구체적인 촬영 규칙을 주십시오("손잡이 전체가 보이게 할 것, 구멍 뒤에 선물 상자를 두지 말 것", "밝은 제품에는 더 어두운 배경").

자주 묻는 질문

무료 배경 제거 API가 있습니까?

이 엔드포인트에는 없습니다. 완료된 출력 한 장마다 $0.0048이 들므로 사진 100장 파일럿은 $0.48입니다. 무료가 필수 조건이라면 rembg 같은 오픈 소스 제거 도구를 직접 호스팅하면 이미지당 요금을 피할 수 있지만, 그러면 직접 운영하고 조정해야 합니다. 호스팅 경로에서는 안정적인 엔드포인트와 예측 가능한 비용을 얻습니다.

결과를 PNG로 저장하면 배경이 투명해집니까?

아닙니다. PNG는 알파를 담을 수 있지만 불투명한 흰 배경을 담을 수도 있습니다. 파일을 디코딩해서 알파 채널을 읽고, 밝은 배경과 어두운 배경의 합성본을 검토하십시오. JPEG의 확장자를 .png로 바꾼다고 달라지는 것은 없습니다.

손잡이나 머리카락, 그림자를 남기라고 지시할 수 있습니까?

이 작업에서는 안 됩니다. 입력은 이미지 URL뿐입니다. 원본을 자르거나, 다시 촬영하거나, 로컬에서 보정하십시오. 프롬프트로 제어하는 결과를 원한다면 위 표의 이미지 편집 경로를 사용하고, 이후에 제품과 알파를 검증하십시오.

어떻게 시작해야 합니까?

대표적인 제품 하나와 납품처 하나를 고르십시오. 사진을 보내고, PNG를 디코딩하고, 두 가지 배경 위에서 가장자리를 검토하고, 승인된 파생본을 평면화한 뒤, 디자이너가 실제 레이아웃에서 열어 보게 하십시오. 그다음 파일럿 세트의 더 까다로운 항목을 실행하고, 전체 카탈로그를 예약하기 전에 재촬영이나 수동 레인이 필요한 것을 기록하십시오.

Agent에게 호출 맡기기

입력 준비와 결과 반환은 Agent가 하고, 가격과 크리에이티브 결정은 직접 승인하고 싶을 때 Agent를 사용하십시오.

• CLI: 같은 입력 객체를 input.json으로 저장한 뒤 npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait를 사용하십시오. CLI는 가격 확인을 요청합니다. 복구용으로 반환된 작업 ID를 보관하십시오.
• MCP: 어시스턴트에게 spicyapi/background-remover-v1/edit에 대해 spicyapi_task_create를 사용한 다음 spicyapi_task_wait를 사용하도록 요청하십시오. MCP 서버는 생성 전에 가격 확인을 요청합니다.
• Skill: npx skills add spicyapi-ai/spicy-skill로 설치한 뒤 $spicyapi에게 같은 워크플로를 실행하고 승인을 위해 멈추도록 요청하십시오. Skill은 설정된 CLI 또는 MCP 연결을 사용합니다.