YouCam API만으로 만드는 AI 헤어스타일 어드바이저

서론

새로운 헤어스타일을 하고 싶다. 하지만 나에게 어울릴지 모르겠다.

미용실에서 "알아서 해주세요"라고 맡기는 것도 불안하고, 그렇다고 매번 똑같은 헤어스타일은 지루하다. 이상적인 것은 "내 얼굴형에 맞는 스타일을 AI가 제안해주고, 가상 피팅까지 자동으로 해주는 것"이다.

YouCam API에는 얼굴 분석(Face Analysis)・헤어스타일 피팅(Hair Style VTO)・헤어 컬러 피팅(Hair Color VTO)의 3가지 API가 있다. 이것들을 조합하면 LLM에 의존하지 않고도 완전 규칙 기반(Rule-based)으로 작동하는 헤어스타일 어드바이저를 만들 수 있다.

이 기사에서는 얼굴 사진을 업로드하는 것만으로 "얼굴형 분석 → 어울리는 스타일 추천 → 피팅 이미지 생성"까지 자동으로 수행하는 웹 앱 제작 방법을 소개한다. YouCam API의 사용법은 물론, LLM에 의존하지 않는 규칙 기반 추천 설계와 실제로 다뤄보며 처음 알게 된 주의점까지 코드와 함께 공유한다.

이런 분들이 읽어주었으면 한다.

• YouCam API를 다뤄보고 싶지만 무엇부터 시작해야 할지 모르는 사람
• 얼굴 분석이나 가상 피팅을 사용한 앱을 만들고 싶은 사람
• LLM을 사용하지 않고 결정론적(Deterministic)으로 작동하는 추천 로직 제작에 관심이 있는 사람

만든 것

웹 앱 데모

사진을 업로드하면 다음 3단계가 자동으로 실행된다.

얼굴 분석: YouCam Face Attributes API가 얼굴형・연령・눈 모양・머리색 등을 해석 -
스타일 추천: 해석 결과로부터 규칙 엔진(Rule Engine)이 어울리는 헤어스타일과 헤어 컬러를 선정 -
피팅 생성: Hair Style VTO API / Hair Color VTO API가 선택된 스타일을 피팅 이미지로 출력

기술적으로 흥미로운 부분은 추천 엔진 부분이다. LLM으로 "추천하는 헤어스타일은?"이라고 생성하는 것이 아니라, 얼굴형과 헤어스타일 템플릿을 키워드 매칭(Keyword Matching)으로 연결함으로써 결정론적으로 동작하는 구조로 만들었다.

왜 LLM을 사용하지 않는가

LLM은 편리하지만, 이번 유스케이스에서는 몇 가지 과제가 있다.

응답 시간: 얼굴 분석 후에 LLM으로 질의하면 추가로 몇 초의 레이턴시(Latency)가 발생함 -
재현성: 같은 얼굴 사진이라도 추천 결과가 흔들릴 가능성이 있음 -
비용: YouCam API의 유닛 소비에 더해 LLM의 API 비용도 발생함 -
의존성: 심플한 3단계 파이프라인에 LLM을 넣는 것은 오버킬(Overkill)

그래서 얼굴 분석 결과(얼굴형・머리색)를 그대로 규칙 기반으로 처리하는 설계로 결정했다.

시스템 구성

사용하는 API는 다음 3가지다.

API	버전	역할
AI Face Attributes & Ratio Analyzer	v2.0	얼굴형・연령・머리색・눈 모양 등을 해석
...

YouCam API의 기초 지식

구현에 들어가기 전에, YouCam API 전반에 공통되는 비동기 태스크(Asynchronous Task)의 흐름을 설명한다. 이 워크플로우는 모든 API에서 공통이다.

파일 업로드 흐름

# 1. File API로 업로드 대상 URL과 file_id를 취득
POST /s2s/v2.1/file/hair-transfer
→ { file_id: "abc123", requests: [{ url: "https://s3...", headers: {...} }] }
...

중요한 포인트: File API 호출만으로는 파일이 업로드되지 않는다. 응답에 포함된 서명된 URL(Signed URL)에 대해 실제 이미지 바이너리를 PUT 해야 한다. 이 부분을 잊으면 500 unknown_internal_error가 발생한다.

폴링(Polling)을 통한 결과 취득

AI 태스크는 비동기이다. task_id를 취득하면 상태가 success 또는 error가 될 때까지 정기적으로 폴링한다.

def _poll_task(self, endpoint: str, task_id: str, max_wait: int = 120) -> dict:
deadline = time.time() + max_wait
while time.time() < deadline:
...

처리 시간은 API 종류나 이미지 크기에 따라 변동하지만, 통상 5~15초 정도이다.

구현 상세

1. 얼굴 분석 API 호출

Face Attributes API는 얼굴 사진으로부터 50가지 이상의 속성을 분석합니다.

def analyze_face(self, file_path: str) -> dict:
file_info = self._upload_file(file_path, "/s2s/v2.0/file/face-attr-analysis")
file_id = file_info["file_id"]
...

dst_actions에 분석하고 싶은 항목을 나열합니다. 이번에는 추천에 필요한 "얼굴형 (faceShape)", "머리색 (hairColor)", "연령/성별 (age/gender)"를 필수 항목으로 설정하였으며, UI 표시를 위해 눈 모양이나 얼굴 비율도 함께 가져오고 있습니다.

얼굴 분석 결과로는 다음과 같은 데이터를 얻을 수 있습니다.

{
"faceshape": "Oval",
"agegender": { "age": 28, "gender": "female" },
...

2. 헤어스타일 템플릿 가져오기

Hair Style VTO (v2.1)에서는 사전에 정의된 템플릿을 사용하여 가상 착용 (Virtual Try-On)을 진행합니다. 이용 가능한 템플릿 목록은 전용 API를 통해 가져옵니다.

def fetch_hair_templates(self) -> list[dict]:
all_templates = []
next_token = None
...

각 템플릿에는 id, title (스타일명), thumb (썸네일 이미지 URL), category_name (카테고리명)이 포함됩니다. 페이지네이션 (Pagination)은 next_token 기반으로 모든 페이지를 가져오도록 구현되어 있습니다.

3. 추천 로직 — 핵심 요소

추천 엔진의 핵심은 얼굴형과 템플릿 이름 간의 **키워드 매칭 (Keyword Matching)**입니다.

FACE_SHAPE_RULES = {
"Oval": {
"description": "가장 균형 잡힌 만능 얼굴형입니다.",
...

얼굴형마다 "추천 키워드"와 "피해야 할 키워드"를 정의하고, 템플릿 이름에 포함된 키워드로 점수를 산출 (Scoring)합니다.

def recommend_hairstyles(face_attrs, templates) -> list[dict]:
face_shape = face_attrs.get("faceshape", "Oval")
rule = FACE_SHAPE_RULES.get(face_shape, FACE_SHAPE_RULES["Oval"])
...

점수 산출 설계 의도:

• 키워드 일치 시 +2: 추천 키워드가 템플릿 이름에 포함되어 있으면 가점
• 회피 키워드 시 -3: 피해야 할 키워드는 더 강하게 감점 (피하는 것이 더 중요함)
• 점수 > 0 인 경우만 채택: 관련 없는 템플릿은 제외
• 상위 3개 추천: 선택지를 너무 좁히지도, 너무 넓히지도 않음

헤어 컬러 또한 마찬가지로, 현재 머리색으로부터 추천 프리셋 컬러를 선택합니다. YouCam API의 풀 컬러 모드에서 이용 가능한 프리셋 (Jet Black / Chocolate Brown / Burgundy 등 10종류) 중에서 선택합니다.

HAIR_COLOR_SUGGESTIONS = {
"Black": [
{"label": "초콜릿 브라운", "preset": "Chocolate Brown"},
...

4. 가상 착용 API 호출

추천된 템플릿 ID 또는 컬러 프리셋을 사용하여 실제 가상 착용 이미지를 생성합니다.

def apply_hairstyle(self, file_path: str, template_id: str) -> str:
file_info = self._upload_file(file_path, "/s2s/v2.1/file/hair-transfer")
file_id = file_info["file_id"]
...

Hair Color VTO도 동일한 구조이며, template_id 대신 preset 파라미터를 지정합니다.

def apply_hair_color(self, file_path: str, preset: str) -> str:
file_info = self._upload_file(file_path, "/s2s/v2.0/file/hair-color")
file_id = file_info["file_id"]
...

5. FastAPI 백엔드 (Back-end)

서버 측은 FastAPI로 구현했습니다. 엔드포인트는 3개뿐인 심플한 구성입니다.

@app.post("/api/analyze")
async def analyze(file: UploadFile = File(...)):
# 얼굴 분석 → 템플릿 획득 → 추천 → 결과 반환
...

프론트엔드는 단일 HTML 파일로, 파일의 드래그 앤 드롭, 얼굴 분석 결과 표시, 스타일·컬러 선택, 가상 착용 (VTO) 결과 표시까지 수행합니다.

주의할 점 (ハマりどころ)

YouCam API를 처음 접하면서 헤맸던 포인트들을 공유합니다.

1. 파일 업로드의 2단계 구조

File API에서 file_id가 반환되어도, 아직 파일이 업로드된 것은 아닙니다. requests.url에 실제 바이너리를 PUT 하는 것을 잊으면, 태스크 생성 시 500 unknown_internal_error가 발생합니다. 처음에는 이 에러의 원인을 몰라 당황했습니다.

# File API의 응답에서 업로드 URL을 가져옴
upload_url = file_info["requests"][0]["url"]
# 이 PUT을 잊으면 500 에러 발생
...

2. API 버전 차이에 따른 엔드포인트 변화

Hair Style VTO는 v1.0 / v2.0 / v2.1의 3세대가 있습니다.

• v1.0:
  /s2s/v2.0/file/hair-style
  +/s2s/v2.0/task/hair-style

• v2.0:
  /s2s/v2.0/file/hair-transfer
  +/s2s/v2.0/task/hair-transfer

• v2.1:
  /s2s/v2.1/file/hair-transfer
  +/s2s/v2.1/task/hair-transfer

v2.1이 최신이며 템플릿 기능이 충실하기 때문에, 이번에는 v2.1을 사용했습니다. 문서를 읽을 때는 자신이 사용 중인 버전의 섹션을 확인해야 합니다.

3. 헤어 컬러 프리셋(Preset) 이름은 완전 일치해야 함

프리셋 이름("Chocolate Brown" 등)은 대소문자와 공백까지 완전하게 일치해야 합니다. "chocolate brown"이나 "chocolate_brown"으로 입력하면 InvalidParameters 에러가 발생합니다.

사용 가능한 풀 컬러 모드 프리셋:

• Jet Black, Chocolate Brown, Honey Blonde, Platinum Blonde, Ash Gray
• Rose Gold, Burgundy, Copper Red, Lavender, Teal Blue

4. hair_color_name과 헤어 컬러 API의 프리셋은 별개

얼굴 분석 API가 반환하는 hair_color_name은 "Black", "Brown", "Blonde" 등 카테고리명입니다. 반면, 헤어 컬러 API의 preset은 "Jet Black", "Chocolate Brown" 등 구체적인 색상명입니다. 이 두 가지를 그대로 매칭할 수 없기 때문에, 이번 구현에서는 딕셔너리를 통한 매핑을 수행했습니다.

5. 얼굴 분석은 「정면 사진」이 거의 필수

이것이 가장 헤맸던 포인트입니다. 얼굴 분석 API (Face Attributes)는 얼굴형·연령·성별 분석을 위해 정면을 향한 얼굴을 요구합니다. 조금이라도 옆, 위, 아래를 향하고 있으면, face_angle_strictness_level을 가장 완화된 `

로 반환됩니다.

게다가 같은 사진이라도 요청할 때마다 결과가 흔들립니다. 얼굴이 약간 기울어진 사진을 여러 번 보내면, 성공하기도 하고 실패하기도 합니다. 재시도(Retry)를 해도 각도 자체는 변하지 않기 때문에 근본적인 해결책은 되지 않습니다.

흥미로운 점은 피부색·머리색 분석 (Skin Tone API)은 각도에 비교적 관대하다는 것입니다. 얼굴형은 실패하더라도 머리색만은 결과가 나오는 식의 상황이 발생합니다. 그래서 구현 시에는 "얼굴형을 가져오지 못했다면, 가져온 정보(머리색·피부색)만으로 추천한다"는 폴백 (Fallback) 로직을 넣었습니다.

if face_result:
face_summary = summarize_face(face_result)
else:
...

결론적으로, 이 앱은 정면·밝은 곳·얼굴이 선명하게 찍힌 사진을 사용하는 것이 전제입니다. 증명사진 같은 정면 샷이 가장 안정적입니다. 옆모습이나 잘린 사진은 얼굴형 분석이 통과되지 않으므로, UI 측에서도 "정면 사진을 사용해 주세요"라고 명시하는 것이 친절할 것이라고 생각합니다.

실행 방법

소스 코드 일체는 GitHub에서 공개하고 있습니다.

# 1. 리포지토리 (Repository) 클론
git clone https://github.com/arufian/youcam-ai-hairstyle.git
cd youcam-ai-hairstyle
...

브라우저에서 http://localhost:8000을 열면 업로드 화면이 표시됩니다.

참고로, 리포지토리에는 얼굴 사진을 포함하지 않았습니다 (타인의 얼굴 사진을 커밋하지 않기 위해 .gitignore 처리 완료). 테스트할 때는 직접 준비한 정면 얼굴 사진을 리포지토리 루트 디렉토리에 sample.jpg로 놓아주세요.

YouCam API의 무료 유닛 (1,000 유닛)은 [여기]에서 받을 수 있습니다.

요약

• YouCam API 3종 (얼굴 분석·헤어스타일 가상 체험·헤어 컬러 가상 체험)을 조합하여, LLM 없이 완전 자동 헤어스타일 어드바이저를 구축했습니다.
• 추천 엔진은 룰 베이스 (Rule-based) 키워드 매칭으로 구현했습니다. 얼굴형 → 어울리는 스타일 매핑을 코드로 작성함으로써 결정론적(Deterministic)이고 빠른 추천을 실현했습니다.
• YouCam API의 비동기 태스크 플로우 (File API → 태스크 생성 → 폴링 (Polling))는 모든 API에 공통된 패턴입니다. 한 번 이해하면 다른 API에도 응용할 수 있습니다.
• 헤어 컬러의 프리셋 이름은 완전 일치가 필요하며, API 버전에 따라 엔드포인트가 다르다는 등의 세부적인 주의사항이 있었습니다.

YouCam API는 미용·패션 분야의 AI 기능을 풍부하게 제공하고 있어, API만 잘 파악하면 놀라울 정도로 적은 코드만으로도 풍부한 기능을 구현할 수 있습니다. 여러분도 꼭 자신만의 조합을 시도해 보세요.

Discussion