이미지 복원 및 객체 제거 API: HiAPI에서 프롬프트로 이미지 편집하기

요약

• HiAPI에서 사진의 객체 제거는 명령형 편집입니다. 이미지를 전송하고 제거할 대상을 설명하세요. 범용 이미지-투-이미지 모델은 마스크를 받지 않습니다.
• 적합한 시작점: flux-2/image-to-image(1K에서 $0.035, aspect_ratio: "auto"와 함께 사용하면 구도 유지), gpt-image-2/image-to-image(1K에서 $0.03, 이미지 필드는 input_urls), seedream-4.5/image-to-image($0.045, 최대 4K 지원), 그리고 qwen-image-3.0/image-to-image($0.0358).
• 마스크 기반 인페인팅 모델 FLUX.1 Fill Pro는 HiAPI에 출시 예정으로 등록되어 있습니다. 공개되기 전까지는 프롬프트가 곧 마스크입니다.

같은 사진, 같은 지시, 두 개의 모델

원본 이미지: 제품 사진이며, 가격표를 제거하려고 합니다.

Remove the coral price tag and its string from the bottle. Rebuild the bottle surface and the gray background that were behind it. Keep the bottle, lighting, shadow and everything else unchanged.

gpt-image-2/image-to-image, resolution 1K, 1254×1254, 112초, $0.03.

가격표와 그 끈이 사라졌습니다. 가격표에 가려져 있던 물병 표면이 재구성되었고, 곡률과 반사광이 원본과 일치하며 회색 배경에 보정 흔적이 남지 않았고, 병뚜껑, 병 밑면, 그림자도 원본과 일치합니다.

같은 요청을 flux-2/image-to-image에도 보냈습니다. 해당 작업은 16초 후 fail로 종료되었고, 사유는 TASK_FAILED뿐이었으며 비용은 환불되었습니다. 한 번의 실패로 모델 자체를 평가할 수는 없지만, 코드에서 fail을 처리하고 두 번째 모델로 재시도해야 한다는 점을 알려줍니다.

어떤 모델을 써야 할까

모델 ID	이미지 필드	원본 구도 유지	출력 크기	가격
flux-2/image-to-image	image_urls (1–8)	예, aspect_ratio: "auto"	resolution 1K / 2K	1K에서 $0.035
gpt-image-2/image-to-image	input_urls (1–16)	예, aspect_ratio: "auto" (기본값)	resolution 1K / 2K / 4K	1K에서 $0.03
qwen-image-3.0/image-to-image	image_urls (1–3)	아니요, 8가지 비율 중 선택 필요	resolution 1K / 2K	$0.0358
seedream-4.5/image-to-image	image_urls (1–14)	아니요, 8가지 비율 중 선택 필요	resolution 2K / 4K	$0.045
seedream-5.0-pro/image-to-image	image_urls (1–10)	아니요, 7가지 비율 중 선택 필요	resolution 1K / 2K	1K에서 $0.06

HiAPI 실시간 가격, 2026년 10월 20일 조회 기준. 실패한 작업은 과금되지 않습니다.

• 객체 제거의 기본 선택: aspect_ratio: "auto"를 지원하는 모델을 사용하면 출력이 사진의 형태를 유지하므로 원래 위치에 그대로 되돌려 놓을 수 있습니다.
• 대형 인쇄 또는 확대 가능한 제품 페이지: Seedream 4.5는 4K 출력 가격이 2K와 동일합니다.
• 배경만 제거하면 되는 경우: 851-labs/background-remover(이미지당 $0.002) 같은 전용 도구를 사용하세요. image_url 하나만 필요하고 프롬프트는 필요 없습니다.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Remove the white delivery van parked on the right. Rebuild the storefront and sidewalk behind it. Keep everything else unchanged.",
      "image_urls": ["https://your-cdn.example.com/street.jpg"],
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }'

taskId를 받게 됩니다. data.status가 success가 될 때까지 GET https://api.hiapi.ai/v1/tasks/{taskId}를 폴링한 다음 data.output[0].url을 다운로드하세요. 원본 이미지는 공개 URL에 있어야 하며, 모델이 서버 측에서 가져옵니다.

Python: 모든 모델에 적용되는 하나의 함수

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

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

def edit(model, timeout_s=300, **inp):
    r = requests.post(API, json={"model": model, "input": inp}, headers=H, timeout=30).json()
    if r.get("code") != 200:
        raise RuntimeError(r)  # a 400 lists every invalid field at once
    task_id = r["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return requests.get(d["output"][0]["url"], timeout=120).content
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(4)
    raise TimeoutError(task_id)

prompt = ("Remove the tourists from the plaza. Extend the paving stones and the fountain base. "
          "Keep the buildings, light and everything else unchanged.")
src = "https://your-cdn.example.com/plaza.jpg"

# FLUX.2 keeps the source shape
img = edit("flux-2/image-to-image", prompt=prompt, image_urls=[src], aspect_ratio="auto", resolution="1K")

# GPT Image 2: note the field name is input_urls
img = edit("gpt-image-2/image-to-image", prompt=prompt, input_urls=[src], resolution="1K")

# Seedream 4.5 at 4K: aspect_ratio and resolution are required
img = edit("seedream-4.5/image-to-image", prompt=prompt, image_urls=[src], aspect_ratio="3:2", resolution="4K")

with open("plaza-clean.png", "wb") as f:
    f.write(img)

제거 프롬프트 작성하기

마스크가 없으면 프롬프트가 무엇을 제거하고 무엇을 유지할지 명확히 설명해야 합니다:

1. 대상과 위치를 명시하세요. "오른쪽에 주차된 흰색 배송 밴"이 "그 밴"보다 효과적입니다.
2. 빈 공간을 무엇으로 채울지 설명하세요. "그 뒤의 상점가와 인도를 재구성하세요."
3. 나머지 모든 것을 고정하세요. "조명, 색상 및 기타 모든 것을 변경하지 마세요"로 끝내면 모델이 사진 전체의 스타일을 다시 조정하지 않습니다.

같은 패턴이 관련 작업에도 적용됩니다:

• 지우고 채우기: "하늘을 가로지르는 전선을 제거하세요. 그라데이션과 일치하는 맑은 하늘로 채우세요. 다른 모든 것은 그대로 두세요."
• 교체: "종이 커피컵을 흰색 도자기 머그로 바꾸세요. 조명과 그림자를 맞추세요. 다른 모든 것은 그대로 두세요."
• 복원: "이 스캔한 사진의 왼쪽 아래 모서리가 손상되었습니다. 사라진 잔디와 길을 재구성하세요. 나머지 부분은 변경하지 마세요."
• 여러 객체: "벤치 옆의 쓰레기통과 교통콘 두 개를 제거하세요. 각 영역을 배경으로 채우세요. 다른 모든 것은 그대로 두세요."

대규모 정리의 경우 호출당 한 번만 제거하고 순차적으로 연결하세요. 각 결과를 자체 스토리지에 저장하고 해당 URL을 다음 호출에 전달하세요. HiAPI의 출력 링크는 작업 완료 후 약 7일이 지나면 만료됩니다.

마주치게 될 오류

이 오류들은 제출 시 모두 HTTP 400이므로 작업이 생성되지 않고 과금도 되지 않습니다:

• additional properties 'mask_url' not allowed(또는 mask): 이 모델들은 마스크를 받지 않습니다. 프롬프트로 영역을 설명하세요.
• input_urls: missing required field "input_urls": gpt-image-2/image-to-image에 image_urls를 보냈습니다.
• additional properties 'quality' not allowed: Seedream 5.0 Pro는 quality가 아니라 resolution(1K 또는 2K)을 사용합니다.
• aspect_ratio: value must be one of ...: auto는 FLUX.2, GPT Image, Grok Imagine에 적용되며 Seedream이나 Qwen에는 적용되지 않습니다.

작업이 fail로 종료되면 data.error를 확인하세요. 흔한 원인은 모델이 원본 URL을 가져오지 못하는 것입니다.

자주 묻는 질문

HiAPI에 마스크 기반 인페인팅 API가 있나요?

현재 범용 용도로는 제공되지 않습니다. 이미지와 흑백 마스크를 받는 FLUX.1 Fill Pro는 출시 예정으로 등록되어 있습니다. 위의 모델들은 프롬프트로만 편집합니다.

객체 제거에 가장 적합한 모델은 무엇인가요?

원본 구도를 유지할 수 있는 모델부터 시작하세요: flux-2/image-to-image 또는 aspect_ratio: "auto"를 함께 사용하는 gpt-image-2/image-to-image. GPT Image 2는 위 예제를 깔끔하게 처리했습니다. 모델을 선택하기 전에 자신의 사진 몇 장으로 두 모델을 비교해 보세요.

한 번의 호출로 여러 객체를 제거할 수 있나요?

네, 하나의 프롬프트에 나열하세요. 호출당 이미지 한 장이 반환됩니다. 결과에서 일부가 누락되면 출력에 다시 한 번 실행하세요.

편집한 이미지를 상업적으로 사용할 수 있나요?

생성된 출력은 요금제의 이용약관을 따릅니다. 편집한 원본 사진에 대한 권리는 여전히 본인에게 있어야 합니다.

더 많은 편집 프롬프트: Seedream 4.5 프롬프트 레시피 및 Qwen Image 3.0 API 가이드.