README.md

---
title: Character Studio
emoji: 🎭
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: Multi-model character generator on ZeroGPU
---

# 🎭 Character Studio

A Hugging Face **ZeroGPU** Space that bundles many image models behind one UI for
character generation. Pick a model from an **editable registry**, type a prompt,
optionally drop a **reference image**, and generate.

## Features
- **Editable model registry** — add / remove models by editing `models.json`, no code change.
- **Multiple base families** — SD1.5, SDXL, FLUX. Each model declares its own `base`.
- **Multiple input modes** — `txt2img`, `img2img`, `IP-Adapter` (style/subject), `Face identity` (FaceID).
- **Custom sources** — HF repos, full `.safetensors` checkpoints, and Civitai download URLs.

## Hardware
Set the Space hardware to **ZeroGPU** (Nvidia, dynamic). Free tier works; pipelines
are cached on CPU and moved to GPU only during a generation call.

## Secrets / environment variables (Settings → Variables and secrets)
- `HF_TOKEN` — needed only for **gated** models (e.g. FLUX.1-dev). Optional otherwise.
- `CIVITAI_TOKEN` — needed only if a registry entry pulls from a Civitai download URL.

## Adding / removing models
See **README_TH.md** for the full Thai field guide. Quick version: each entry in
`models.json` looks like:

```json
{
  "id": "my-model",
  "label": "My Model (SDXL)",
  "base": "sdxl",
  "type": "checkpoint",
  "repo_id": "author/repo-on-hf",
  "single_file_url": null,
  "default_steps": 30,
  "default_guidance": 6.0,
  "enabled": true
}
```

For a LoRA, set `"type": "lora"`, keep `repo_id` as the **base checkpoint**, and add
either `lora_repo_id` (+ optional `lora_weight_name`) or `lora_url` (Civitai), plus
`lora_scale`. After editing, click **🔄 Reload models** in the UI.

## Notes
- IP-Adapter and Face identity modes are available for **SD1.5 / SDXL** only; FLUX
  supports `txt2img` / `img2img`.
- Face identity uses InsightFace (`buffalo_l`) + IP-Adapter-FaceID and needs a clear face.
- Only one large model is held in memory at a time; switching models reloads.

## Responsible use
This tool is for original character art and authorized creative work. Do not use the
Face identity feature to depict real people without their consent.