Character Card

What Is a Character Card?

A character card is a JSON object that describes a roleplay character, and it is usually embedded in a PNG image so a single file holds the portrait and the definition. SillyTavern's documentation calls it "a collection of prompts that set the behavior of the LLM" and says a card can hold "an abstract scenario, an assistant tailored for a specific task, a famous personality or a fictional character".

Think of it as a portable character prompt with labeled fields; writing advice is in our guide to writing a character prompt.

Character Card V1, V2 and V3 Compared

V3 is described as a superset of V2 except for changed or removed fields.

V1 fields are plain strings that default to empty. In text, {{char}} or <BOT> becomes the card's name and {{user}} or <USER> becomes the user's display name.

What the Fields Do

V2 added the fields frontends care about most. By default, system_prompt replaces the user's global system prompt unless it is empty, and post_history_instructions does the same for the "jailbreak" setting; both support an {{original}} placeholder. The alternate_greetings array holds extra first messages that frontends must offer as swipes. The creator_notes field must not be used inside prompts. The extensions field takes arbitrary key-value pairs, and unknown keys must be preserved.

The optional character_book is a lorebook of extra world facts: entries with keys, content and an insertion order, plus book settings such as scan_depth and token_budget. V3 changes it to a lorebook object and adds fields such as use_regex.

How PNG Embedding Works

V1 and V2 store the card as a base64 JSON string in a text metadata field of a PNG or APNG file (the V1 document capitalizes it as Chara, V2 uses chara), so the picture displays normally while the data rides along. V3 uses a tEXt chunk named ccv3 with base64 UTF-8 JSON. Applications should prefer ccv3 over chara when both exist. V3 also defines a .charx ZIP with card.json at the root plus the assets it references.

Character Cards in Apps

• SpicyChat: imports Character.AI card files in JSON or PNG. Its docs do not say which spec version they follow. See the SpicyChat review.
• CrushOn.AI: lets you import a character from another platform as a JSON file. See the CrushOn.AI review.
• Janitor AI: we found no card import documented, but its fields (personality, scenario, initial message, example dialogue) resemble card fields. See Janitor AI.
• Character.AI: its Character Definition (up to 32,000 characters) uses {{char}} and {{user}} placeholders and allows up to five extra greetings, similar to alternate_greetings. We found no card export documented.
• Muah AI: its community characters browser lists card import, format not stated.
• Local tools: SillyTavern is built around cards, and KoboldCpp imports Tavern character cards.

Cards from public hosts can contain adult or unlawful content, so check a card before importing it. See also apps with custom characters, how to build an AI character and the rest of the glossary.