Characters & LoRAs
A character is the name that ties one person together in FlixML: the LoRA that draws them on each workflow, the voice they speak in, who owns them, and every image and video made of them.
A character doesn’t describe anyone’s look. Each model wants a look written its own way, sentences for one and tags for another, so your agent writes it into every prompt in the form that model reads. Without a LoRA, the likeness is whatever the prompt describes.
What a character carries
Section titled “What a character carries”- LoRAs, one per workflow, each with a trigger word. Name the character in a job on that workflow and FlixML loads its LoRA and puts the trigger word in the prompt. On a workflow it has no entry for, nothing loads and no trigger is added. Naming a character doesn’t change any of the workflow’s other settings.
- A voice. Speech generated for the character uses it.
- An owner, the account that created it. Only the owner and admin keys can name it in a job, and the owner sees every image and video of it. See API Keys & Access.
- Pictures. The first is its avatar in Studio’s character list. Generation doesn’t use them.
Every job that names a character files its images and videos under that character, so the gallery can show everything made of one person.
Making one
Section titled “Making one”Your agent creates a character through the API when it needs one, and changes it the same way: create a character, update a character. Only id and name are required, and the rest can be added later. A new character belongs to the key that creates it and shows up in Studio’s sidebar under Characters & LoRA Training.
Training a LoRA
Section titled “Training a LoRA”FlixML trains character LoRAs through the API on AI Toolkit, running on a GPU you point it at:
| Variable | Description |
|---|---|
AITK_API_URL |
AI Toolkit UI URL |
AITK_API_TOKEN |
Required. The AI_TOOLKIT_AUTH value the trainer was started with |
AITK_GPU_IDS |
GPU IDs to train on (optional) |
Setup, datasets and captions: Training a LoRA. Full training endpoints and payloads are in the Agent API and SKILL.md.
Character match
Section titled “Character match”Optional. Every image of one character gets a score for how closely its face matches the rest of that character’s gallery, shown on the image’s card. In a picture with several faces, the one closest to the character is scored. Sort → Best match puts the closest first and Sort → Lowest match the furthest, which is where the misses collect; GET /api/listing?sort=match and ?sort=match_asc do the same through the API. The reference is the character’s own gallery, so deleting the images that miss keeps it accurate.
It needs two things Studio doesn’t install for you. From the repo root:
pip install -r requirements-face.txtand an InsightFace model pack, a folder holding a face detection and a face recognition .onnx, in ~/.insightface/models/buffalo_l. Studio never downloads the models: InsightFace’s code is MIT, but its pretrained models are licensed for non-commercial research only, so whether you can use them is your call. Restart the API and existing images are scored in the background, on the API host’s CPU. Without the packages or the models, Studio runs as before and images carry no score.
Scores are cosine similarity, higher is closer. Faces narrower than 150 px score less reliably and show dimmed. A character needs 5 images with a clear face before its images get a score.