Recraft 배경 제거 API: 실행 가능한 예제

대부분의 배경 제거 API는 범용 이미지 편집 모델을 고르고 적절한 프롬프트로 피사체를 추출하도록 유도해야 합니다. recraft/remove-background는 이 단계를 생략합니다. 전용 모델로서 이미지 URL을 받아 머리카락과 털 수준의 가장자리 디테일을 보존한 투명 PNG를 반환합니다. 프롬프트도, 네거티브 프롬프트도, 강도 파라미터도 없습니다 — 소스 이미지를 입력하면 누끼 결과가 출력됩니다.

이 가이드는 한 번의 완전하고 테스트된 호출을 살펴봅니다: 요청 구조, 실제로 받게 되는 응답, 그리고 배치 작업이 경계 상황 하나 때문에 멈추지 않게 해주는 프로덕션 수준 패턴(콜백, 멱등성, 오류 처리)입니다.

사전 조건:

• 콘솔에서 hiapi API 키 발급
• Python 3.9+ 및 requests 설치(pip install requests), 또는 curl 직접 사용
• 소스 이미지가 공개 URL에 있어야 함 — hiapi 작업 API는 파일 업로드가 아니라 URL로 이미지를 가져옵니다. 형식은 PNG, JPG 또는 WEBP, 최대 5MB, 최대 1600만 픽셀, 가로·세로 모두 256~4096픽셀.

요청

hiapi의 모든 생성 모델과 마찬가지로 recraft/remove-background는 공유 비동기 작업 API를 통해 동작합니다. POST /v1/tasks에 model과 input을 담아 보내면 즉시 taskId를 받고, 누끼는 백그라운드에서 실행됩니다. 전체 계약 — 요청 헤더, 멱등 키, 상태 코드 — 은 작업 생성에 통합 문서화되어 있으며, 모델별 부분은 input이고 이 모델에서는 필드가 하나뿐입니다:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft/remove-background",
  "input": {
    "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg"
  }
}'

import requests

payload = {
    "model": "recraft/remove-background",
    "input": {
        "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg",
    },
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())
# {"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

image_url은 이 모델이 받는 유일한 필드입니다 — format, response_format, 크기 파라미터가 없습니다. 다른 것을 보내면 API가 모델에 도달하기 전에 스키마 오류로 요청 전체를 거부합니다(아래 오류 참조). 출력은 항상 투명 PNG입니다.

결과 폴링

위 응답의 taskId를 가져와 GET /v1/tasks/{taskId}를 폴링하면서 data.status가 종료 상태에 도달할 때까지 기다립니다. 상태 열거형은 플랫폼의 모든 모델에서 동일합니다: queued → handling → archiving → success(또는 fail). 이 모델의 실제 실행은 보통 10초 이내에 완료됩니다:

import time

task_id = response.json()["data"]["taskId"]

while True:
    r = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    data = r.json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

print(data)

상태가 success이면 data.output은 요소가 하나뿐인 배열입니다:

{
  "status": "success",
  "output": [
    {
      "artifactId": "119426",
      "type": "image",
      "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M1RYTHQ5F94S2405YSC65EWM-0.png",
      "expireAt": 1789222580
    }
  ]
}

url은 임시 링크입니다 — expireAt은 대략 일주일 뒤의 Unix 타임스탬프이며 영구 CDN 주소가 아닙니다. 작업이 성공하자마자 바이트를 다운로드해 자체 스토리지에 저장하세요:

image_bytes = requests.get(data["output"][0]["url"]).content
with open("cutout.png", "wb") as f:
    f.write(image_bytes)

프로덕션 수준 패턴

루프 폴링 대신 콜백을 사용하세요. 생성 시 callback.url을 전달하면 hiapi가 작업 완료 시 최종 결과를 POST로 보내주므로 폴링 루프에서 요청을 소모하지 않아도 됩니다:

payload = {
    "model": "recraft/remove-background",
    "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
    "input": {"image_url": "https://your-cdn.example.com/product-01.jpg"},
}

when: "final"은 종료 상태(success 또는 fail)일 때 콜백을 한 번만 받는다는 뜻이며, 중간 상태마다 받지 않습니다. 제품 사진 배치에서는 이게 적절한 기본 설정이며, 이미지마다 폴링 루프를 유지할 필요가 없습니다.

멱등성. 요청이 클라이언트 쪽에서 타임아웃됐지만 실제로 hiapi에 도달한 경우, 동일한 Idempotency-Key 헤더로 재시도하면(작업 생성에 문서화) 원래 작업을 반환하며 두 번째 누끼에 과금하지 않습니다. 네트워크 오류 시 재시도하는 모든 배치 작업에 설정할 가치가 있습니다.

오류 — 한 가지가 아닌 두 가지 형태. 형식이 잘못된 요청과 인증 실패는 서로 다른 응답 봉투로 반환되므로, 둘 중 하나만 검사하는 코드는 다른 하나를 조용히 삼켜버립니다:

// 입력 오류(schema 검증) — HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// API key 유효하지 않음 또는 만료됨 — HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

먼저 error_code를 확인하고, 없으면 error.code로 대체하세요 — 모든 실패가 동일한 최상위 키를 가진다고 가정하지 마세요.

가격. 이미지당 $0.01(20 크레딧)이며, 입력 해상도와 무관하게 단일 가격입니다. 현재 가격은 항상 가격 페이지에 있습니다.

누끼가 아니라 배경 교체가 필요할 때

recraft/remove-background는 투명 누끼만 생성합니다 — 채우기나 장면은 없습니다. 목표가 같은 호출에서 스튜디오 배경이나 라이프스타일 장면으로 바꾸는 것이라면 다른 작업입니다: 피사체를 보존한 채 주변 배경을 재생성하도록 프롬프트하는 이미지-투-이미지 모델을 사용하세요. 해당 방법과 일반 누끼보다 더 높은 비용을 지불할 가치가 있는 경우는 API로 이미지 배경 제거: 프롬프트 기반 편집에서 확인하세요.

자주 묻는 질문

recraft/remove-background는 프롬프트나 강도 파라미터를 받나요? 아니요. 스키마는 엄격합니다 — image_url이 유일하게 허용되는 필드입니다. format이나 response_format 같은 추가 필드를 보내면 "additional properties not allowed" 메시지와 함께 400이 반환됩니다.

어떤 이미지 형식과 크기를 지원하나요? 입력: PNG, JPG 또는 WEBP, 최대 5MB, 최대 1600만 픽셀, 가로·세로 모두 256~4096픽셀. 출력은 항상 알파 채널을 포함한 PNG입니다.

URL 대신 로컬 파일을 업로드할 수 있나요? 아니요 — image_url은 hiapi 서버가 가져올 수 있는 공개 http(s):// URL이어야 합니다. 먼저 객체 스토리지나 CDN에 업로드하세요.

출력 URL은 얼마나 유효한가요? 각 출력 항목의 expireAt 필드는 Unix 타임스탬프로 보통 약 일주일 뒤입니다. 임시 링크로 취급하여 작업 성공 후 즉시 바이트를 자체 스토리지로 복사하세요 — temp.hiapi.ai 링크를 장기 보관하지 마세요.

수백 장의 제품 사진 배치 처리에 적합한가요? 예 — 이미지마다 작업을 제출하고 하나의 callback.url을 공유하여 hiapi가 결과를 푸시하도록 하면 개별 폴링이 필요 없습니다. 이미지당 $0.01로 계산하면 1,000장 카탈로그 처리 비용은 생성에 $10입니다.