이커머스 제품 이미지를 위한 FLUX 1.1 Pro: hiapi API 가이드

온라인에서 물건을 판다면 이 계산은 이미 알고 있을 것입니다. 제품 상세 페이지 하나에 흰 배경 이미지 하나, 라이프스타일 장면 이미지 하나, 되면 다각도 이미지 세트까지 필요합니다. SKU마다, 색상마다 말이죠. 스튜디오 촬영으로는 하루에 제품 열 개를 겨우 처리하지만, 이미지 API는 천 개를 처리합니다.

flux-1.1-pro(Black Forest Labs의 FLUX.1.1 [pro])는 hiapi의 사실감 담당 주력 모델입니다. 브러시드 메탈, 유리, 직물, 부드러운 보케 같은 설득력 있는 질감을 렌더링하며, 요금은 이미지당 $0.05로 일괄 적용됩니다. 이 가이드는 바로 실무에 적용할 수 있는 이커머스 레시피입니다. 아래의 모든 이미지는 바로 위에 그대로 인쇄된 프롬프트로 생성되었으며, 복사해서 붙여넣으면 바로 쓸 수 있는 동일한 /v1/tasks 호출을 사용했습니다. 그리고 저희는 실제 파라미터 범위를 기록했습니다. 존재할 것처럼 보이지만 전송하면 400을 반환하는 파라미터까지 포함해서요.

60초 만에 API 이해하기

hiapi에서 flux-1.1-pro는 비동기 작업 엔드포인트에서 실행됩니다. 작업을 만들고, 폴링하고, 결과를 다운로드하면 됩니다:

# 1. Create the task
curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "input": {
      "prompt": "Studio packshot of an unbranded stainless steel wristwatch...",
      "aspect_ratio": "1:1",
      "output_format": "jpg",
      "seed": 6607
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01KWK3JG..."},"message":"success"}

# 2. Poll until status is "success" (typically 10–40s for flux-1.1-pro)
curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWK3JG... \
  -H "Authorization: Bearer $HIAPI_API_KEY"

# 3. Download output[0].url — it carries an expireAt timestamp,
#    so save the file to your own storage immediately.

본론으로 들어가기 전에 운영상 주의할 점 두 가지를 기억하세요:

• 출력 URL은 임시입니다. 작업이 성공하면 즉시 다운로드해서 직접 다른 곳에 저장하세요. 자세한 내용은 hiapi 출력 URL이 만료되면 무슨 일이 일어나는가를 참고하세요.
• 작업이 processing 상태에 예상보다 오래 머무른다면, 무작정 다시 제출하지 마세요. 멈추거나 시간 초과된 작업 진단 가이드가 있습니다.

실제 파라미터 범위(그리고 추측하다 마주치는 400)

다른 플랫폼에서 FLUX 모델을 써봤다면 steps와 guidance를 조정하려는 습관이 나올 것입니다. 하지만 hiapi의 flux-1.1-pro 작업 스키마에는 이 필드들이 존재하지 않습니다. API는 입력을 엄격하게 검증하고 알 수 없는 속성을 거부합니다:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'steps', 'guidance' not allowed"
}

이것은 버그가 아닙니다. FLUX 1.1 [pro]는 호스팅 엔드포인트로 제공되며, 샘플링 내부 메커니즘은 제공자가 고정합니다. 다음은 운영 스키마로 검증된, 실제로 전송할 수 있는 항목입니다:

필드	타입	허용 값 / 범위
prompt	string	필수
aspect_ratio	string	1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 4:5, 5:4, custom
width, height	integer	256–1440 px(가로세로 비율 대신 사용하거나 custom 가로세로 비율과 함께 사용)
seed	integer	임의의 정수 — 구도를 고정해 재현성 확보
output_format	string	jpg, png, webp
prompt_upsampling	boolean	백엔드가 프롬프트를 재작성/확장하도록 함
safety_tolerance	integer	0–6

제품 이미지를 위한 실용적인 기본값은 다음과 같습니다: output_format: "jpg", 노출 위치에 맞는 명확한 aspect_ratio(쇼핑몰 그리드에는 1:1, 피드/라이프스타일 장면에는 4:5, 배너에는 3:2 또는 1440×960), SKU 시리즈마다 하나의 seed 고정, 그리고 prompt_upsampling은 꺼두기 — 이커머스에서는 모델이 임의로 덧붙이지 않고 당신의 표현을 그대로 따르길 원하기 때문입니다.

레시피 1 — 깔끔한 흰 배경 이미지

가장 기본적인 이미지입니다. 제품 하나, 이음새 없는 배경, 부드러운 주광. 배경색을 명확히 지정하고 바닥 반사를 요구하세요. 그리고 어떤 사실적 모델에서든 중요한 점인데, 반드시 "브랜드 없음, 로고 없음, 텍스트 없음"을 써넣으세요. 다이얼과 라벨은 FLUX가 상표 모양의 낙서를 만들어낼 수 있는 바로 그 지점이며, 그렇지 않으면 나중에 후보정으로 지워야 합니다.

Studio packshot of an unbranded stainless steel wristwatch with a plain deep green dial and brushed metal bracelet, the dial completely clean with simple baton hour markers and no logo, no brand name, no text or numerals anywhere, standing upright on a seamless light grey background, centered composition, soft diffused key light from the upper left, subtle reflection beneath the watch, photorealistic e-commerce product photography

전송할 때는 aspect_ratio: "1:1", seed: 6607을 사용하세요. 브러시드 메탈 질감과 부드러운 바닥 반사가 바로 전문가급 $0.05를 지불해서 얻는 것입니다. 저렴한 모델은 바로 이런 세부 묘사를 평평하게 눌러버립니다.

레시피 2 — 라이프스타일 장면 이미지

쇼핑몰 그리드에는 흰 배경 이미지가 필요하지만, 제품 페이지와 소셜 미디어는 장면으로 전환을 이끌어냅니다. 제품을 장면 안에 배치하고, 라벨은 비워두고, 얕은 피사계 심도로 "고급감"을 전달하세요. 4:5는 피드 크롭에 맞습니다.

A lit soy candle in a clear glass jar with a plain blank kraft-paper label, on a rustic oak nightstand next to a stack of two linen-bound books, warm evening window light, softly blurred bedroom background, cozy lifestyle product photography for an online store, photorealistic

전송할 때는 aspect_ratio: "4:5", seed: 7301을 사용하세요. 빈 라벨이 보존된 점에 주목하세요. 바로 여기에 나중에 실제 브랜드 그래픽을 합성할 수 있습니다.

레시피 3 — 고정 seed를 이용한 색상 변형

카탈로그 제작에서 가장 비용을 아끼는 요령입니다. seed는 노이즈 초기화를 고정하므로, seed와 프롬프트 구조를 완전히 동일하게 유지하고 색상 단어만 바꾸면 새로운 색상에서도 같은 구도를 얻을 수 있습니다. 재촬영도 필요 없고, img2img 워크플로도 필요 없습니다.

아래 두 이미지는 모두 seed: 5150, aspect_ratio: "1:1"을 사용하며, 프롬프트는 정확히 두 단어만 다릅니다(navy blue → coral pink):

A single insulated stainless steel water bottle in matte navy blue, standing on a round travertine stone slab against a soft warm beige studio background, centered, soft diffused lighting, minimalist e-commerce product photo, photorealistic

같은 병 실루엣, 같은 석판, 같은 구도이지만 다른 SKU입니다. 이것이 고정 seed 프롬프트가 하루치 변형 촬영을 대신하는 방식입니다.

배치: SKU별로 카탈로그 전체 렌더링

다음은 저희가 실제로 돌린 패턴입니다: 제출, 폴링, 다운로드, 재시도. 운영 실행에서 미리 계획해야 할 점이 하나 드러났습니다. flux-1.1-pro 작업이 가끔 일반적인 {"code": "TASK_FAILED"}로 실패합니다. 이는 일시적이며, 동일한 입력으로 다시 제출하면 보통 성공합니다. 이미지마다 최대 3회 시도를 예약하세요(성공적으로 렌더링된 이미지에만 요금이 부과됩니다).

import json, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_HIAPI_KEY",
           "Content-Type": "application/json"}

CATALOG = [
    {"sku": "bottle-navy",  "colour": "matte navy blue"},
    {"sku": "bottle-coral", "colour": "matte coral pink"},
    {"sku": "bottle-sage",  "colour": "matte sage green"},
]
TEMPLATE = ("A single insulated stainless steel water bottle in {colour}, "
            "standing on a round travertine stone slab against a soft warm "
            "beige studio background, centered, soft diffused lighting, "
            "minimalist e-commerce product photo, photorealistic")

def render(prompt, seed, retries=3):
    for attempt in range(retries):
        task = requests.post(API, headers=HEADERS, json={
            "model": "flux-1.1-pro",
            "input": {"prompt": prompt, "aspect_ratio": "1:1",
                      "output_format": "jpg", "seed": seed},
        }).json()
        task_id = task["data"]["taskId"]
        while True:
            state = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
            if state["status"] == "success":
                return requests.get(state["output"][0]["url"]).content
            if state["status"] == "fail":          # transient TASK_FAILED happens;
                break                              # resubmit with the same input
            time.sleep(5)
    raise RuntimeError(f"gave up after {retries} attempts")

for item in CATALOG:
    img = render(TEMPLATE.format(colour=item["colour"]), seed=5150)
    with open(f"{item['sku']}.jpg", "wb") as f:
        f.write(img)                               # re-host immediately; task URLs expire
    print(item["sku"], "done")

수백 개의 SKU를 푸시해야 한다면 제출 속도를 제어하세요. 이미지 API 속도 제한 상세 설명에서 제한 동작과 적절한 동시성 수준을 다룹니다.

가격 및 flux-1.1-pro를 선택할 시점

hiapi 가격 페이지에서 확인한 내용:

모델	이미지당 가격	적합한 용도
flux-schnell/text-to-image	$0.005	초안, 레이아웃 구도, 대량 썸네일
flux-1.1-pro	일괄 $0.05	사실적 흰 배경 이미지 및 라이프스타일 장면 이미지, 최대 1440px 임의 해상도
flux-2/text-to-image	$0.0375–$0.125 (MP 기준)	최고 수준의 프롬프트 준수, 이미지 내 텍스트 선명도

일괄 가격은 조용한 강점입니다. 1440×960 메인 비주얼 배너와 512×512 썸네일이 똑같이 $0.05인 반면, flux-2는 메가픽셀 단위로 과금합니다. 워크로드가 "사실적 제품 이미지, 다양한 크기"라면 flux-1.1-pro가 비용을 예측할 수 있는 기본 선택입니다. 정확한 객체 수나 이미지 안에서 읽을 수 있는 인쇄 텍스트가 필요하다면 flux-2로 업그레이드하세요. 같은 이커머스 레시피로 실행해 본 결과가 여기 있습니다.

다섯 장 이미지로 구성된 PDP(메인 이미지, 흰 배경 이미지, 라이프스타일 장면 이미지, 색상 변형 두 개)는 제품당 총 $0.25입니다. 200개 SKU 카탈로그를 새로고침하는 비용: $50, 반나절, 스크립트 하나.

정리

hiapi의 flux-1.1-pro는 두 번의 호출로 이루어지는 비동기 워크플로로 사실적인 제품 이미지를 제공합니다. 엄격하지만 단순한 파라미터 범위(가로세로 비율, 크기, seed, 포맷 — steps/guidance를 조정할 필요 없음), 고정 seed 색상 변형, 그리고 카탈로그 예산을 매우 예측 가능하게 만드는 일괄 $0.05 가격입니다. API 키를 발급받고 flux-1.1-pro 모델 페이지에서 시작해, 위의 curl 호출로 첫 번째 흰 배경 이미지를 렌더링하세요. 커피가 식기 전에 PDP에 바로 올릴 수 있는 이미지가 나옵니다.