Media Higgsfield Identity

---
name: media-higgsfield-identity
description: |
  Higgsfield MCP에서 재사용 가능한 인물·사물 일관성 참조를 만듭니다. Soul Character(학습형 identity 모델)와
  Reference Element(즉시 생성형 참조) 중 어느 쪽을 써야 하는지 판정하고, 선택된 경로로 생성·조회합니다.
  다음과 같은 요청 시 사용하세요:
  - "내 얼굴로 Soul 만들어줘", "디지털 트윈 학습시켜줘"
  - "이 캐릭터 계속 똑같이 나오게 해줘"
  - "나랑 친구 둘 다 나오는 이미지"
  - "이 제품을 여러 컷에 일관되게 넣어줘"
  - "학습해둔 캐릭터 목록 보여줘"
  Soul은 한 사람의 identity에 충실하지만 한 생성에 1개만·soul 계열 모델 전용이고, Element는 즉시 만들어지며
  한 프롬프트에 여러 개를 배치할 수 있고 사람이 아닌 대상도 됩니다. 이 분기를 잘못 고르면 되돌릴 수 없는
  학습 비용이 발생하므로, 경로가 불명확하면 생성하지 않고 blocker를 반환합니다.
version: "1.3.0"
---

# Higgsfield 일관성 참조 (media-higgsfield-identity)

> `moai-media` | Soul Character · Reference Element 판정과 생성 (코어: `media-higgsfield-core`)

## 개요

"같은 인물·같은 캐릭터·같은 제품이 여러 컷에 일관되게 나오게" 하는 두 가지 수단을 다룬다. 두 수단은 **대체재가 아니라 서로 다른 제약을 가진 별개 경로**이며, 잘못 고르면 학습 시간과 크레딧을 버린다.

호출 계약·namespace 런타임 해석·비용 프리플라이트는 코어를 따른다:
- 호출 계약: `../media-higgsfield-core/references/call-schema.md`
- 라이브 조회: `../media-higgsfield-core/references/catalog-protocol.md`
- 잡·비용·리드백: `../media-higgsfield-core/references/job-lifecycle.md`

## 트리거 키워드

Soul, Soul ID, 소울, 디지털 트윈, 캐릭터 학습, 얼굴 학습, identity, 캐릭터 일관성, Element, 레퍼런스 엘리먼트, 참조 요소, 재사용 캐릭터, 같은 인물, 같은 제품

## 두 경로 비교 (판정의 근거)

| 축 | Soul Character | Reference Element |
|---|---|---|
| 만드는 방법 | 5~20장 학습 (약 10분, 비차단) | 이미지 1장으로 즉시 생성 (동기) |
| 한 생성에 몇 개 | **1개만** | **여러 개** (`<<<id>>>` 다중 배치) |
| 대상 | 사람 1인 | 사람·환경·소품 모두 |
| 사용 가능 모델 | `soul_2`, `soul_cinematic` **전용** | Nano Banana 계열·GPT Image 2·Seedream·Cinema Studio·Seedance·Kling 등 |
| identity 충실도 | 높음 (전용 학습) | 보통 (참조 주입) |
| 되돌리기 | 학습 비용 발생 후 | 비용 거의 없음 |

상세 판정 규칙과 지원 모델 전체 목록은 `references/soul-vs-elements.md`.

## 판정 워크플로우

### 0단계 — 사람이 찍힌 사진인가 (경로 판정보다 먼저)

**[HARD] 얼굴 동의 게이트는 Soul/Element 분기보다 앞에 있다.** 사람이 찍힌 사진을 서버로 올리는 일은 어느 경로를 타든 같은 일이며, 경로는 그 뒤에 정한다.

이 순서가 뒤집히면 게이트에 구멍이 난다. Element로 확정되는 신호에는 **"가진 이미지가 1장뿐"**과 **"지금 바로·빨리"**가 들어 있다(1단계). 즉 **제3자 얼굴 사진 한 장을 급히 올리는 요청**이 정확히 Element로 분기하는데, 게이트가 Soul 쪽에만 있으면 그 요청은 아무 확인 없이 업로드된다. 가장 위험한 입력이 게이트를 비켜 가는 구조였다.

**게이트가 걸리는 조건**: 업로드할 이미지에 **사람 얼굴이 있다.** 사람이 아닌 대상(제품·소품·배경·로고)만 있으면 이 게이트는 지나가고 1단계로 간다.

- **[HARD] 사람 사진이 하나라도 섞였으면 `media_upload` 전에 멈춘다.** Soul이든 Element든, 1장이든 20장이든 같다.
- **[HARD] 승인과 동의는 다른 문항이다.** 아래 §게이트 1의 두 문항을 그대로 쓴다.
- 동의를 확보하지 못했으면 **업로드하지 않고 종료**한다. 경로 판정으로 넘어가지 않는다.

Element 경로라고 위험이 줄지 않는다. 학습은 없지만 **그 사람의 얼굴이 서버로 가고, 그 얼굴로 이미지가 생성된다.** 되돌릴 수 없다는 성질은 같다.

### 1단계 — 경로 판정 (0단계를 통과한 뒤)

아래 신호로 경로를 가른다. **어느 쪽도 확실하지 않으면 생성하지 않고 blocker를 반환**한다 — 오케스트레이터가 사용자에게 확인한다. 이 스킬은 사용자에게 직접 질문하지 않는다.

**Element로 확정되는 신호 (하나라도 걸리면 Element):**
- 한 컷에 인물/대상이 **2명 이상** ("나랑 친구", "두 사람이")
- 대상이 사람이 아님 (제품·소품·배경·로고)
- 가진 이미지가 **1장뿐**
- Nano Banana·Seedream·Kling·Cinema Studio 등 **soul 계열이 아닌 모델**을 지목
- "지금 바로", "빨리" 등 즉시성 요구

**Soul로 확정되는 신호:**
- "학습", "훈련", "디지털 트윈", "내 identity" 등 명시적 표현
- 같은 사람 사진 **5장 이상**을 제공했고 단독 컷이 목적

**양쪽 다 아니면 → blocker.** 애매한 상태로 Soul 학습을 시작하는 것이 이 스킬이 막으려는 실패다.

### 2단계-A — Soul 경로

얼굴은 되돌릴 수 없는 개인정보다. 사진을 올리면 서버에 남고, 학습이 끝나면 그 사람의 얼굴로 이미지를 계속 만들어낼 수 있는 모델이 계정에 남는다. **그래서 Soul 경로에는 승인 게이트가 두 번 있다** — 사진을 올리기 전에 한 번, 학습을 제출하기 전에 한 번. 둘은 다른 일이라 한 번의 승인으로 묶지 않는다.

#### 게이트 1 — 업로드 전 (사진이 서버로 나가기 전)

> 사람 사진이면 이 게이트는 **0단계에서 이미 통과했다.** 여기서 다시 묻지 않는다. 아래 내용은 그 게이트의 정의이며, 0단계와 Element 경로가 함께 참조한다.

- **[HARD] 승인은 §승인 요청 계약의 경로로 받는다.** 산문으로 묻지 않는다. 이 스킬이 서브에이전트로 실행 중이라 질문할 수 없으면 blocker를 반환하고 오케스트레이터가 대신 묻는다(1단계와 같은 규약).
- **[HARD] 요약하지 말고 실제로 올라가는 것을 그대로 보여준다:**

| 보여줄 것 | 왜 필요한가 |
|---|---|
| 사진 파일명 전체 목록 · 장수 | 어떤 사진이 나가는지 파일 단위로 확인 |
| 사진 속 인물이 누구인지 | 아래 동의 문항으로 이어진다 |
| 업로드 대상 계정 | 개인 계정인지 회사·공용 계정인지 |

- **[HARD] 인물 동의는 별도 문항으로 확인한다.** "사진을 올려도 되는가"와 "이 얼굴을 학습시켜도 되는가"는 다른 질문이다.

| 선택지 | 뜻 |
|---|---|
| 내 얼굴이다 (권장) | 본인 — 그대로 진행 |
| 제3자이고 동의를 받았다 | 동의 근거(서면·계약·촬영 동의서 등)를 한 줄로 남기고 진행 |
| 아직 동의를 못 받았다 | **중단** — 사진을 올리지 않는다 |

> 촬영·게시에 동의했다는 사실은 "내 얼굴로 AI 모델을 학습시켜도 좋다"는 동의가 아니다. 행사 사진·단체 사진·고객 사진이 여기에 해당한다.

#### 게이트 2 — 학습 제출 전 (`action:'train'` 직전)

업로드가 끝나면 크레딧이 나가기 전에 다시 멈춘다. 이번에는 **돈과 학습 결과물**을 보여준다:

| 보여줄 것 | 왜 필요한가 |
|---|---|
| 업로드된 `media_id` 목록 · 최종 장수 | 실제로 학습에 들어가는 것이 무엇인지 |
| Soul 이름 · 타입(`soul_2` / `soul_cinematic`) | 계정 목록에 이 이름으로 남는다 |
| 견적 크레딧과 플랜 조건 | 학습은 유료 플랜(Basic 이상) 기능이다 |
| 같은 이름·같은 인물의 기존 Soul 유무 | 중복 학습은 크레딧을 두 번 쓴다 |

- **[HARD] 제출 전에 기존 Soul을 먼저 조회한다.** `show_characters(action:'list', status:'ready')` 로 같은 인물·같은 이름이 이미 학습돼 있는지 확인하고, 있으면 그 사실을 승인 화면에 보여준 뒤 사용자가 재학습을 고르게 한다.
- **[HARD] 실패해도 자동 재제출하지 않는다.** 학습 제출이 애매하게 실패하면(타임아웃·응답 없음) 재제출하지 않고 멈춘다. 성공 신호가 없다는 것은 학습이 시작되지 않았다는 증거가 아니다. `show_characters(action:'list')` 로 실제로 생성됐는지 먼저 확인하고, 없다는 것이 확인된 뒤에만 다시 제출한다.

#### 승인 뒤 실행 절차

1. **이미지 준비.** 로컬 경로는 받지 않는다. `media_upload` → 바이트 PUT → `media_confirm` 순서로 올려 `media_id` UUID를 얻는다. 완료된 이미지 잡 ID나 https URL도 허용된다.
2. **품질 점검.** 5~20장, 권장 8~12장. 각도·조명·표정·거리가 다양할수록 좋다. 상세 기준은 `references/training-photo-guide.md`. 기준 미달이면 학습을 제출하기 전에 사용자에게 알린다.
3. **타입 선택.** 다운스트림 용도로 정한다 — 정지 이미지는 `soul_2`, 시네마틱은 `soul_cinematic`.
4. **학습 제출.** `show_characters(action:'train', name, medias[])`. 비차단이며 약 10분 소요.
5. **상태 확인.** `show_characters(action:'status', soul_id)`. 폴링은 조용히 — 진행 상황을 반복 보고하지 않는다.
6. **인계.** 준비되면 `soul_id`를 `generate_image`의 `params.soul_id`로 넘긴다. 모델은 `soul_2` 또는 `soul_cinematic`.

기존 Soul을 찾을 때는 `show_characters(action:'list', status:'ready')`.

### 2단계-B — Element 경로

**[HARD] 사람이 찍힌 이미지면 0단계 게이트를 이미 통과했어야 한다.** 통과 기록이 없는 상태로 이 경로에 들어왔다면 업로드하지 말고 0단계로 돌아간다 — "Element라서 학습이 없으니 괜찮다"는 이유로 건너뛰지 않는다.

1. **이미지 준비.** Soul과 동일한 업로드 절차. `medias[]` 항목은 `{id, url, type}` 형태이며 `type`은 `media_input`(업로드) 또는 `image_job`(이전 생성).
2. **생성.** `show_reference_elements(action:'create', medias[])`. `category`는 기본 `auto`(서버 분류)로 두고, 사용자가 명시할 때만 `character`/`environment`/`prop`을 지정한다. `name`은 32자 이내이며 생략하면 서버가 자동 부여한다. 동기 반환이다.
3. **사용.** 반환된 element id를 `generate_image`/`generate_video`의 `params.prompt` 안에 `<<<element_id>>>` 형태로 끼워 넣는다. 한 프롬프트에 여러 개를 넣을 수 있다.
4. **조회.** `show_reference_elements(action:'list')` 또는 `action:'get'`.

> Element 사용 시 프롬프트에 들어가는 `<<<id>>>` 표기는 내부 메커니즘이다. 결과 보고에서 사용자에게 이 문법을 설명하지 않는다 — 사용자에게는 "그 캐릭터를 넣었다"로 충분하다.

## 비용·계정 전제

- Soul 학습은 **유료 플랜(Basic 이상)**을 요구한다. 무료 플랜이면 제출 전에 알린다.
- 학습 자체와 이후 생성은 별개 비용이다. 실제 생성 직전 `get_cost: true` 프리플라이트는 코어 규칙을 그대로 따른다.
- Element 생성은 학습이 없어 비용 부담이 작다.

## 출력 형식

```
## Higgsfield 일관성 참조 결과
- 선택 경로: [Soul | Element] — 판정 근거: [걸린 신호]
- 이름: [name]
- 참조 ID: [soul_id | element_id]
- 상태: [ready | training | 생성 완료]
- 사용 가능 모델: [경로별 제약]
- 다음 단계: [generate_image에 어떻게 넘기는지]
```

## 주의사항

- 경로가 애매하면 **생성하지 않는다.** Soul 학습은 시간과 크레딧을 쓰고 되돌릴 수 없다.
- 로컬 파일 경로를 `medias`에 그대로 넣지 않는다 — 반드시 업로드해 `media_id`를 얻는다(코어 `call-schema.md` §2와 동일 규칙).
- 한 생성에 `soul_id`는 1개다. 2인 이상 등장 요구를 Soul로 우회하려 하지 않는다.
- Soul을 soul 계열이 아닌 모델에 넘기지 않는다 — 무시되거나 오류가 된다.
- 학습 실패의 흔한 원인(사진 부족·단조로움·선글라스/모자 가림·단체 사진)은 `references/training-photo-guide.md`.
- 타인의 얼굴을 동의 없이 **올리지도 학습시키지도 않는다**. **이것은 안내가 아니라 게이트다** — 0단계 동의 문항에서 "아직 동의를 못 받았다"가 나오면 사진을 올리지 않고 멈춘다. "초상권은 사용자 책임"이라고 알리고 진행하는 것으로 갈음하지 않는다.

## 승인 요청 계약 (런타임 중립)

[HARD] 이 스킬의 게이트는 **특정 도구 이름에 묶이지 않는다.** `AskUserQuestion`은 Claude 런타임의 수단일 뿐이고, Codex를 비롯한 다른 런타임에는 그 도구가 없다. 도구 이름으로 계약을 쓰면 그 도구가 없는 런타임에서 게이트가 **영구 blocker**가 되어, 승인이 필요한 모든 작업이 그냥 멈춘다. 그건 안전이 아니라 고장이다.

승인은 아래 순서로 구한다. 위에서부터 **실제로 가능한 첫 번째**를 쓴다.

**승인의 정의는 수단이 아니라 결과다: 승인서를 사용자에게 그대로 보여주고, 그에 대한 명시적 응답을 받는 것.** 아래는 그 결과를 만드는 경로들이며, 위에서부터 가능한 첫 번째를 쓴다.

| 순위 | 경로 | 조건 |
|---|---|---|
| 1 | 런타임의 구조화 질문 도구 (`AskUserQuestion` 등) | 그 도구가 현재 세션에 노출돼 있을 때 |
| 2 | **일반 대화로 승인서를 제시하고 다음 턴에서 응답을 받는다** | 사용자와 직접 대화 중일 때. 도구가 없어도 이 경로는 언제나 열려 있다 |
| 3 | 구조화 blocker 반환 → 상위 오케스트레이터가 물어봄 | 서브에이전트로 실행 중일 때 |

**[HARD] 런타임의 도구 실행 권한 프롬프트는 승인이 아니다.** 그 프롬프트는 "이 도구를 호출해도 되는가"를 물을 뿐, 게이트가 보여주기로 한 인자·견적·동의 문항을 표시하지 않는다. 승인서 전체와 선택지를 실제로 표시하는 경우에만 2번 경로로 인정한다.

**[HARD] 2번 경로가 있으므로 "물을 수단이 없다"는 상황은 사실상 없다.** 대화가 가능한 곳에서는 언제나 승인서를 글로 제시할 수 있다. fail-closed는 **대화도 blocker 반환도 불가능한 완전 무인 실행**에만 해당한다 — 그 경우에만 실행하지 않고 멈춘다.

**[HARD] 3번을 쓸 때 blocker는 그 자체로 승인 요청서여야 한다.** 상위가 무엇을 물어야 할지 모르면 되물을 수 없고, 그러면 교착된다. 다음을 모두 담는다:

- 승인받을 **행위** 한 줄 (무엇이 되돌릴 수 없는지 / 얼마가 나가는지)
- 게이트가 요구하는 **인자 전부** (요약하지 않은 값)
- **선택지 목록** — 상위가 그대로 사용자에게 제시할 수 있는 형태
- **재개 방법** — 어떤 답을 받으면 무엇을 이어서 실행하는지

**[HARD] 세 경로가 모두 불가능한 무인 실행에서는 실행하지 않는다(fail-closed).** 물을 수단이 없다는 것은 승인을 받았다는 뜻이 아니다. 이때는 "승인 수단이 없어 진행하지 못했다"고 기록하고 멈춘다 — 조용히 진행하지 않는다. 반대로 **대화가 가능한데 도구가 없다는 이유로 멈추는 것도 잘못**이다. 2번 경로를 쓴다.

> 이 계약은 `CLAUDE.local.md` §범용성 원칙(OS 2종 × 런타임 2종에서 동일 동작)의 게이트 쪽 적용이다. 한 런타임에서만 도는 게이트는 미완성으로 본다.

---

## 관련 스킬

| 스킬 | 시점 |
|---|---|
| `moai-media:media-higgsfield-core` | 코어: 호출 계약·비용·namespace |
| `moai-media:media-higgsfield-image` | 후속: 참조를 써서 이미지 생성 |
| `moai-media:media-higgsfield-video` | 후속: 참조를 써서 영상 생성 |
| `moai-story:story-character-sheet` | 선행: 무엇을 학습시킬지(각도·앵커) 설계 |
| `moai-designer:design-brand-visual` | 후속: 브랜드 모델·마스코트 일관성 |

## 출처

- [Higgsfield Skills (공식 agent 문서)](https://github.com/higgsfield-ai/skills) — `higgsfield-soul-id` 스킬 v0.12.0 (MIT). 학습 사진 기준·실패 원인은 이 문서 기반.
- 라이브 MCP 도구 스키마 관측 (`show_characters` / `show_reference_elements`) — Soul/Element 분기 규칙·지원 모델 목록·업로드 제약의 근거. **Evidence tier: 1차.**
- 공식 CLI 스킬에는 Element 경로와 분기 규칙이 없다. 그 부분은 MCP 스키마 관측이 유일 출처다.