Media Higgsfield Identity

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

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

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

## 개요

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

**현재 연결의 기능 확인:** 사진을 업로드하기 전에 같은 연결에서 캐릭터 목록·학습 견적·학습 제출·학습 상태 조회 도구와 각각의 입력 스키마를 확인한다. 도구 이름은 연결마다 다를 수 있으므로 `show_characters`라는 이름 하나를 필수 조건으로 삼지 않는다. 필요한 기능이 없으면 업로드·학습을 시작하지 않고 빠진 기능을 알리며, Element가 사용자의 목적에 맞는지 별도로 판정한다.

호출 계약·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 |
|---|---|---|
| 만드는 방법 | 여러 사진으로 학습 (장수는 연결별 제한 확인, 비차단) | 이미지 1장으로 즉시 생성 (동기) |
| 한 생성에 몇 개 | **1개만** | **여러 개** (`<<<id>>>` 다중 배치) |
| 대상 | 사람 1인 | 사람·환경·소품 모두 |
| 직접 전달 | `soul_id`는 `soul_2`, `soul_cinematic`에서만 사용 | `<<<element_id>>>`는 현재 연결이 지원하는 모델에서 사용 |
| identity 충실도 | 높음 (전용 학습) | 보통 (참조 주입) |
| 비용 | 학습과 후속 생성의 비용을 따로 확인 | Element 생성·후속 생성의 비용을 연결에서 확인 |

Higgsfield의 현재 웹 안내는 학습된 Soul 캐릭터가 Elements에도 나타나 Seedance 영상에 쓰일 수 있다고 설명한다. 이는 `soul_id`를 Seedance에 직접 넘길 수 있다는 뜻은 아니다. 연결에서 Element 노출과 대상 모델 지원을 확인한다. 상세는 `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로 상위에 반환하고, 직접 실행에 채널이 없어도 같은 blocker를 반환한다.

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

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

**양쪽 다 아니면 → 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을 먼저 조회한다.** 현재 연결의 캐릭터 목록 도구(Claude MCP 예: `show_characters(action:'list', status:'ready')`에서 `status`를 `training`·`failed`로 바꿔 각각 호출)로 세 상태와 상태별 다음 페이지를 끝까지 확인한다. 같은 인물·같은 이름의 기존 항목이 있으면 상태를 승인 화면에 보여주고 사용자가 재학습 여부를 고르게 한다. 목록·페이지를 확인할 수 없으면 제출하지 않는다.
- **[HARD] 실패해도 자동 재제출하지 않는다.** 학습 제출이 애매하게 실패하면(타임아웃·응답 없음) 재제출하지 않고 멈춘다. 성공 신호가 없다는 것은 학습이 시작되지 않았다는 증거가 아니다. 현재 연결의 캐릭터 목록·상태 도구로 실제 생성 여부를 먼저 확인하고, 없다는 것이 확인된 뒤에만 다시 제출한다.

#### 승인 뒤 실행 절차

1. **이미지 준비.** 로컬 경로는 받지 않는다. `media_upload` → 바이트 PUT → `media_confirm` 순서로 올려 `media_id` UUID를 얻는다. 완료된 이미지 잡 ID나 https URL도 허용된다.
2. **품질 점검.** 학습 도구의 라이브 스키마나 해당 연결의 공식 안내에서 최소·최대 장수를 확인한다. 공식 CLI 스킬은 5~20장, 웹 도움말은 20~80장으로 서로 다르다. 현재 연결의 제한을 확인하지 못했다면 수량을 추정해 업로드·학습하지 않는다. 각도·조명·표정·거리가 다양할수록 좋다. 상세 기준은 `references/training-photo-guide.md`. 기준 미달이면 학습을 제출하기 전에 사용자에게 알린다.
3. **타입 선택.** 다운스트림 용도로 정한다 — 정지 이미지는 `soul_2`, 시네마틱은 `soul_cinematic`.
4. **학습 제출.** 현재 연결의 학습 도구(Claude MCP 예: `show_characters(action:'train', name, medias[])`)에 라이브 스키마대로 제출한다. 비차단 작업이다.
5. **상태 확인.** 현재 연결의 캐릭터 상태 도구(Claude MCP 예: `show_characters(action:'status', soul_id)`)로 조회한다. 폴링은 조용히 — 진행 상황을 반복 보고하지 않는다.
6. **인계.** 직접 Soul 모델에 쓸 때만 `soul_id`를 `generate_image`의 `params.soul_id`로 넘긴다. 모델은 `soul_2` 또는 `soul_cinematic`. 다른 모델에서 재사용하려면 연결의 Elements 목록에서 **기존 캐릭터 참조를 찾아 선택**한다. 있으면 그 Element ID를 재사용하고 새 Element를 만들지 않는다. 없으면 자동 연동을 가정하지 말고 필요한 이미지와 새 Element 생성 여부를 코어의 질문·blocker 계약으로 확인한다.

기존 Soul 조회도 현재 연결의 캐릭터 목록 도구로 모든 관련 상태와 페이지를 확인한다. Claude MCP의 `show_characters(action:'list', status:'ready')`는 상태별 조회의 한 예시다.

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

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

1. **기존 참조 조회.** `show_reference_elements(action:'list')`에서 해당 캐릭터·제품·환경의 기존 Element가 있는지 확인한다. 학습된 Soul을 재사용하는 요청이면 먼저 해당 캐릭터가 Elements에 나타나는지 찾는다. 후보가 여러 개면 코어의 질문·blocker 계약으로 고르고, 없으면 새 생성 여부를 같은 계약으로 확인한다. 하위 에이전트는 질문 도구가 보여도 blocker를 상위에 반환한다.
2. **필요할 때만 이미지 준비.** 기존 Element를 재사용하면 업로드하지 않는다. 새 Element를 명시적으로 만들 때만 0단계 얼굴 동의 게이트를 거친 뒤 이미지를 업로드한다. `medias[]` 항목은 `{id, url, type}` 형태이며 `type`은 `media_input`(업로드) 또는 `image_job`(이전 생성).
3. **필요할 때만 생성.** 새 Element를 선택한 경우 `show_reference_elements(action:'create', medias[])`를 호출한다. `category`는 기본 `auto`(서버 분류)로 두고, 사용자가 명시할 때만 `character`/`environment`/`prop`을 지정한다. `name`은 32자 이내이며 생략하면 서버가 자동 부여한다.
4. **사용.** 기존 또는 새 Element의 사용 가능 상태를 확인하고, 해당 id를 `generate_image`/`generate_video`의 `params.prompt` 안에 `<<<element_id>>>` 형태로 끼워 넣는다. 대상 모델이 Element를 지원하는지 라이브 조회한다.

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

## 비용·계정 전제

- Soul 학습은 **유료 플랜(Basic 이상)**을 요구한다. 무료 플랜이면 제출 전에 알린다.
- 학습 자체와 이후 생성은 별개 비용이다. 실제 생성 직전 연결 프로필에 맞는 비용 조회는 코어 규칙을 따른다.
- 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] 업로드 동의와 유료 학습 승인은 서로 다른 게이트다. 각각 코어 `media-higgsfield-core` §승인 요청 계약을 따른다. 현재 앱에 질문 채널이 없으면 직접 대화 중에도 승인서를 산문으로 묻지 않고 blocker로 반환한다. blocker에는 다음을 모두 담는다:

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

**[HARD] 승인 응답을 받지 못하면 업로드나 학습을 실행하지 않는다.** 도구 실행 권한 프롬프트는 얼굴 업로드 동의나 크레딧 승인으로 간주하지 않는다.

> 이 게이트는 연결된 데스크톱 앱과 운영체제에 관계없이 동일하게 적용한다.

---

## 관련 스킬

| 스킬 | 시점 |
|---|---|
| `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). 학습 사진 기준·실패 원인은 이 문서 기반.
- [Higgsfield Soul ID 웹 도움말](https://higgsfield.ai/creator-hub/help-center/ai-models/how-do-i-create-and-use-a-soul-id-character) — 웹 학습은 20~80장으로 안내한다. CLI 스킬의 5~20장 제한을 웹·MCP에 그대로 적용하지 않는다.
- 같은 웹 도움말은 학습된 캐릭터가 Elements에 나타나 Seedance에서 사용될 수 있다고 설명한다. 실제 연결의 Elements 목록과 모델 지원은 별도로 확인한다.
- 라이브 MCP 도구 스키마 관측 (`show_characters` / `show_reference_elements`) — Soul/Element 분기 규칙·지원 모델 목록·업로드 제약의 근거. **Evidence tier: 1차.**
- 공식 CLI 스킬에는 Element 경로와 분기 규칙이 없다. 그 부분은 MCP 스키마 관측이 유일 출처다.