배경 제거 API 문서

설명

이 클라우드 API는 자동화된 고정밀 배경 제거를 위해 지능형 돌출 개체 감지(SOD)를 사용합니다. 최적의 속도를 위해 소스 이미지를 5MB 미만으로 유지하세요.

🥥 중요 사항

데이터 보존: 출력 이미지 URL 및 알파 매트(마스크)는 1일 동안만 유효합니다. 즉시 다운로드하여 저장하세요.
속도 제한: 기본 제한은 2 QPS입니다. 동시성을 높이려면 영업팀이나 비즈니스 개발팀에 문의하세요.

버전 기록

4.0 | 출시일: 2025-03-20
4.0.1 | 출시일: 2026-07-01 (다중 결과 출력에 대한 지원이 추가되었습니다.)

입력 이미지 요구 사항

이미지 형식	해상도	파일 크기
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	최대 10MB(포함)

🥥 중요 사항

출력 URL는 24시간 후에 만료됩니다.
기본 속도 제한은 2 QPS입니다. 동시성 제한을 업그레이드하려면 당사에 문의하세요.

URL 요청

🥥 https://coco-openapi.yezisheji.com/api/v1/segment/submit
https://coco-openapi.yezisheji.com/api/v1/segment/task_info

요청 방법 및 예시

# 작업 만들기

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/submit' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_file=@/path/of/image.jpg'

# 작업 가져오기

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/task_info' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'task_id={YOUR_TASK_ID}'

인증 및 권한

이러한 서비스를 사용하기 전에 API Key를 요청하세요. 자세한 내용은 사업 개발 또는 영업팀에 문의하세요.
API 인증: HTTP Header를 통해 비밀 토큰을 전달하고 API Key를 안전하게 저장하세요.

구축 요청

1、이미지 배경 제거

POST /api/v1/segment/submit

요청 매개변수:

매개변수 이름	유형	기본값	선택적 값	설명
image_url	String	None	-	배경을 제거할 이미지의 URL(image_file과 상호 배타적)
image_file	String($binary)	None	-	로컬 이미지 파일(image_url과 상호 배타적)
rsz_w	int	None	Integer between [0~4096]	0보다 큰 경우 반환된 이미지의 크기를 rsz_w에 비례하여 조정합니다.
rsz_h	int	None	Integer between [0~4096]	0보다 큰 경우 반환된 이미지의 크기를 rsz_h에 비례하여 조정합니다.
crop_object	int	None	0、1	주 주제 영역까지 자르려면 1로 설정합니다.
multi_result	int	None	0、1	여러 매트 결과를 반환할지 여부입니다. 청구는 반환된 결과 수를 기준으로 하며 일반적으로 5개를 초과할 수 없습니다.
sync	int	0	0、1	0은 나중에 task_info 폴링을 위해 즉시 task_id를 반환합니다. 1은 완료를 기다리고 결과를 반환합니다.
output_type	int	1	1、2、3	이미지 및 마스크 결과를 반환합니다. 1 이미지만. 2 이미지와 마스크. 3 마스크만.
output_format	String	png	jpeg、png	반환된 이미지 형식입니다. png: 투명한 배경. JPEG: 기본적으로 흰색 배경; 다른 색상에는 bg_color를 사용하세요.
bg_color	String	None	Hexadecimal color string starting with "#"	단색 배경색, output_format가 jpeg인 경우에만 유효합니다. 예: "#FFFFFF", "#000000".
output_mask_format	String	jpeg	jpeg、png	반환된 마스크 이미지 형식입니다.
timeout	int	10	1-60	API 처리 대기 시간 초과(초), sync=1인 경우에만 유효합니다.

참고: 종횡비를 유지하지 않고 rsz_w 및 rsz_h 배율을 해당 치수로 설정합니다. crop_object는 또한 원래 종횡비를 유지하지 않습니다.

# Async 모드에 대한 응답 예 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcadf7b3b99f4447f9ddce"
    },
    "status": 200,
    "timestamp": 1744512855,
    "trace_id": "ae173819-6fb5-4e88-a587-ff654f2de9bf",
    "message": "ok"
}

# 동기화 모드에 대한 응답 예 (sync=1)

JSON|

{
    "data": {
        "created_at": 1744513021,
        "completed_at": 1744513022,
        "image": "{image oss url}",
        "mask": "{mask oss url}"
    },
    "status": 200,
    "timestamp": 1744513022,
    "trace_id": "3a2a0b4a-8b4a-4034-865a-8a5ebcc7e93c",
    "message": "ok"
}

2、이미지 배경 제거

POST /api/v1/segment/submit

요청 매개변수:

# Async 모드에 대한 응답 예 (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcaec66b4a4af9c824fcd2",
        "created_at": 1744513062,
        "completed_at": 1744513063,
        "status": 2,
        "mask": "{mask oss url}",
        "image": "{image oss url}",
        "result_cnt": 2,
        "results": [
            {
                "task_id": "{task_id_1}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            },
            {
                "task_id": "{task_id_2}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            }
        ]
    },
    "status": 200,
    "timestamp": 1744513180,
    "trace_id": "952a636e-3a9d-4e72-b470-681c61fcd763",
    "message": "ok"
}

매개변수 이름	유형	설명
result_cnt	Number	multi_result=1일 때 반환된 결과 수

매개변수 이름	유형	기본값	선택적 값	설명
task_id	String	None	Valid Task ID	sync=0인 async 모드의 경우 백그라운드 제거 API에 의해 반환된 task_id.

3、사용량조회

GET /api/v1/segment/quota

요청 매개변수: 없음

# 예시 응답

Plain Text|

{
    "data": {
        "used_tasks": 888,
        "remaining_tasks": 88888
    },
    "status": 200,
    "timestamp": 1778555905,
    "trace_id": "b9d83cd6-f220-436f-ac30-52fcd8d5b30a",
    "message": "ok"
}

응답 매개변수

매개변수 이름	유형	설명
image	String	배경 제거 후 이미지의 URL
mask	String($binary)	마스크 이미지의 URL
results	Array	multi_result=1일 때의 결과 배열
result_cnt	Number	multi_result=1일 때 반환된 결과 수
status	String	data.status 작업 상태: 2 완료 1 처리 -1 실패 -2 시간 초과됨
used_tasks	Number	사용된 매트 작업 수
remaining_tasks	Number	남은 사용 가능한 매트 작업 수

상태 코드

HTTP 응답 상태 코드

HTTP 응답 상태 코드	설명
200	요청이 성공했습니다.
400	클라이언트 매개변수 오류입니다. 누락되었거나 잘못된 값을 확인하세요.
401	인증에 실패했습니다. X-API-KEY 및 서비스 활성화를 확인하세요.
404	요청한 URL 또는 리소스가 존재하지 않습니다.
412	업로드된 이미지 URL 또는 파일 유효성 검사에 실패했습니다.
413	업로드한 파일이 크기 제한을 초과했습니다.
429	요청 빈도가 QPS 제한을 초과합니다. 속도를 늦추거나 비즈니스 지원팀에 문의하세요.
500	서버 예외. 비즈니스 또는 기술 지원에 문의하세요.