SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscharacter-refs

character-refs

Design & creation

View repository

Updated 10-15 21:39

About this skill

character-refs

Input a character description, output a set of character reference images—The character can come from anywhere: a novel adaptation, a story you made up, or a person you thought of on the spot.One front-facing full-body anchor, and every other image references only this anchor. Use them as reference images for video models (H3 / Wan / Seedance), and for people to look at too.

{baseDir} = the directory this file is in. Script {baseDir}/scripts/character-refs.mjs, zero dependencies,node run it directly.

**This is the only skill in the repository that actually produces images.** The other skills only deliver prompts, because the model and art style can only be decided at the moment of image generation; this skill is that "moment"—the model is chosen by the user at Step 0, and the art style is chosen when creating the character (default is anime, with a realistic preset also available, and custom art styles can be attached too).

Core rules (read and understand before starting)

  • **A set of images has only one root: the front-facing full-body anchor.** Only it is text-to-image; all the rest are "anchor + one image-editing instruction". The three types of details—hair, face, and collar—additionally attach a confirmed front-facing headshot. Images no longer reference each other— so if any one image turns out badly, just regenerate that one image individually, and there will be no chain reaction.
  • Tiers, by default produce up to the second tier：
Tier Content When to produce
1 Front-facing full body (anchor) Always, the first image
2 (default) Front-facing headshot, 90° side view (facing the right side of the frame), back view Produced by default, all of them
3 Detail images (up to 8): the ones the user names, or the places where the character is most recognizable; if none, use the default hair / hair accessory, collar, cuffs, shoes Close-ups of accessories or parts of the clothing
4 (not produced by default) 45° headshot (facing the left side of the frame) The user explicitly asks for it

H3 testing: with only the front-facing full body, the clothing and back view are correct, but the face goes off-model;add one headshot, and the face is closest. So by default produce the full second tier. If only the anchor is wanted (for example, to first see what the character looks like before deciding):gen <asset.json> --tier 1。

  • The model is not locked: the main image and derived images can use different models, and regenerating a single image can also switch models. Consistency comes from "the same anchor", not from "the same model" (tested: Qwen anchor + GPT derivation, GPT anchor + Qwen derivation, and mixed use within the same set all connect properly). Each image records its own model; mixed use within the same set is only noted in the report.
  • Only three things are frozen: the anchor file (sha256), the art style snapshot, and the text description fingerprint. If any one of them changes, the images that depend on it are marked "outdated"—mark only, do not delete, and all old versions are kept.

Step 0 — Initial setup (once per machine)

node {baseDir}/scripts/character-refs.mjs config --show

If "Still missing: ..." is written at the end of the output, ask the user about these three things,ask them all at once：

  1. Which model is used for the main image (anchor)：
    • qwen — Qwen Image 2.1, running on your own ComfyUI server. Fast (25–45 seconds per image), exact dimensions, does not consume subscription quota. Requires COMFY_URL(optional COMFY_USER / COMFY_PASS), placed in an environment variable or a .env file
    • codex — codex built-in image generation (GPT). No API key needed, butconsumes ChatGPT subscription quota(Plus hits the cap at about 25 images, recovers after a few hours), 80–160 seconds per image
    • openai — OpenAI Images API, default gpt-image-2. Pay-per-use, requires OPENAI_API_KEY; can also point to a compatible endpoint (--openai-base-url）
    • custom:<名字> — the user's own image generation command, see references/models.md
  2. Which model is used for derived images: defaults to the same as the main image. Can be separated (e.g. anchor GPT, derived Qwen)
  3. After the anchor is generated, should it stop and wait for human confirmation: recommended yes— the anchor is the root of the whole group; if it is wrong, everything after it is wasted. Choosing no auto-approves it, and the report marks it as "not human-confirmed";anchors that fail the check gate will not be auto-approved, requiring a human to review it before confirm or regenerating
node {baseDir}/scripts/character-refs.mjs config --model qwen --confirm-anchor yes --qwen-env-file <.env 路径>
# 分开设置：--anchor-model codex --derive-model qwen

The configuration is written to {baseDir}/config.local.json(not under version control, not overwritten on reinstall). From then on it is used by default; if the user says "switch to xx", rerun config。Do not print the passwords or keys from .env，config --show has been masked.

Step 1 — One-time input

The usera paragraphdescribing the character is enough; do not ask item by item. You (the model) break it down:

node {baseDir}/scripts/character-refs.mjs intake-template

Following the template, break the description into the fields and write them to <工作目录>/<角色名>-intake.json. Rules (see references/intake.md）：

  • lang Fill in the language the user speaks (Chinese zh, English en, Japanese ja are built in). The confirmation table and report both use this language; for other languages, first run ui-template <lang>, translate the printed English text item by item, and put the whole block into the intake's ui field
  • Mark what the user said as stated, mark what you inferred as inferred, and mark what was filled in by convention as default——Mark truthfully; the confirmation table relies on it to remind the user which items to check
  • If age, gender, or era cannot be inferred, ask the user; only these three may not be made up by yourself; fill in everything else yourself, do not ask follow-up questions
  • en into the prompt:always English, do not write the character name, do not write style words;text is for people to read, write it in the language of lang (the zh written in old inputs is still recognized)
  • Clothing is split into top / bottom— a headshot only uses the top; if the bottom is included, the model will pull the camera back
  • Detail images are chosen according to the character: items named by the user take priority; if none are named, choose the places that best identify this character, with four default slots as a fallback; facial features do not get detail images (they are already clear in the headshot). See references/intake.md
node {baseDir}/scripts/character-refs.mjs intake-check <intake.json>

If there are problems, fix them according to the error until it passes. Once it passes, it prints theconfirmation table, show it to the user as-is; inferred and defaulted items carry markers. Only after the user confirms (or makes changes and confirms again) do you proceed.

Step 2 — Build assets

node {baseDir}/scripts/character-refs.mjs new <intake.json> --out <输出目录> [--look 画风]

Build out <输出目录>/<角色名>/asset.jsonThe art style layer snapshots into the asset at this point; later changes to the preset do not affect existing characters.

Art style: if the user says so, use what the user says; if not, it's anime. Characters in the same showall use the same art style。

preset --look recognized name
Anime (default) 动漫 卡通 anime cartoon 二次元 アニメ
Realistic photo 写实 realistic photo 真人

looks List all presets. User wants another art style (Chinese style, American comic...):look-template <最接近的预设> > my-look.json, change style(medium, linework), clean(background and light,must keep a white background）、neg(negative prompt — to switch to a drawn art style, remove anime illustration from the negative prompt), for a drawn art style write medium as drawn, then --look my-look.json. Custom art styles have not been tested; generate an anchor first to see the result.

To change the art style of an already created character:

node {baseDir}/scripts/character-refs.mjs restyle <asset.json> --look 动漫

After the change, all existing images (including the anchor) are marked outdated; old images are kept, and regeneration starts from the anchor.

Step 3 — Generate the default second tier

node {baseDir}/scripts/character-refs.mjs gen <asset.json>

Without views and tiers specified, it fills in the not-yet-generated, outdated images in the first and second tiers.

Confirmation is configured: this commandstops after generating only the anchor. Show the image to the user (report or open the PNG directly); once the user says it's OK, then

node {baseDir}/scripts/character-refs.mjs confirm <asset.json>
node {baseDir}/scripts/character-refs.mjs gen <asset.json>      # 同一条命令，接着出大头照、侧面、背面

If not satisfied, run gen <asset.json> front-fullagain (generates v2, you can --seed change the seed,--model change the model), or go back to Step 1 and change the description. **If the anchor is not confirmed, derived images will be rejected.** When configured not to confirm, one command generates all four images.

Step 4 — Upgrade tiers on demand

node {baseDir}/scripts/character-refs.mjs gen <asset.json> --tier 3 --reason "E03 有发饰和领口特写"

--reason Write why the tier is being upgraded, record it in the asset. You can also generate only certain images:gen <asset.json> detail-hair detail-neck。

Step 5 — Check and regenerate

node {baseDir}/scripts/character-refs.mjs check <asset.json>

Each image passes the code gate (size 300–5760, aspect ratio 0.4–2.5, proportions match, ≤20MB, background white enough), then check for outdated. **If there is a problem, exit 1.** For those that fail the gate or are outdated, regenerate that single image:

node {baseDir}/scripts/character-refs.mjs gen <asset.json> detail-neck --model codex

In the gate, "background white enough" checks all four sides for full-body images, and only the top and the upper half of both sides for headshots (the body naturally reaches the bottom), and is skipped for detail images with an explicit note. The gate cannot check appearance, angle, or framing— after generating, you must look at the images; these items rely on your eyes.

Step 6 — Report

node {baseDir}/scripts/character-refs.mjs render <asset.json>... --out <输出目录>/character-refs.html

Multiple characters can be generated together. The language defaults to the asset's lang; to temporarily change it, add --lang en; for a non-built-in language without ui , use --ui <文件> to pass self-translated copy, missing copy will directly error out; it will not produce a half-Chinese half-English report. UI copy changes language, character descriptions stay in the original text. The first tier has only one card; from the second tier on it is a character sheet layout (headshot on the left, front / side / back on the upper right, detail strip on the lower right), detail images are hidden by default, toggle with one click on the page. Outdated images have a red frame icon; there is a legend at the top of the page, and hovering over a red-framed image shows the reason; mixing models triggers a reminder.

Step 7 — Report back

One sentence: which images were generated, which model was used, report path. Name any that failed the gate or are outdated.Don't say "the result is great" if you haven't looked at the images.

Landing structure

<输出目录>/
├── character-refs.html          ← render 产出
└── <角色名>/
    ├── asset.json               ← 角色描述 + 每张图的全部版本
    └── default/                 ← 造型（v1 只有 default 一套）
        ├── front-full.v1.png    ← 锚点
        ├── face-front.v1.png
        ├── face-front.v2.png    ← 重出不覆盖
        └── detail-hair.v1.png …

Every PNG has written in it the identifier (角色/造型/视图/版本), model, and which images it referenced, so its origin can be traced even if the image is copied elsewhere. asset.json For the structure of references/schema.md。

Boundaries

  • The art styles I've actually tested are only two: realistic and anime (both run through four tiers on Qwen); the effect of a custom art style depends on how it's written, so generate an anchor first and see
  • Detail images only include things that grow on the character (hair ornaments, collar, cuffs, shoes); props go to novel-art
  • Known shortcomings: small scars tend to be drawn as fresh wounds, large-area details like double-breasted rows are framed too far away, Qwen's collar details draw coarse cloth looking like velvet (switch to codex to regenerate this one), and skin exposed in Qwen detail images tends to look old (an age sentence has been added to the prompt, effective on a 16-year-old sample, not extensively verified)
  • openai The adapter has only been verified for request format using a local fake server,it has not been run with a real key; when using it for the first time, generate an anchor first and see
  • The same set of prompts has been actually tested on both Qwen and GPT; the effect of a custom model depends on that model

Self-test

node {baseDir}/scripts/selftest.mjs

233 assertions, no model calls, no quota spent: PNG signature read/write, check gates, input validation, multilingual confirmation table and report, art style presets and style switching, prompts, expiration propagation, request format of the image generation adapter (Qwen and GPT Image use a local fake server), as well as the complete flow run through a custom command. Run this first after changing the script.

Built-in sample

{baseDir}/examples/阿禾-描述.txt is a user-style one-sentence description (a Jiangnan tea-picking girl in the 1920s), 阿禾-intake.json is the broken-down input, with inferred and default fields marked. Sample images are not under version control; if you want to see them, run it once with your own model.