소개
엔드포인트 기능
prompt의 대상을 찾아 나머지를 제거하고 투명 배경 PNG를 반환합니다.
주요 입력
image_url은 사진이며 prompt는 남길 대상을 설명합니다. autocrop은 캔버스를 대상에 맞춰 자르고 refine_edges는 가장자리를 추가 정리합니다. 기본값은 모두 꺼짐입니다.
반환 결과
투명 PNG 1장입니다. autocrop을 켜지 않으면 사진 크기를 유지합니다.
| 항목 | 값 |
|---|---|
| 입력 | 이미지 |
| 출력 | 이미지 |
| 엔드포인트 | 이미지 편집 |
| 캔버스 | 사진 전체 크기 또는 autocrop으로 자르기 |
| 가장자리 정리 | 선택적 추가 처리( |
핵심 기능 및 하이라이트
두 사람 중 한 사람을 설명으로 선택
두 사람의 바 장면에서 "the woman in the cream sweater"를 요청했습니다. 남성과 병 선반은 제거되고 여성은 머리카락과 스웨터 가장자리가 유지된 전체 1536×864 투명 캔버스로 나왔습니다.
와인 잔 하나만 꼭 맞게 자르기
autocrop을 켠 "the wine glass in front of the man"은 잔만 있는 130×307 PNG가 되었습니다. 잔 너머의 바 조명은 남으므로 새 배경에 놓기 전에 알아두어야 합니다.
마스크를 그릴 필요 없음
브러시나 상자를 배치할 필요 없습니다. 색, 위치, 옷을 포함한 짧은 문구로 비슷한 대상을 구분합니다.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
image_url | 예 | 대상이 있는 사진입니다. JPEG·PNG·WebP 파일을 올리거나 파일로 바로 가는 링크를 넣으세요. 1자 이상 |
prompt | 예 | 필수입니다. "the red car"나 "the woman in the cream sweater"처럼 남길 대상 하나를 짧게 설명합니다. 1자 이상 · 500자 이하 |
refine_edges | 아니요 | 기본값은 꺼짐입니다. 켜면 배경 제거를 추가 실행해 남은 배경 픽셀과 가장자리 투명도를 정리합니다. 기본값: |
autocrop | 아니요 | 기본값은 꺼짐으로 사진 전체 크기를 반환합니다. 켜면 대상 주변에 꼭 맞게 자릅니다. 기본값: |
요금
$0.024 / 장
추출당 고정 요금이며 설명, 가장자리 정리, 자르기는 요금에 영향을 주지 않습니다. 실패한 요청은 과금하지 않습니다.
활용 사례
복잡한 사진에서 상품 하나 추출
라이프스타일 사진에서 병, 가방, 신발 하나를 꺼내 카탈로그 카드에 사용합니다. 나머지 장면을 수동 보정할 필요가 없습니다.
단체 사진에서 한 사람 선택
배경 제거는 앞의 모두를 남기지만 여기서는 남길 사람을 지정해 다른 사람을 배경과 함께 제거합니다.
콜라주·썸네일용 소재
대상에 맞춰 자른 뒤 새 배경, 영상 썸네일, 슬라이드에 배치합니다.
프롬프트 가이드 및 실전 팁
대상 하나를 설명합니다
prompt에 "the red car"나 "the woman on the right" 같은 짧은 명사구를 씁니다. 비슷한 대상이 여럿이면 색, 위치, 옷의 특징을 덧붙입니다.
캔버스를 선택합니다
autocrop을 끄면 원래 위치에 다시 겹칠 수 있는 사진 전체 크기로 반환합니다. 켜면 대상에 맞춘 PNG가 되어 상품 카드나 스티커에 쓸 수 있습니다.
필요하면 가장자리를 정리합니다
refine_edges를 켜면 배경 제거를 추가 실행해 남은 픽셀과 가장자리 투명도를 정리합니다. 머리카락과 부드러운 윤곽에 유용합니다.
소개
Object Extractor는 텍스트 설명으로 사진에서 대상 하나를 분리해 투명 배경으로 반환합니다. 배경 제거가 전경의 모든 피사체를 남기는 것과 달리 지정한 대상만 남깁니다.
요청
{
"image_url": "https://example.com/bar.jpg",
"prompt": "the woman in the cream sweater",
"refine_edges": true,
"autocrop": false
}
image_url과 prompt 두 필드는 반드시 넣어야 합니다. refine_edges는 배경 제거를 추가 실행해 가장자리의 남은 픽셀을 정리합니다. autocrop은 전체 사진 크기 대신 캔버스를 대상에 맞춰 자릅니다.
테스트 결과
1536×864 바 장면의 "the woman in the cream sweater"는 약 17초 후 머리카락과 스웨터 가장자리가 깔끔한 1536×864 크기로 여성만 반환되었습니다. 손의 와인 잔과 기대고 있던 테이블의 얇은 부분도 남았습니다. autocrop을 켠 "the wine glass in front of the man"은 130×307 PNG로 나왔고 유리를 통해 보이는 배경은 안에 남았습니다. 양손으로 든 커피 머그는 손가락이 가린 부분이 비어 있었습니다. 설명 없는 요청은 사진을 그대로 반환했습니다.
작업 흐름
대상 추출은 비동기로 실행됩니다. 작업을 생성하고 완료까지 폴링한 뒤 SpicyAPI 저장소에서 PNG를 다운로드합니다. 추출당 고정 요금이며 실패한 요청은 과금하지 않습니다.
팁
- 비슷한 대상은 구체적으로 씁니다. "the bottle"보다 "the taller bottle on the left"가 좋습니다.
- 같은 위치에 다시 놓으려면
autocrop을 꺼 둡니다. - 모든 피사체를 한 번에 남기려면 Background Remover (
/models/background-remover-v1)가 더 간단합니다.
API 빠른 시작
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/object-extractor-v1/edit",
"input": {
"image_url": "https://example.com/reference.png",
"prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
인증, 전체 스키마, 폴링과 오류 처리는 API 레퍼런스에서 확인하세요.




