사용 가이드
flux-3와 HiAPI API로 이커머스 상품 이미지 생성하기
프롬프트 템플릿, 배경 및 조명 제어, 그리고 실행 가능한 상품 이미지 생성 요청
이 페이지에서
flux-3가 이커머스 상품 이미지에 적합한 이유
상품 카탈로그 파이프라인이 실패하는 이유는 대개 지루합니다. 바로 일관성입니다. 상품 페이지에는 메인 이미지 하나가 아니라 여러 SKU, 여러 각도, 계절별 업데이트에 걸친 수십 장의 이미지가 필요하며, 이들 모두가 같은 오후 같은 스튜디오에서 촬영한 것처럼 보여야 합니다. 매 장을 사진작가에게 맡기면 느리고 비쌉니다. 매 장을 아무 이미지 생성기에 맡기면 대개 각각은 그럴듯하지만 함께 놓으면 어색한 이미지 묶음이 나옵니다.
바로 이 지점에서 flux-3가 유용합니다. HiAPI API를 통해 제공되는 이미지 생성 모델이므로, 상품 파이프라인은 이미지 생성을 또 하나의 HTTP 호출로 처리할 수 있습니다. 프롬프트와 상품 파라미터를 보내고, 이미지를 받아 저장한 뒤, 다음 SKU를 처리하면 됩니다. 벤더 전용 SDK도, 모델마다 별도 계정을 만들 필요도, 제공자마다 글루 코드를 작성할 필요도 없습니다.
이커머스에서 특히 중요한 점은 flux-3가 프롬프트 구조에 예측 가능하게 반응한다는 것입니다. 상품 사진은 매우 제약이 많은 장면입니다. 하나의 피사체, 중앙 또는 의도적인 구도, 깨끗한 배경, 스튜디오 스타일 조명이 그것입니다. 이런 제약은 텍스트로 표현할 수 있는 것들이며, 텍스트가 되는 순간 창의적 결정이 아니라 템플릿 변수가 됩니다. 이것이 '모델에게 이미지 한 장을 부탁하는 것'과 카탈로그 작업에서 '생성 단계를 갖는 것'의 차이입니다.
이 가이드의 실제 워크플로는 다음과 같습니다. 재사용 가능한 프롬프트 구조를 정의하고, 배경과 조명 표현을 조정해 기준선이 올바르게 보일 때까지 다듬은 다음, 제품별로 피사체 블록만 교체합니다. 나머지는 모두 그대로 두며, 이것이 한 제품 라인에서 시각적 일관성을 확보하게 해줍니다.
시작하기 전에 준비할 것
- HiAPI API 키와 플랫폼 모델 목록에서 확인한 현재 flux-3 모델 식별자.
- 구조화된 형태의 상품 데이터: 이름, 소재, 색상, 형태, 그리고 모델이 렌더링하길 원하는 두드러진 세부 사항.
- 기준 프롬프트와 생성 결과를 보관할 장소. 나중에 버전을 비교할 수 있어야 합니다.

flux-3 상품 사진 프롬프트의 구성
한 제품에만 통하는 프롬프트는 쓸모가 적습니다. 채워 넣을 수 있는 프롬프트가 유용합니다. 이를 위해 설명을 고정 블록으로 나누고, 각 블록을 코드의 변수 하나에 대응시킵니다.
다섯 개의 블록
- 피사체. 물체가 무엇인지 구체적인 명사로 설명합니다. '멋진 컵'보다 '무광 세라믹 커피 머그'가 낫습니다. 중요한 경우 크기 단서('키가 큰', '넓은 입구')를 추가합니다.
- 소재와 표면. 마감과 질감: 브러시드 알루미늄, 유약 세라믹, 직조 면, 프로스트 유리. 모델의 하이라이트가 여기서 나오므로 명확하게 씁니다.
- 배경. 제품이 놓인 배경과 표면: 심리스 페이퍼, 석재 슬래브, 부드러운 그라데이션, 순백 심리스 배경. 이 블록은 의도적으로 짧고 무미건조하게 유지하세요. 이것은 발판이지 창의적 슬롯이 아닙니다.
- 조명. 방향, 품질, 대비: 왼쪽에서 오는 부드러운 키 라이트, 큰 확산 광원, 은은한 필 라이트, 물체 아래의 미세한 그림자. 이 블록이 '스튜디오' 느낌의 대부분을 결정하며, 가장 많이 조정하게 될 블록입니다.
- 카메라 프레이밍. 렌즈가 장면을 구성하는 방식: 중앙 제품 샷, 눈높이, 3/4 각도, 타이트한 크롭, 위쪽에 충분한 여백.
블록을 템플릿으로 전환하기
이 블록들은 런타임에 하나의 문자열로 조립되며, SKU마다 피사체(때로는 소재)만 교체됩니다:
product photo of {subject}, {material}, {background}, {lighting}, {framing}
채워 넣은 예시:
product photo of a matte ceramic coffee mug, glazed stoneware with visible clay texture,
on a seamless light gray paper backdrop, soft diffused key light from the upper left
with gentle fill and a soft contact shadow, centered eye-level shot with negative space above
템플릿을 안정적으로 유지하는 두 가지 규칙이 있습니다. 첫째, 블록 순서를 고정하세요. 텍스트가 완전히 같더라도 블록을 재배열하면 강조점이 달라집니다. 둘째, SKU 간에 고정 블록을 완전히 동일한 문자열로 유지하고 매번 다시 쓰지 마세요. 미세한 표현 변화가 카탈로그에서 배경과 조명이 불일치하는 가장 흔한 원인입니다.
창의성이 들어가면 안 되는 곳
고정 블록에서는 편집적 언어를 피하세요. 감정 형용사, 스타일링 장식, 장면 언급을 넣지 마세요. 변화가 필요한 부분은 의도적인 캠페인에 맡기고 카탈로그 템플릿은 깨끗하게 유지하세요. 기술 사양처럼 읽히는 템플릿은 기술 사양처럼 보이는 이미지를 만들어냅니다. 바로 이것이 상품 리스팅에 필요한 것입니다.

배경과 조명 제어하기
배경과 조명은 한 묶음의 이미지가 일관된 카탈로그처럼 읽히게 하는지 결정하는 두 블록입니다. 둘 다 구체적이고 물리적인 표현에 잘 반응합니다.
배경: 무미건조함을 추구하세요
배경은 미학이 아니라 물리적 세트로 설명하세요. '심리스 라이트 그레이 페이퍼 배경'과 '순백 인피니티 배경'이 신뢰할 수 있는 이유는 알려진 스튜디오 구성을 설명하기 때문입니다. '미니멀'이나 '미학적' 같은 단어는 모호하며 장면 요소가 스며들게 만듭니다.
유용한 레버:
- 표면 유형: 심리스 페이퍼, 매트 비닐, 천연 석재 슬래브, 밝은 목재.
- 색상과 톤: 라이트 그레이, 오프 화이트, 웜 샌드. 제품 가장자리가 읽히도록 명도를 중간에서 밝게 유지하세요.
- 연속성: '심리스' 또는 '인피니티'는 배경과 바닥이 융합되길 원한다고 모델에 알려주며, 나중에 지우기 어려운 지평선을 없앱니다.
- 비움: 초기 시도에서 잡다한 물체가 나타난다면 '빈 배경, 소품 없음'을 명시적으로 쓰는 것이 좋습니다.
마켓플레이스용 투명 배경 PNG가 필요하다면 깨끗한 단색 배경에서 먼저 생성한 뒤 후처리로 누끼를 따세요. 이미지 모델에 진짜 알파 채널 출력을 요구하는 것은 신뢰할 만한 경로가 아닙니다.
조명: 방향 우선, 품질 다음
조명 표현은 두 가지 결정으로 명확히 나뉩니다. 방향은 하이라이트와 그림자가 어디에 떨어지는지를 정하고, 품질은 그 하이라이트 가장자리가 얼마나 부드러운지를 정합니다.
- 방향: '왼쪽 위에서 오는 키 라이트', '정면에서 오는 부드러운 키 라이트', '오른쪽에서 오는 빛, 왼쪽의 은은한 필 라이트'. 하나를 선택하고 제품 라인 전체에서 유지하세요.
- 품질: '큰 확산 광원', '부드러운 그림자', '균일한 조명'. 확산된 부드러운 빛은 광택 소재를 날려버리지 않으므로 상품 사진의 안전한 기본값입니다.
- 접촉 그림자: '제품 아래의 부드러운 접촉 그림자'는 물체를 바닥에 붙여줍니다. 이것이 없으면 제품이 떠 있는 것처럼 보입니다.
- 대비: '낮은 대비, 밝고 균일함'은 흰 배경 마켓플레이스에 적합하고, 약간 더 방향성 있는 대비는 프리미엄 라이프스타일 크롭에 적합합니다.
제품 라인 일관성 유지하기
일관성은 프롬프트 문제라기보다 버전 관리 문제입니다. 배경과 조명 블록을 이름 있는 프리셋(예: '화이트 스튜디오' 프리셋과 '슬레이트' 프리셋)으로 저장하고, 각 생성 작업에서 SKU별로 텍스트를 붙여 넣는 대신 이름으로 프리셋을 참조하세요. 프리셋을 조정하면 한 번만 조정하면 되고, 다음 배치는 의도적으로 변경을 이어받습니다. 표류하지 않습니다.
결과가 잘못 나오면 한 번에 블록 하나만 바꾸고 같은 제품을 다시 생성하세요. 배경과 조명을 동시에 바꾸면 어떤 표현이 효과를 냈는지 알 수 없습니다.

실행 가능한 flux-3 HiAPI 요청
생성 단계는 API 호출 한 번입니다. 정확한 엔드포인트 경로, 모델 식별자, 요청 필드는 플랫폼에 문서화되어 있으며 변경될 수 있으므로 거기서 확인해야 합니다. 아래 형식은 스크립트에 연결할 패턴입니다.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
presets = {
"white_studio": {
"background": "on a pure white infinity sweep, no props, empty backdrop",
"lighting": "soft diffused key light from the upper left, even fill, "
"soft contact shadow beneath the product, low contrast",
"framing": "centered eye-level product shot, generous negative space",
}
}
def build_prompt(product, preset_name="white_studio"):
p = presets[preset_name]
return (
f"product photo of {product['subject']}, {product['material']}, "
f"{p['background']}, {p['lighting']}, {p['framing']}"
)
def generate(product, preset_name="white_studio"):
payload = {
"model": "flux-3", # confirm the current identifier in the model list
"prompt": build_prompt(product, preset_name),
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations", # see docs for exact path
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
product = {
"subject": "a matte ceramic coffee mug",
"material": "glazed stoneware with visible clay texture",
}
result = generate(product)
print(result)
배치 처리에 연결하기
단일 제품이 아니라 전체 카탈로그에서 안전하게 실행하려면 몇 가지 습관이 필요합니다:
- 모든 값을 환경 변수에서 읽으세요. 키를 소스 코드와 로그에서 멀리 두세요.
- 응답을 신뢰할 수 없는 것으로 취급하세요. 문서화된 필드에서 반환된 이미지 참조나 페이로드를 읽은 뒤 다운로드해 자체 스토리지 버킷에 저장하세요. 임시 URL이 작업보다 오래 유지된다고 의존하지 마세요.
- 정확한 프롬프트 문자열을 각 출력과 함께 기록하세요. 이미지 메타데이터와 함께 저장하세요. 나중에 SKU 1234의 이미지가 왜 다르게 보이는지 묻는다면 답은 기억이 아니라 데이터베이스에 있어야 합니다.
- 일시적 오류에는 백오프 재시도를 사용하고 동시성을 제한해 대량 배치가 속도 제한을 유발하지 않도록 하세요.
- SKU와 프롬프트 버전 기준으로 요청을 멱등하게 유지하세요. 재실행 시 중복이 흩어지는 대신 같은 출력 슬롯을 덮어쓰게 됩니다.
템플릿에서 프로덕션 파이프라인으로 반복하기
처음 검증된 프롬프트는 기준선이지 완성된 자산이 아닙니다. 프로덕션화한다는 것은 파이프라인이 재현하고 감사할 수 있는 것으로 만든다는 뜻입니다.
1단계: 소량 샘플에서 기준선 고정하기
서로 다른 소재 카테고리에서 다섯에서 열 개의 제품을 생성하세요. 광택 제품, 무광 제품, 직물, 금속, 투명 제품 각각 하나씩입니다. 이들은 조명 블록을 서로 다른 방식으로 시험합니다. 이 샘플에서 템플릿이 성립하면 기준선이 생긴 것입니다. 광택 제품이 날아가거나 직물이 평평해 보이면 카탈로그를 다 돌린 뒤가 아니라 지금 해당 블록을 조정하세요.
2단계: 프리셋에 이름을 붙이고 버전 관리하기
프리셋에 명시적인 버전 식별자를 부여하고 변경을 편집이 아니라 새 버전으로 취급하세요. 간단한 white_studio_v1 → white_studio_v2 방식은 이전 프리셋으로 배치를 다시 생성해 비교할 수 있게 하고, '작은 개선'이 절반의 SKU에서 회귀였음이 밝혀졌을 때 롤백할 수 있게 합니다.
3단계: 파이프라인이 읽을 수 있는 곳에 프롬프트 두기
두 계층을 유지하세요. 공유 프리셋 정의(배경, 조명, 프레이밍, 버전)는 한곳에 두고, SKU별 피사체와 소재 필드는 상품 데이터베이스에 둡니다. 그런 다음 생성 코드가 둘을 결합합니다. 이렇게 하면 프리셋 변경이 향후 모든 작업에 전파되고, 피사체 데이터는 여전히 카탈로그 팀이 소유합니다.
4단계: 출력을 체계적으로 비교하기
수십 개의 SKU를 넘으면 나란히 검토하는 방식은 확장되지 않습니다. 더 저렴한 신호:
- 컨택트 시트 검토: 배치를 하나의 그리드 이미지로 이어 붙이고 이상을 훑어보세요. 표류한 배경과 어긋난 프레이밍은 썸네일 크기에서도 즉시 눈에 띕니다.
- 배경 대비 가장자리 샘플링: 이미지 경계 근처에서 픽셀 색상을 샘플링하고, 모서리가 프리셋의 예상 색조와 다른 결과를 표시하세요. 사람의 눈 없이도 가장 흔한 실패인 배경이 조용히 색이 변하는 문제를 잡아냅니다.
- 화면 위치 확인: 제품이 중앙에 있고 위쪽에 여백이 있어야 한다면, 각 이미지에서 피사체 질량의 위치를 측정하고 이상치를 표시하세요.
표시된 것은 검토 대기열로 들어가고, 나머지는 모두 자동으로 게시됩니다.
5단계: 의도적으로 재생성하기
기준선이 안정되면 새 SKU는 프롬프트 문제가 아니라 데이터 문제입니다. 피사체와 소재 필드를 추가하고, 작업을 대기열에 넣고, 자동화가 처리하게 하세요. 재생성 실행은 의도적인 변경(계절 배경, 새로운 조명 변형)에 맡기고, 그럴 때 프리셋 버전을 올리세요.
흔한 함정과 피하는 방법
상품 이미지 생성의 대부분 실패는 같은 몇 가지 문제이며, 각각 프롬프트 측 또는 파이프라인 측 해결책이 있습니다.
배치 내 배경 표류
가장 흔한 불만: 이미지가 개별적으로는 일관되지만 SKU 간에는 다릅니다. 거의 항상 표현 표류가 원인입니다. 누군가 배경 블록을 다시 썼거나, 템플릿이 제품 속성을 그 안에 삽입했기 때문입니다. 해결책: 배경과 조명을 단일 프리셋 소스의 고정 문자열로 두고, 코드에서 조립된 프롬프트가 프리셋 텍스트를 그대로 포함하는지 검증하세요.
잡다한 소품과 장면 요소
모델은 배경을 좋아합니다. 작은 잎 가지, 접힌 천, 탁자 가장자리처럼 보이는 그림자 등을 추가합니다. 비움을 명시적으로 선언하고('빈 배경, 소품 없음'), 장면 언어를 물리적이고 스튜디오에 국한되게 유지하세요. 계속 나타난다면 피사체 설명을 단순화하세요. 피사체 블록의 장식적 형용사가 장면에서 짝을 이루는 장식을 불러오는 경우가 많습니다.
떠 있는 제품
접촉 그림자가 없으면 물체가 배경에 붙은 것처럼 보입니다. 조명 블록에 '제품 아래의 부드러운 접촉 그림자'를 포함하고, 제품이 떠 있지 않고 표면 위에 놓여 있음을 명확히 하세요.
일관되지 않은 프레이밍
크롭을 섞으면 카테고리 페이지가 망가집니다. 프레이밍 블록을 하나의 문구로 고정하고 변하지 않게 하세요. 여러 종횡비가 필요하다면 비율마다 프롬프트하지 말고 같은 구도를 생성한 뒤 후처리로 크롭하세요.
지나치게 상세한 프롬프트
제품 역사, 브랜드, 스토리를 설명하는 긴 프롬프트는 카탈로그 이미지가 아니라 편집적 이미지를 만드는 경우가 많습니다. 템플릿은 촬영 목록처럼 읽혀야 합니다. 결과가 이상하다고 느껴질 때 해결책은 보통 단어를 추가하는 것이 아니라 삭제하는 것입니다.
생성 실패를 코드 결함으로 취급하기
하나의 나쁜 결과는 파이프라인을 다시 작성하라는 신호가 아닙니다. 저장된 정확한 프롬프트 문자열로 재현하고, 블록 하나를 바꾸고, 다시 생성한 뒤 결론을 내리세요. 프롬프트를 각 출력과 함께 기록하는 것이 바로 이것을 가능하게 하며, 가장 먼저 들일 비용이 가장 낮은 습관입니다.
프리셋 하나, 샘플 배치 하나, 이미지마다 저장되는 프롬프트 하나로 시작하세요. 소재 유형 전반에서 기준선이 성립하면 확장하세요.