| 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') 로 실제로 생성됐는지 먼저 확인하고, 없다는 것이 확인된 뒤에만 다시 제출한다.
승인 뒤 실행 절차
- 이미지 준비. 로컬 경로는 받지 않는다.
media_upload → 바이트 PUT → media_confirm 순서로 올려 media_id UUID를 얻는다. 완료된 이미지 잡 ID나 https URL도 허용된다.
- 품질 점검. 5
20장, 권장 812장. 각도·조명·표정·거리가 다양할수록 좋다. 상세 기준은 references/training-photo-guide.md. 기준 미달이면 학습을 제출하기 전에 사용자에게 알린다.
- 타입 선택. 다운스트림 용도로 정한다 — 정지 이미지는
soul_2, 시네마틱은 soul_cinematic.
- 학습 제출.
show_characters(action:'train', name, medias[]). 비차단이며 약 10분 소요.
- 상태 확인.
show_characters(action:'status', soul_id). 폴링은 조용히 — 진행 상황을 반복 보고하지 않는다.
- 인계. 준비되면
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라서 학습이 없으니 괜찮다"는 이유로 건너뛰지 않는다.
- 이미지 준비. Soul과 동일한 업로드 절차.
medias[] 항목은 {id, url, type} 형태이며 type은 media_input(업로드) 또는 image_job(이전 생성).
- 생성.
show_reference_elements(action:'create', medias[]). category는 기본 auto(서버 분류)로 두고, 사용자가 명시할 때만 character/environment/prop을 지정한다. name은 32자 이내이며 생략하면 서버가 자동 부여한다. 동기 반환이다.
- 사용. 반환된 element id를
generate_image/generate_video의 params.prompt 안에 <<<element_id>>> 형태로 끼워 넣는다. 한 프롬프트에 여러 개를 넣을 수 있다.
- 조회.
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 문서) —
higgsfield-soul-id 스킬 v0.12.0 (MIT). 학습 사진 기준·실패 원인은 이 문서 기반.
- 라이브 MCP 도구 스키마 관측 (
show_characters / show_reference_elements) — Soul/Element 분기 규칙·지원 모델 목록·업로드 제약의 근거. Evidence tier: 1차.
- 공식 CLI 스킬에는 Element 경로와 분기 규칙이 없다. 그 부분은 MCP 스키마 관측이 유일 출처다.
