물체 제거 API: 마스크를 만들고 편집된 이미지 내려받기

spicyapi/object-eraser-v1/edit에 image_url과 짧은 prompt, mask_url, 또는 둘 다를 넣어 사용합니다. 마스크에서는 흰색이 제거, 검은색이 유지를 뜻하며, 픽셀 크기가 원본과 같아야 합니다. 요청 하나가 몇 개의 물체를 제거하든 가격은 출력 이미지 1장당 0.03달러입니다. 결과는 원래 캔버스 크기를 유지하고, 선택한 영역은 주변 장면의 내용으로 채워집니다.

프롬프트와 마스크 중 고르기

주변에 여백이 있고 눈에 띄는 물체라면 짧은 설명으로 시작합니다.

앞쪽 오른편 의자 다리 옆 바닥에 있는 흰색 종이컵

명사, 눈에 보이는 색이나 재질, 위치를 적습니다. "장면을 깔끔하고 고급스럽게 만들어 줘"는 무엇을 없앨지 가리키지 못합니다. 프롬프트는 1~1000자까지 쓸 수 있지만, 길게 쓴다고 선택이 더 정확해지지는 않습니다.

설명이 어디에도 맞지 않으면 이미지가 바뀌지 않은 채 돌아오고, 작업은 그래도 성공으로 처리됩니다. 제거된 것으로 판단하기 전에 출력을 원본과 비교하세요.

선택 가능한 대상을 그린 삽화입니다. 표시된 물체는 모두 남아 있으며 API 출력이 아닙니다.

먼저 Playground에서 시험하기

1. Object Eraser 페이지를 열고 Playground 탭의 Form 보기에서 잔액이 있는 계정으로 로그인해 실행합니다.
2. Input image에 사진을 추가합니다(JPG, PNG, WebP, 최대 10 MB). 파일을 끌어다 놓거나, Asset URL과 Add URL로 링크를 붙여 넣거나, 찾아보기로 선택합니다.
3. Prompt에 대상을 설명하거나, Mask에 흑백 이미지를 추가하거나, 둘 다 채웁니다. 폼은 둘 중 하나 이상을 요구합니다.
4. Output format은 PNG로 두고(JPEG와 WebP는 파일이 더 작습니다) 실행합니다. 가격은 이미지당 0.03달러입니다.
5. 결과를 원본과 마스크 옆에 열고, 무언가 남아 있으면 아래 실패 표를 참고합니다.

Request body 패널에는 API가 받는 것과 같은 JSON이 표시되므로, 여기서 통한 프롬프트나 마스크는 그대로 코드에 옮길 수 있습니다. 여기서 실패한다면 코드를 한 줄 쓰기 전에 프롬프트나 마스크부터 고치세요.

보낼 이미지와 정확히 맞춰 마스크 만들기

영역을 이미 안다면(검출기의 박스나 UI 선택 등) 코드로 마스크를 생성합니다. 크기를 원본에서 가져오므로 항상 일치합니다.

from PIL import Image, ImageDraw

src = Image.open("source.jpg")          # apply EXIF rotation and crop first
mask = Image.new("L", src.size, 0)      # black = keep
bbox = (src.width // 4, src.height // 3, src.width // 2, src.height // 2)
# Example coordinates only: adjust this box to the unwanted object in your photo.
ImageDraw.Draw(mask).rectangle(bbox, fill=255)  # white = remove
mask.save("mask.png")

2400×1600 원본에서 불규칙한 모양을 다룬다면 이미지 편집기에서 2400×1600 마스크를 준비합니다.

1. 먼저 원본의 회전과 자르기를 끝내고 그 작업용 이미지를 저장합니다.
2. 캔버스 전체 크기의 검은색 레이어를 추가하고, 그리는 동안 대상이 보이도록 불투명도를 낮춥니다.
3. 컵을 흰색으로 칠합니다. 원치 않는 가장자리와 접촉 그림자를 포함하고, 여유가 있는 곳은 약간 넉넉하게 칠합니다. 의자 다리는 검은색으로 둡니다.
4. 레이어를 다시 완전 불투명으로 돌리고 그 레이어만 불투명한 흑백 PNG로 내보냅니다. 어둡게 만든 사진이나 색이 있는 주석은 안 됩니다.
5. 내보낸 마스크를 작업용 원본에 겹쳐 흰색 영역을 확인합니다.

가로세로 비율만 같아서는 부족합니다. 두 파일의 너비, 높이, 자르기, 방향이 모두 같아야 합니다. 근처에 다른 물체가 없는 곳이라면 약간 넉넉한 모양도 괜찮습니다. 모델 페이지의 예시에서 프레임 가장자리 선반용 마스크는 사진과 같은 크기의 검은 캔버스에 선반 위로 단순한 흰 직사각형 하나를 얹은 것입니다.

그림자와 반사는 물체의 윤곽 밖에 있을 수 있습니다. 원치 않는 반사는 별도의 흰색 영역으로 칠하세요. 컵의 그림자가 의자의 접지 그림자와 겹치는 곳에서는 어두운 부분 전체를 흰색으로 칠하지 마세요. 의자가 떠 보일 수 있습니다. 마스크는 제거할 범위를 표시할 뿐, 가려진 바닥이나 제품의 형태를 제공하지 않습니다.

큰 제거나 서로 겹치는 제거는 별도의 패스로 실행하고, 각 마스크는 직전에 채택한 출력을 바탕으로 만듭니다. 작은 물체 두 개를 한 요청에 처리하면 0.03달러, 별도 요청 두 번이면 0.06달러입니다. 오래된 선택이 새 사진을 조용히 편집하지 않도록 마스크와 이미지 파일 이름을 짝으로 관리하세요.

그다음 코드로 실행하기

Python SDK를 설치하고(pip install spicyapi), 서버 환경에 SPICY_API_KEY를 설정한 뒤 아래 요청을 실행합니다. 모델 페이지의 예시 사진을 사용하므로 그대로 동작합니다. 내 컴퓨터의 파일은 client.upload_file을 거치면 spicy:// 주소로 돌아옵니다. 마스크를 쓰려면 사진과 같은 픽셀 크기의 내 파일로 "mask_url"을 추가하세요.

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="spicyapi/object-eraser-v1/edit",
    input_data={
        "image_url": "https://cdn.spicyapi.ai/models/examples/inputs/fbc8d531c80e6d0d.jpeg",
        "prompt": "the wooden ladle lying across the sauna stones at the left",
        "output_format": "png",
    },
    idempotency_key=str(uuid.uuid4()),
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
print(output_assets(final)[0]["url"])  # copy the image to your own storage now

업로드, 생성, 대기, 다운로드, 재시도, 오류 코드는 작업 가이드와 Python SDK 레퍼런스에서 다룹니다. 생성된 파일은 최대 14일간 보관되므로 결과를 내 저장소로 복사하세요.

또는 에이전트가 실행하게 하기

어시스턴트가 편집을 실행해야 할 때 공식 도구 세 가지는 모두 가격을 보여 주고 유료 호출 전에 확인을 요청합니다.

• CLI. 사진과 마스크를 업로드한 뒤 작업을 만듭니다.

``bash spicyapi files upload photo.jpg spicyapi tasks create --model spicyapi/object-eraser-v1/edit --input-file input.json --wait ``

반환된 spicy:// 주소를 input.json에 image_url과 mask_url로 넣습니다. CLI 문서를 참고하세요. npx @spicyapi/cli는 설치 없이 동작합니다.

• MCP 서버. 어시스턴트에 MCP 서버를 추가한 뒤 "Object Eraser로 이 사진에서 흰색 종이컵을 지워 줘. 파일은 /path/to/photo.jpg에 있어"라고 요청합니다. spicyapi_upload_file로 파일을 업로드하고, 가격 확인에서 멈추는 spicyapi_task_create를 호출한 다음 spicyapi_task_wait를 호출합니다.
• 스킬. npx skills add spicyapi-ai/spicy-skill은 Agent Skill을 설치하며, 코딩 어시스턴트가 필드를 추측하는 대신 최신 모델 스키마를 읽게 합니다.

눈앞의 실패에 맞게 고치기

erased.png를 원본과 마스크 옆에 엽니다. 먼저 선택 영역이 유지되는 내용과 만나는 부분을, 그다음 채움의 중앙을 확인합니다.

그림자와 반사 점검을 그린 삽화입니다. 제거가 끝난 모습을 보여 주지 않습니다.

모델은 가려진 배경을 복원하지만, 물체 뒤에 실제로 무엇이 있었는지 드러낼 수는 없습니다. 상품 페이지라면 바닥이 깨끗해 보인다는 이유로 만들어진 의자 이음매나 달라진 시트 박음질을 받아들이지 마세요. 제거한 물체가 상품 페이지에 정확히 보여야 할 세부를 가리고 있었다면 다시 촬영하세요.

SpicyAPI는 이 모델에 안전 검사를 실행하지 않으며, 무엇을 반환할지는 모델이 직접 결정합니다.

채택한 출력과 함께 원본과 마스크를 보관하고, 특정 물체가 남은 경우에만 패스를 추가하세요. 모델 페이지의 Examples 탭에서 실제 전후 결과를 볼 수 있습니다.