Bria Eraser API 사용 방법: curl, Python 및 바로 실행 가능한 요청

bria-eraser는 사진에서 객체를 제거합니다. 이미지와 흑백 마스크를 보내면 일치하는 배경으로 마스크 영역을 채웁니다. prompt 필드는 없습니다. 이 가이드에서는 전체 실행 요청, 이를 실행하는 Python 코드, 그리고 자체 마스크가 작동할지 결정하는 세부 사항을 보여줍니다. 대시보드에서 HiAPI key를 받아야 합니다.

최소 요청(curl)

이 모델은 통합 비동기 엔드포인트 POST /v1/tasks를 사용합니다. 아래 두 URL은 모두 공개되어 있으며 작성 시점에 접근 가능합니다:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-eraser",
    "input": {
      "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025379-46c31ddb2b52110d-e1-street-src.png",
      "mask_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025861-e5d2a17ae1d12d41-e1-street-mask.png",
      "mask_type": "manual"
    }
  }'

이 호출은 이미지가 아니라 즉시 작업 id를 반환합니다:

{"code":200,"data":{"taskId":"tk-hiapi-01M5K80RFJN3J788MMJT7YDVNB"},"message":"success"}

data.status가 success가 될 때까지 GET /v1/tasks/<taskId>를 폴링한 다음 data.output[0].url을 읽으세요.

Python: 제출, 폴링, 다운로드

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def erase(image_url: str, mask_url: str, out_path: str) -> str:
    r = requests.post(API, headers=HEADERS, timeout=30, json={
        "model": "bria-eraser",
        "input": {"image_url": image_url, "mask_url": mask_url, "mask_type": "manual"},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: poll the SAME task id again
        if d["status"] == "success":
            img = requests.get(d["output"][0]["url"], timeout=60)
            img.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(img.content)
            return task_id
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(task_id)

작업 id를 보관하세요. 폴링이 한 번 실패하면 해당 id를 다시 폴링하세요. 재제출하지 마세요. 제출할 때마다 별도로 과금되는 작업이 생성되기 때문입니다.

요청 필드

필드	필수 여부	설명
input.image_url	예	공개 http/https URL. JPEG, PNG 또는 WEBP.
input.mask_url	예	원본 이미지와 가로세로 비율이 같은 흑백 이미지. 흰색은 지워지고 검은색은 유지됩니다.
input.mask_type	아니오	manual(기본값)은 브러시로 그린 마스크에, automatic은 분할 도구로 생성한 마스크에 사용합니다.
input.preserve_alpha	아니오	기본값 false. true로 설정하면 알파 채널이 있는 입력의 투명도를 유지합니다.

프로덕션 환경: 콜백 사용

폴링은 테스트에 적합합니다. 서비스에서는 최상위 callback을 전달하여 HiAPI가 작업 완료 시 알려주도록 하세요:

{
  "model": "bria-eraser",
  "input": { "image_url": "...", "mask_url": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

콜백이 유실될 경우를 대비해 폴링을 대체 수단으로 유지하세요. 출력 URL은 만료되므로 작업이 성공하면 가능한 한 빨리 파일을 자체 스토리지에 복사하세요.

실제로 실행하고 확인한 결과

작성 당일 curl 부분의 요청을 한 번 실행하고 완료될 때까지 폴링했습니다.

• 상태 순서: handling → archiving → success. archiving은 작업이 끝난 후 output이 나타나기 전에 표시됩니다. "아직 완료되지 않음"으로 보고 계속 폴링하세요.
• 시간: 작업 생성부터 완료까지 16초가 걸렸습니다. output URL은 그 후 몇 초 뒤에 나타났습니다.
• 출력: temp.hiapi.ai의 PNG, 1360 × 768, 알파 채널 포함. 이는 원본 이미지와 동일한 크기로, 원래 해상도를 유지한다는 문서 설명과 일치합니다.
• 과금: 제가 확인했을 때 공개 가격 데이터에서 이 모델의 가격은 이미지당 $0.0575였습니다. 현재 가격은 가격에서 확인하세요.
• 검증 오류: mask_type: "bogus"를 보내는 것을 일부러 테스트했습니다. API는 HTTP 400으로 거부했습니다:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: mask_type: value must be one of 'manual', 'automatic'"}

저는 한 장의 이미지에서 하나의 요청만 확인했습니다. 다른 마스크 스타일, 매우 큰 이미지, 또는 이미지와 가로세로 비율이 다른 마스크는 테스트하지 않았습니다. 이러한 경우에 대한 아래 설명은 제 테스트가 아니라 모델 문서에서 가져온 것입니다.

마스크 팁(문서 기준)

• 객체 가장자리에서 조금 더 넓게 칠하세요. 윤곽에 딱 맞는 마스크는 원본 객체 주변에 광晕을 남기는 경우가 많습니다.
• 마스크는 사진과 동일한 가로세로 비율을 유지하세요. 문서에서 요구하지만 그렇지 않을 경우 어떻게 되는지는 설명하지 않습니다.
• 분할 또는 매팅 도구에서 생성한 마스크에만 automatic을 사용하세요. 브러시 마스크에는 manual을 사용합니다.

어느 페이지를 읽어야 할까요?

이 가이드는 전용 엔드포인트를 사용한 마스크 기반 제거를 다룹니다. 범용 이미지-투-이미지 모델을 사용한 프롬프트 기반 편집은 이미지 인페인팅 및 객체 제거를 참고하세요. 단일 객체가 아닌 전체 배경을 제거하려면 배경 제거 가이드를 참고하세요. 모델 페이지는 bria-eraser에, 필드 참조는 API 문서에 있습니다.

자주 묻는 질문

bria-eraser에 프롬프트가 필요한가요?

아니요. 문서에 프롬프트가 필요 없다고 나와 있으며, 제가 실행한 요청에는 이미지, 마스크, mask_type만 포함되었습니다.

마스크에서 어떤 색상이 제거되나요?

흰색은 지워지고 검은색은 유지됩니다.

출력이 입력보다 작나요?

제 실행에서 출력은 1360 × 768로 원본 이미지와 완전히 동일했습니다.

폴링과 콜백 중 무엇을 사용해야 하나요?

테스트에는 폴링을 사용하세요. 프로덕션에서는 callback.url과 when: "final"을 사용하고, 폴링을 대체 수단으로 두세요.