블로그

사용 가이드

muse-image-1.0/text-to-image 전자상거래 제품 이미지: 개발자 워크플로 가이드

HiAPI API를 통한 각도와 조명 프롬프트 템플릿, 크기 선택, 배치 요청

Nov 9, 2026
거의 검은색에 가까운 짙은 초록 배경 위에서 열린 격자 구조를 이루는, 서로 교차한 납작한 황동색과 짙은 초록색 리본 — 이 가이드의 커버 아트.
이 페이지에서

text-to-image가 전자상거래 제품 워크로드에 적합한 이유

카탈로그 작업은 본질적으로 반복적입니다. 같은 제품을 몇 가지 각도에서, 같은 조명으로, 같은 배경 위에, 몇 가지 크기로 촬영합니다. 이러한 반복성은 바로 text-to-image 모델이 잘 처리하는 영역입니다. 주력 제품의 스튜디오 촬영을 대체하는 것이 아니라, 카탈로그의 롱테일 부분을 저비용으로 일관성 있게 채우는 용도입니다.

생성 기술이 실제로 가치를 발휘하는 상황:

  • 대량 변형. 색상 구성, 미세한 SKU 차이, 패키지 리뉴얼 등 재촬영 비용이 이미지 자체의 가치보다 큰 경우.
  • 플레이스홀더 및 출시 전 소재. 최종 촬영 소재가 준비되기 전에 실제처럼 보여야 하는 목록 페이지, 내부 검토 자료, A/B 테스트.
  • 구도 탐색. 사진작가와 스튜디오 일정을 투입하기 전에 탑다운 플랫레이와 45도 히어로 컷의 효과를 먼저 시험.

부적합한 상황: 규제 대상 홍보 문구, 정확하게 읽혀야 하는 패키지 텍스트, 고객이 정교한 소재 질감을 비교하는 히어로 이미지. 이런 작업은 여전히 카메라와 사람이 필요합니다.

개발자 입장에서 사고 모델은 하나의 파이프라인입니다. 구조화된 제품 설명을 입력하고, 프롬프트 템플릿을 렌더링하고, 모델이 하나 이상의 이미지를 반환하면, QA 검토가 어떤 항목을 상점에 게시할지 결정합니다. 아래 각 섹션은 이 파이프라인을 똑똑하게 만드는 대신 평범하고 재현 가능하게 만드는 방법을 다룹니다.

카탈로그 파이프라인은 평직 직조와 같습니다. 하나의 프롬프트가 격자 구조로 들어가고, 같은 구조가 여러 개의 개별 제품 이미지를 만들어냅니다.

HiAPI를 통한 muse-image-1.0/text-to-image 호출

모든 요청은 동일한 HiAPI 인터페이스를 통과하므로, 한 번만 인증하면 호출하는 모든 모델에 대해 하나의 클라이언트를 유지할 수 있습니다. 모델 식별자는 muse-image-1.0/text-to-image이며, 요청에는 프롬프트, 출력 크기 선택, 그리고 고정하려는 모든 단일 생성 옵션이 포함됩니다.

구조적 관점에서 단일 생성은 다음과 같습니다. 요청 페이로드를 구성하고, HiAPI 클라이언트를 통해 POST로 전송하고, 반환된 결과 객체를 읽고, 이미지 참조를 해당 제품 ID와 함께 영속화합니다. 첫 호출부터 들여야 할 두 가지 습관:

  1. 프롬프트를 요청 안에 인라인하지 말고 변수에 저장하세요. 수백 번 재사용하고 비교하게 됩니다.
  2. 모든 출력에 대해 정확히 렌더링된 프롬프트를 기록하세요. 3주 후 이미지에 문제가 보일 때, 프롬프트가 유일한 디버깅 근거입니다.
import os
from hiapi import HiAPI

client = HiAPI(api_key=os.environ["HIAPI_API_KEY"])

prompt = render_product_prompt(product, angle="three-quarter", light="softbox-left")

result = client.images.generate(
    model="muse-image-1.0/text-to-image",
    prompt=prompt,
    size="1024x1024",
)

save_asset(product_id=product.id, angle="three-quarter", result=result)

size를 사후 고려 사항이 아니라 템플릿의 일부로 취급하세요. 동일한 프롬프트라도 다른 종횡비에서 피사체 구도가 바뀔 수 있습니다. 이어지는 섹션은 프롬프트 구조와 크기 결정을 함께 다룹니다.

요청은 클라이언트에서 엔드포인트를 거쳐 모델에 도달하고, 엮인 리본이 하나의 이미지 결과를 반환합니다.

일관된 촬영 각도를 위한 프롬프트 템플릿

카탈로그의 일관성은 소수의 슬롯만 교체하는 고정된 프롬프트 골격에서 나옵니다. 모든 프롬프트를 처음부터 작성하면 이미지마다 편차가 생깁니다. 촬영 유형별로 템플릿을 만들고, 카메라 설명 언어는 모든 제품에 걸쳐 바이트 단위로 동일하게 유지하세요.

사용 가능한 골격:

{subject_block}. {camera_block}. {light_block}. {background_block}. {style_block}

제품에 따라 변하는 것은 subject_block뿐입니다. camera_block은 각도별 상수입니다:

  • 히어로 / 4분의 3 뷰: product photographed at a 45-degree three-quarter view, slightly above eye level, full product in frame with even margins
  • 정면 입면: straight-on front view, camera at product mid-height, centered, no perspective tilt
  • 탑다운 플랫레이: directly overhead top-down view, product centered, flat lay composition
  • 디테일 클로즈업: close-up macro view of the product surface, shallow depth of field

실무에서 이들을 작동하게 만드는 두 가지 규칙:

  • 시점을 두 번 명시하세요. 명확한 각도에 구도 조항(예: "full product in frame with even margins")을 더하는 것이 어느 하나만 쓰는 것보다 안정적입니다.
  • 상대적 참조를 피하세요. "Same angle as the last image"는 text-to-image 모델에 아무 의미가 없습니다. 모든 프롬프트는 독립적으로 성립해야 합니다.

템플릿을 렌더링 코드와 함께 버전 관리에 두세요. camera_block을 수정할 때는 버전 번호를 올리고, 커밋 전에 작은 샘플을 재생성하세요. 문구 변경은 곧 전체 카탈로그의 변경입니다.

조명과 배경을 위한 프롬프트 템플릿

조명과 배경은 생성된 이미지 묶음이 서로 무관한 이미지 더미가 아니라 같은 촬영처럼 보이게 만드는 핵심입니다. 둘 다 템플릿의 상수 부분에 속하며, 방향과 부드러움을 명시해야 합니다.

안정적으로 전이되는 조명 언어:

  • 방향: key light from camera left, light from upper right, soft overhead light. 방향은 가장 직관적인 일관성 레버이므로 촬영 유형별로 고정하세요.
  • 품질: soft diffused light, large softbox, gentle shadows, hard directional light with defined shadow edge.
  • 필과 번짐: subtle fill from the right, low-contrast shadows, clean highlight on the top surface.

배경 언어:

  • 심리스 스튜디오: on a seamless light grey studio backdrop, no horizon line, soft contact shadow beneath the product.
  • 라이프스타일 표면: resting on a matte stone surface, softly out-of-focus neutral background.
  • 누끼 작업 용이: isolated on a plain white background, product fully in frame, generous margins for cropping.

실용적인 두 가지 주의 사항. 첫째, 제품 표면과 반사가 많을수록 조명을 더 정밀하게 설명해야 합니다. 하이라이트의 위치가 곧 제품의 외관이기 때문입니다. 둘째, 같은 촬영 유형 안에서 배경을 혼용하지 마세요. 하나의 그리드 타일 세트는 배경을 공유해야 하며, 그렇지 않으면 그리드가 서로 다른 세 공급업체에서 모은 것처럼 보입니다. 이 블록들을 상수로 고정하고, 의도적으로 바꿀 때만 변경하세요.

출력 크기와 종횡비 선택

대량 처리 전에 배치 위치별로 크기를 결정하세요. 다른 크기로 다시 실행하는 것은 리사이즈가 아니라 완전한 재생성이기 때문입니다. 먼저 배치 위치를 종횡비에 매핑하고, 그다음 프런트엔드가 실제로 렌더링하는 픽셀 크기에 매핑하세요.

  • 그리드 및 카테고리 타일: 정사각형. 제품 그리드 크롭은 예측하기 어렵기 때문에 여유 있는 마진의 정사각형 구도가 대부분의 타일 레이아웃에 맞습니다.
  • 제품 상세 페이지: 정사각형 또는 4:3, 썸네일이 아닌 확대 뷰어의 크기를 기준으로 정하세요. 상세 페이지가 고정 비율로 크롭된다면 정확히 맞추고 CSS에서 맞서 싸우지 마세요.
  • 배너 및 히어로 스트립: 와이드, 안전 영역을 명시적으로 계획하세요. 제품을 중앙에 두고 양쪽에 마케팅 문구가 들어갈 네거티브 스페이스를 남기도록 요청하세요.
  • 이메일 및 소셜 미디어: 플랫폼 기본 비율에 맞추세요. 재생성이 패딩 추가보다 저렴합니다.

몇 가지 경험칙:

  1. 배치 위치마다 표준 크기 하나를 선택해 재사용하세요. 한 타일 그리드에 여러 크기를 섞으면 눈에 띄는 품질 차이가 생깁니다.
  2. 생성 이미지를 확대해 더 큰 위치를 채우지 마세요. 더 큰 크기로 생성한 뒤 축소하세요.
  3. 비율이 바뀌면 구도를 다시 확인하세요. 정사각형용으로 구도 잡은 45도 히어로 컷은 와이드 크롭에서 제품 바닥을 잃을 수 있으니, camera_block의 구도 조항을 그에 맞게 조정하세요.
  4. 크기를 작업 기록에 남기세요. 나중에 출력을 검토할 때 크기는 메타데이터 노이즈가 아니라 맥락의 일부입니다.

배치 요청과 항목별 결과 처리

카탈로그 규모에서는 작업 단위가 요청이 아니라 작업(job)입니다. 제품 하나, 촬영 유형 하나, 크기 하나, 렌더링된 프롬프트 하나. 작업을 먼저 데이터로 모델링하고 유계 큐를 통해 전송하면, 실패는 오후를 날리는 사건이 아니라 재실행 가능한 한 행이 됩니다.

견고한 루프는 네 가지를 합니다:

  • 프롬프트를 결정적으로 렌더링: 템플릿과 제품 필드에서 렌더링하고, 렌더링된 문자열을 작업에 저장하세요.
  • 동시성 제한: 계정과 다운스트림 스토리지가 감당할 수 있는 양으로 제한하세요. 전체 카탈로그를 한 번에 요청하지 마세요.
  • 결과를 항목별로 처리. 배치 작업은 항목별로 성공 또는 실패하므로, 각 결과를 해당 job_id 아래에 쓰고 전체 배치가 원자적이라고 가정하지 마세요.
  • 일시적 오류에만 백오프 재시도. 유효성 오류(형식이 잘못된 프롬프트, 지원되지 않는 크기)는 재시도해도 같은 방식으로 실패하므로 먼저 분류한 뒤 재시도하세요.
for job in queue.fetch_pending(limit=50):
    try:
        result = client.images.generate(
            model="muse-image-1.0/text-to-image",
            prompt=job.prompt,
            size=job.size,
        )
        db.record_success(job.id, result)
    except TransientError as e:
        queue.requeue(job.id, backoff=e.retry_after)
    except ValidationError as e:
        db.record_failure(job.id, reason=str(e))

작업마다 상태 컬럼(pending, done, failed)을 유지하고, 실패를 위한 데드 레터 뷰를 마련하세요. 배치가 완료되면 총합 하나가 아니라 촬영 유형과 크기별로 집계를 보고하세요. 회귀 문제는 바로 거기에 숨어 있습니다.

생성 이미지 게시 전 QA 체크리스트

생성 이미지에는 게이트가 필요하고, 게이트는 누군가 문을 지키는 체크리스트여야 합니다. 자동화 검사는 저렴한 문제를 잡고, 검토자는 비싼 문제를 잡습니다.

검토 전 자동화 검사:

  • 대상 배치 위치의 종횡비와 픽셀 크기가 올바름.
  • 명백한 손상 출력 없음. 파일이 정상적으로 열리고 디코딩됨.
  • 프롬프트에 제품 색상이 지정된 경우, 색상이 예상과 일치함.
  • 그리드 타일에서 크롭 허용 오차를 위한 마진이 확보됨.

게시 전 사람 검토:

  • 제품이 이 제품처럼 보이는가. 모양, 비율, 하드웨어, 마감?
  • 허구의 텍스트, 로고, 패키지 문구가 있는가? 생성된 텍스트는 흔한 실패 지점이자 상점에서 법적 위험입니다.
  • 조명과 배경이 전체 크기에서뿐 아니라 썸네일 크기에서도 그룹 내 다른 이미지와 일치하는가.
  • 화면에 불필요한 물체, 추가 구성 요소, 비논리적 반사가 없는가.
  • 홍보 문구와 규제 라벨이 생성 기술로 변경되지 않았는가. 이런 이미지는 촬영 프로세스를 거쳐야 합니다.

승인된 소재마다 검토자와 프롬프트 버전을 기록하세요. 고객 불만이나 게시 중단 요청이 들어올 때 이 기록을 통해 영향을 받은 모든 이미지를 한 번에 찾아내고, 전체 세트를 재생성하거나 내릴 수 있습니다.

촬영 유형 하나, 크기 하나, 소량의 제품 샘플로 시작해 HiAPI 인터페이스를 통해 실행하고, 출력이 검토를 통과한 후에만 템플릿을 확장하세요.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기