---
license: openrail++
license_name: tokforge-sdxl-ipadapter-bundle
tags:
- text-to-image
- image-to-image
- stable-diffusion
- stable-diffusion-xl
- sdxl
- ip-adapter
- realvisxl
- reference-image
- identity
- multi-subject
- safetensors
- stable-diffusion-cpp
- tokforge
base_model:
- SG161222/RealVisXL_V4.0_Lightning
- h94/IP-Adapter
pipeline_tag: text-to-image
---

## TokForge

- **Website:** https://tokforge.ai
- **Discord:** https://discord.gg/Acv3CBtfVm
- **Google Play:** https://play.google.com/store/apps/details?id=dev.tokforge
- **iOS TestFlight:** https://testflight.apple.com/join/jnufjzRr

Runs on-device in the TokForge app.

# TokForge — SDXL IP-Adapter (Reference Identity) bundle

The **highest-fidelity reference-identity** image route for the [TokForge](https://tokforge.ai)
Android app, and the **clean multi-subject** path. Attach a photo of a person (or two),
then render **that person** in any scene (*"me as a superhero, unmasked, face visible"*).
The **plus-face** IP-Adapter transfers the **face only** while the **prompt drives the
whole scene**. SDXL's stronger plus-face transfer (vs SD1.5) gives sharper single-subject
identity, and makes the regional-mask **two-subject** path produce two distinct recognizable
faces.

This bundle runs on the on-device [`stable-diffusion.cpp`](https://github.com/leejet/stable-diffusion.cpp)
engine (TokForge's IP-Adapter port) on **CPU** and **Adreno OpenCL**. Full SDXL is heavier
than the SD1.5 IP-Adapter tier — this is offered on **16 GB-class** phones. For 8 GB phones,
use the lighter [`darkmaniac7/TokForge-SD15-IPAdapter`](https://huggingface.co/darkmaniac7/TokForge-SD15-IPAdapter)
tier instead.

## Files

| File | Size | License | Contents |
|------|------|---------|----------|
| `realvisxl-v40-lightning-fp16.safetensors` | ~6.9 GB | OpenRAIL++ | **RealVisXL V4.0 Lightning** (SDXL photoreal finetune) — dual CLIP text encoders + UNet + VAE in one self-contained **f16** sd.cpp safetensors |
| `ip-adapter-plus-face_sdxl_vit-h.safetensors` | ~848 MB | Apache-2.0 | IP-Adapter **plus-face** SDXL (`h94/IP-Adapter`) — 16-token image_proj Resampler + 70 decoupled cross-attn layers (`cross_attention_dim` 2048) |
| `ip_adapter_clip_vision_vith.safetensors` | ~2.5 GB | MIT | OpenCLIP **ViT-H-14** image encoder (1280 hidden, 32 layers). The plus-face path needs ViT-H, **not** bigG — the same encoder the SD1.5 plus-face bundle ships |

`manifest.json` and `MD5SUMS` carry the integrity hashes + render defaults.

### Why this base, and why f16 (not Q4)

The base is **RealVisXL V4.0 Lightning** — the same self-contained SDXL safetensors the
TokForge "RealVisXL SDXL Quality" tier ships, a strong photoreal SDXL finetune distilled
for a **few-step** (6-step) Lightning floor. It is kept at **f16** (full precision) so the
IP-Adapter's decoupled cross-attention and the face Resampler keep **subject quality** high.
A `q4_0` base measurably weakens the transferred identity, so this bundle deliberately uses f16
(matching the SD1.5 tier's quality choice).

### Why plus-face + ViT-H (not the base SDXL adapter + bigG)

The standard `ip-adapter_sdxl` projects the whole pooled CLIP-**bigG** embedding → it drags the
reference's *entire scene* through. The **plus-face** variant (`ip-adapter-plus-face_sdxl_vit-h`)
runs a 16-token Resampler over the **ViT-H** penultimate hidden state → it extracts the **face
only**, so identity is preserved while the **prompt** controls the scene. Because this adapter is
the `_vit-h` build (`image_proj.latents` shape `[1, 16, 1280]`), it pairs with the **ViT-H**
encoder (1280 hidden) — **not** the bigG encoder (1664 hidden) the base SDXL adapter uses. The
TokForge sd.cpp IP-Adapter loader auto-detects plus-face by `image_proj.latents` and the SDXL
adapter config (2048-dim, 70 layers) by the SDXL base.

## How TokForge uses it

In the app (16 GB+ phones): **Image** model picker → download **"SDXL IP-Adapter (Reference
Identity)"** → attach a face photo as a reference under chat → prompt the scene. The engine is
invoked as:

```bash
sd -M img_gen \
   -m realvisxl-v40-lightning-fp16.safetensors \
   -p "as a superhero, unmasked, face visible, detailed face" \
   -n "<strong negative>" \
   --clip_vision ip_adapter_clip_vision_vith.safetensors \
   --ip-adapter ip-adapter-plus-face_sdxl_vit-h.safetensors \
   --ip-adapter-image <your_face.jpg> \
   --ip-adapter-scale 0.75 \
   --cfg-scale 2.0 --sampling-method euler --scheduler discrete \
   --steps 6 -H 1024 -W 1024
```

### Recommended render settings

| Setting | Value |
|---------|-------|
| sampler | `euler` |
| scheduler | `discrete` |
| steps | `6` (Lightning few-step floor) |
| cfg-scale | `2.0` (Lightning low-CFG) |
| ip-adapter-scale | `0.75` (keeps the scene with strong recognizable identity; lower ≈ more scene freedom, higher ≈ closer to the reference) |
| resolution | `1024×1024` (SDXL native) |

> Plus-face transfers the **face only**, so the rendered face must stay **visible and
> unobstructed** for a recognizable identity. Keep the face in frame ("unmasked, face visible,
> detailed face, looking at viewer") — the app appends this cue automatically.

## Licenses

This is an aggregate of three independently-licensed components — each retains its own license:

- **RealVisXL V4.0 Lightning base** (`realvisxl-v40-lightning-fp16.safetensors`) — **OpenRAIL++** ([SG161222/RealVisXL_V4.0_Lightning](https://huggingface.co/SG161222/RealVisXL_V4.0_Lightning), the SDXL `openrail++` license). Use must comply with the OpenRAIL++ use-based restrictions.
- **IP-Adapter plus-face (SDXL, ViT-H)** (`ip-adapter-plus-face_sdxl_vit-h.safetensors`) — **Apache-2.0** ([h94/IP-Adapter](https://huggingface.co/h94/IP-Adapter)).
- **OpenCLIP ViT-H-14 image encoder** (`ip_adapter_clip_vision_vith.safetensors`) — **MIT** (OpenCLIP / LAION ViT-H-14).

> The non-commercial **IP-Adapter-FaceID** / InsightFace path is **NOT** used here — only the
> Apache-2.0 base + plus-face adapters from `h94/IP-Adapter`.

## Provenance

- Base: `realvisxl-v40-lightning-fp16.safetensors`, the self-contained sd.cpp SDXL safetensors
  built from `SG161222/RealVisXL_V4.0_Lightning` (the same base the TokForge RealVisXL SDXL tier ships).
- Adapter + image encoder copied verbatim from `h94/IP-Adapter`
  (`sdxl_models/ip-adapter-plus-face_sdxl_vit-h.safetensors`, `models/image_encoder/model.safetensors`).