🎨 JVision Bridge

사내망 JVision Invoke AI (FLUX.2 Klein 4B) 래퍼 — 캐릭터 시트 참조 + 비율 프리셋 + seed 추적

v1.0.0

10.8.x.x VPN only

FLUX.2 Klein 4B

⚠️ 이 페이지는 10.8.x.x 대역과 127.x에서만 접근 가능 (FastAPI middleware ACL).

📌 핵심 사용 예

curl -X POST http://10.8.0.17:8089/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "haru and luna at sunset cafe", "aspect": "16:9", "characters": ["haru", "luna"]}' \
  -o output.png

# 응답 헤더: X-Seed / X-Image-Name / X-Batch-Id / X-Refs / X-Size

🔧 엔드포인트

POST/generate

원샷 이미지 생성. PNG bytes 직접 반환.

Request body

필드	타입	설명
`prompt`	str (req)	영어 묘사 권장, 최대 2000자
`aspect`	str?	비율 프리셋 (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9) — width/height보다 우선
`width` / `height`	int?	aspect 없을 때 사용 (64~2048)
`seed`	int?	재생산용. 음수 또는 미지정 시 랜덤
`steps`	int?	기본 4 (FLUX.2 Klein 권장)
`characters`	list?	['haru','luna','mori'] 중 일부 — 해당 캐릭터 시트 ref 자동 첨부 (Invoke AI flux_kontext 주입)
`workflow`	str?	기본 'flux2_klein_t2i'

Response headers

헤더	설명
`X-Seed`	실제 사용된 seed (재생산용)
`X-Image-Name`	JVision 갤러리 image_name (UUID)
`X-Batch-Id`	큐 배치 ID
`X-Refs`	첨부된 ref image_name (콤마 구분)
`X-Size`	응답 PNG 바이트 수

POST/generate_async

비동기 — enqueue만 하고 batch_id 즉시 반환. 결과는 /result/{batch_id} 폴링.

GET/result/{batch_id}

배치 상태 조회. 완료 시 첫 이미지 PNG bytes 반환, 미완료 시 status JSON.

GET/aspects

지원하는 비율 프리셋 → width/height 매핑.

{"presets":{"1:1":{"width":1024,"height":1024},"16:9":{"width":1344,"height":768},...}}

GET/refs

캐릭터 시트 ref 캐싱 상태. 자동 업로드된 image_name 목록.

{"cached":{"haru":"3393565d-...png","luna":"a0f732a5-...png"},"supported":["haru","luna","mori"]}

POST/refs/upload/{character}

강제 재업로드. character_refs/{char}.png 교체 후 호출. 캐시 무효화 + 재업로드.

GET/models

JVision에 install된 모델 전체 목록 (메인 / VAE / Text Encoder / LoRA).

GET/workflows

JVision의 워크플로우 목록 (default + user).

GET/healthz

헬스 체크 — JWT 만료 시간, primary failure count 포함.

POST/auth/refresh

JWT 즉시 재발급 (관리용).

🎭 캐릭터 시트 ref

프롬프트에 캐릭터 키워드 포함 시 jv_bridge가 자동으로 시트 이미지를 reference로 첨부 → 외형 일관성 확보.

캐릭터	키워드
haru ☀️	haru, 하루, blonde twintails, yellow hoodie, sun mark/emblem
luna 🌙	luna, 루나, navy hair/wavy/long, crescent moon necklace, blue knit
mori 🃏	mori, 모리, mint-green, heterochromia, violet and gold, card pattern hoodie

자동 카운트는 discordbot/image_gen.py:_detect_characters()가 처리. 수동 호출 시 characters: ["haru","luna"] 명시.

📂 파일 보관

character_refs/{char}.png — 원본 캐릭터 시트 (png/jpg/webp)
character_refs/_uploaded.json — JVision 업로드 후 받은 image_name 캐시
workflows/flux2_klein_t2i.json — 기본 t2i 워크플로우 템플릿

🔐 ACL

환경변수 BRIDGE_ALLOWED_PREFIXES="10.8.,127." — 콤마 구분, prefix 매칭. 그 외 모든 IP는 403.

JVision Bridge · 사내망 전용 · Swagger UI · /healthz