README.md

metadata

title: ROEM-AI
emoji: 📸
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: AI fashion model cut generator

AI ModelCut Studio

Hugging Face Dataset Save

Generated images are saved to a Hugging Face Dataset when these Space secrets are set:

HF_DATASET_REPO=sunyoung00/ROEM_TEST
HF_TOKEN=hf_...

HF_TOKEN must have write permission for the dataset repo. If HF_DATASET_REPO is not set, the app defaults to sunyoung00/ROEM_TEST. Upload failures are logged but do not block image generation.

Saved files are uploaded under:

generated/YYYYMMDDTHHMMSSZ_requestid/
  01_label.png
  metadata.json

제품 이미지, AI 모델 얼굴, 체형 레퍼런스, 제품 기장, 샷별 포즈 레퍼런스를 조합해 쇼핑몰용 AI 모델컷을 생성하는 Hugging Face Spaces용 앱 구조입니다. (얼굴/체형/포즈 레퍼런스 배치는 assets/README.md 참고)

Hugging Face Spaces 실행 구조

이 저장소는 Docker Space로 바로 실행할 수 있습니다.

필수 파일:

• Dockerfile: Hugging Face Spaces Docker SDK가 빌드하는 컨테이너 정의
• app.py: FastAPI 기반 웹 서버와 생성 API
• requirements.txt: Python 런타임 의존성
• index.html, styles.css, script.js: 별도 프론트엔드 시안

Hugging Face에서 새 Space를 만들 때 SDK는 Docker로 선택하면 됩니다.

Space SDK: Docker
Port: 7860
Start command: Dockerfile CMD 사용

현재 app.py는 OpenAI/Gemini 이미지 생성 API를 우선 호출합니다. API 키가 없거나 DEMO_FALLBACK=true로 설정한 경우에는 업로드한 제품 이미지를 합성하는 데모 worker를 사용할 수 있습니다.

실제 이미지 생성 API

현재 앱은 Docker 컨테이너에서 OpenAI 또는 Gemini 이미지 생성 API를 호출할 수 있습니다.

환경변수:

OPENAI_API_KEY=...
GEMINI_API_KEY=...
OPENAI_IMAGE_MODEL=gpt-image-2
GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview
DEMO_FALLBACK=false

# 데이터셋 저장
HF_DATASET_REPO=sunyoung00/ROEM_TEST
HF_TOKEN=hf_...

# 생성 동작 튜닝 (선택)
GEN_MAX_WORKERS=4            # 일괄 샷 / Gemini 후보 동시 생성 수
API_INPUT_MAX_SIDE=2048      # 레퍼런스 이미지 전송 시 긴 변 상한
MATCH_REFERENCE_FRAMING=true # 샷 레퍼런스 프레이밍에 맞춰 자동 크롭
SUBJECT_BG_TOLERANCE=32      # 배경 대비 피사체 검출 민감도(크롭용)
IDEALIZE_PROPORTIONS=false   # 체형 레퍼런스 없을 때 8.2~8.5등신 강제 여부
FRAMING_TOP_MARGIN=          # (선택) 수동 크롭 상단 여백 비율, 예: 0.10
FRAMING_BOTTOM_MARGIN=       # (선택) 수동 크롭 하단 여백 비율, 예: 0.08

화면의 이미지 생성 모델에서 아래 provider를 선택합니다.

• openai:gpt-image-2
• openai:gpt-image-1.5
• openai:gpt-image-1
• gemini:gemini-3.1-flash-image-preview
• gemini:gemini-3-pro-image-preview
• gemini:gemini-2.5-flash-image

1K는 1024px급 세로 결과, 2K는 2048px급 세로 결과를 요청합니다. GPT Image 2와 Gemini 3.1/3 Pro 이미지 모델처럼 2K 요청을 지원하는 모델은 API 요청 단계에서 2K를 지정하고, 반환 이미지 크기가 다르면 최종 캔버스에 맞춰 정규화합니다.

API 키가 없거나 모델명이 해당 계정에서 지원되지 않으면 화면에 오류가 표시됩니다. DEMO_FALLBACK=true를 설정한 경우에만 기존 데모 렌더러로 대체됩니다.

모델 얼굴 프리셋

첨부한 모델 얼굴 이미지는 아래 경로에 저장해서 함께 업로드하면 기본 프리셋으로 사용됩니다.

assets/model_face_preset.png

앱에서는 모델 얼굴 소스 기본값이 첨부 얼굴 프리셋으로 설정되어 있습니다. 별도 얼굴 이미지를 테스트하고 싶을 때만 업로드 얼굴을 선택하면 됩니다.

화면의 페르소나 얼굴 업로드에 얼굴 이미지를 올리면 해당 파일이 /api/generate의 model_face로 전달됩니다. 실제 API 생성에서는 이 얼굴 레퍼런스를 첫 번째 참조 이미지로 넣고, 후보 3장과 후속 샷 모두 동일 인물로 유지하도록 프롬프트에 identity lock 지시를 포함합니다.

화면 구성

• 로그인 / 프로젝트 저장
• QR 또는 로컬 제품 이미지 업로드: 제품 1~4 각각 앞면, 뒷면 옵션
• 카테고리, 핏, 제품 기장, 스타일 선택
• 프롬프트 입력
• 카테고리(상의/하의 등)에 따라 달라지는 샷 버튼 선택
• 전신(앞면) 후보 3장 우선 생성
• 선택한 후보 컷 기준 샷 구도 변경 생성 (각 샷은 assets/poses의 명명 레퍼런스를 따라감)
• 1K / 2K 해상도 선택
• 선택 컷 재생성
• AI 표기 삽입
• 일괄 다운로드
• 생성 시간 안내

권장 생성 파이프라인

1. 입력 검증

   • 제품 원본 해상도, 배경 투명도, 블러, 로고 영역, 메타데이터 확인
   • 긴 변 기준 최소 1500px 이상 권장

2. 제품 전처리

   • 제품 1~4의 앞면/뒷면 레퍼런스 제품 영역 세그멘테이션
   • 실루엣, 로고, 패턴, 버튼, 소재 텍스처 보존용 마스크 생성
   • 카테고리와 기장 값을 프롬프트 조건으로 변환

3. 모델 조건 생성

   • 선택한 AI 모델 얼굴 임베딩 또는 레퍼런스 이미지 연결
   • 포즈 레퍼런스에서 OpenPose / DensePose / depth 조건 추출
   • 전신 3컷을 먼저 생성하고 이후 스타일 변형 컷 생성

4. 1차 이미지 생성

   • 전신(정면) 후보 3장을 먼저 생성
   • 사용자가 선택한 기준 컷의 얼굴/의상 정보를 후속 샷 생성의 기준으로 사용
   • 제품 마스크를 강하게 고정
   • 얼굴, 손, 다리, 옷 경계부를 별도 검수 대상으로 저장
   • 컷별 seed, prompt, negative prompt, model version 기록

5. 샷 구도 확장

   • 선택 기준 컷에서 얼굴, 의상, 색상, 소재, 로고를 유지
   • 각 샷은 assets/poses/의 동일 이름 레퍼런스(예: 전신_앞면_.*)에서 포즈·각도·크롭만 가져옴
   • 카테고리에 따라 노출 샷이 달라짐
     • 상의(원피스·아우터 포함): 전신(앞면), 전신(측면), 전신(후면), 상반신(앞면), 상반신(측면), 상반신(후면), 상반신(클로즈업), 디테일(후면)
     • 하의(스커트 포함): 전신(앞면), 전신(측면), 전신(후면), 상반신(앞면), 상반신(측면), 하반신, 하반신(클로즈업)
   • 전신·상반신(앞/측/후)·하반신은 레퍼런스 프레이밍에 맞춰 자동 크롭, 클로즈업·디테일은 크롭 생략

6. 품질 검수

   • 제품 형태 변형률
   • 로고 왜곡
   • 손가락, 얼굴, 다리 비율
   • 배경 누끼 품질
   • AI 표기 누락 여부

7. 고해상도 후처리

   • 1K 생성 후 2K 업스케일
   • 얼굴/제품 디테일 영역 선택 샤픈
   • 색상 편차 보정
   • JPG/PNG/WebP 및 ZIP 일괄 다운로드

추천 백엔드 구조

client
  upload panel
  option builder
  result gallery

api
  POST /projects
  POST /assets/product
  POST /assets/model-face
  POST /jobs/generate
  POST /jobs/:id/regenerate
  GET  /jobs/:id
  GET  /projects/:id/results.zip

worker
  preprocess product
  extract pose
  generate first-pass images
  run quality checks
  upscale and sharpen
  export final assets

storage
  original assets
  masks
  intermediate renders
  final images
  job metadata

로컬 실행

Docker 앱:

docker build -t modelcut-studio .
docker run --rm -p 7860:7860 -e OPENAI_API_KEY=... -e GEMINI_API_KEY=... modelcut-studio

Python 직접 실행:

pip install -r requirements.txt
python app.py

정적 UI 시안:

index.html을 브라우저로 열면 바로 확인할 수 있습니다.