README.md

metadata

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:

{
  "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.