On this page

AI Pose Gallery character reference and three-in-one synthesis workflow

Document type
Field manual
Updated
Reading time
10 min

Configure ai-pose-gallery-zh with 6,162 Chinese pose, costume, and portrait records, Web Studio, ComfyUI custom nodes, and 9 Agent skills, including Qwen Image Edit 2509 workflows and asset license limits.

Source
Document details
anhao/ai-pose-gallery-zh
License
MIT

Combine pose mannequins, depth maps, costumes, and portraits from a localized index to assemble character generation recipes through the Web Studio, ComfyUI nodes, or Agent skills.

Indexed records
6,162Poses 1,439, costumes 3,224, portraits 1,499
Local image files
12,022Plus 1,760 remote reference images
Agent skill packs
9Covering pose, costume, and portrait lookup

01Dataset scale, interfaces, and scope

System purpose

ai-pose-gallery-zh (version 2.0.0) consolidates three Japanese AI drawing reference sites by Gia (@giaaibusi) and incorporates CharaDB anime outfits by Taki AI (@taki_auto) along with Chinese historical outfits from wquguru/shisei. The repository includes a React synthesis workbench, ComfyUI custom nodes, a Cloudflare same-origin proxy, and 9 Claude Code/Agent reference lookup skills.

DatasetCovered categories and viewsIndexed recordsImage storage
Pose mannequins (/poses)Full-body single standard 365, sexy 399, upper-body 400, couple 275; 26 categories, 5 camera angles1,4392,878 local files (.jpg thumbnails and .png originals)
Pose depth maps (POSE-DB-02)One-to-one mapping with the 1,439 pose IDs1,439 (shared index)2,878 local files (.webp thumbnails and originals)
Realistic costumes (Gia)8 categories (spring, summer, autumn, winter, lingerie/sleepwear, sexy, swimwear, party/formal) and 86 Chinese tags1,4072,814 local files (.webp thumbnails and originals)
Chinese historical costumes (Shisei)Shang-to-Qing HC outfits supporting front, diagonal, side, and back across 227 valid views57454 local files (w300/w900 .webp, about 5.77 MiB)
Anime costumes (Gia anime)8 Chinese categories matching the realistic set, prefixed with gia-anime-1,320Metadata snapshot only; images load directly from the upstream site
Anime costumes (CharaDB)15 categories with Chinese names and English Danbooru tags440Metadata only; images load directly from the upstream site
Portrait references (/portraits)Front face 893, styling mood 606; 4 hair lengths and 51 hairstyle subcategories1,4992,998 local files (thumbnails and 1600×2000 .webp originals)
Character reference and generation architecture

  1. Reference data layer

    • 12,022 local WebP/PNG/JPG files
    • 1,760 remote anime costume images
    • data/*-zh.json localized indices

  2. Assembly and interface layer

    • Web Studio 3+N recipes and collage
    • 4 ComfyUI custom nodes
    • 9 Agent skills in skills/

  3. Generation execution layer

    • Gemini / GPT Image / Qwen / Doubao APIs
    • Local ComfyUI queue and WebSocket
    • IndexedDB task and history storage

The Web Studio and ComfyUI plugin share data/ and img/; remote anime costumes load only when allowlist and format checks pass.

Line 37 of the README retains an older prose count of 11,568 images (before adding the 454 Shisei files), and the directory tree comment on line 139 retains an older 4,785 figure; the version 2.0.0 data table totals 6,162 indexed records and 12,022 local image files. The README table also lists Shisei originals as .png, whereas docs/SHISEI-COSTUMES.md and data/shisei/images-manifest.json store both w300 and w900 assets as .webp.

02Web Studio, ComfyUI plugin, and Agent skills

Installation and verification

  • Not completed:

    Frontend development requires Node.js 20 or later and pnpm (package.json specifies Vite ^8.3.5, React ^19.3.1, and TypeScript ~7.0.2).

  • Not completed:

    Data maintenance scripts and ComfyUI custom nodes require Python 3; the ComfyUI plugin reuses the torch, numpy, Pillow, and aiohttp packages bundled with ComfyUI.

  • Not completed:

    The local three-image synthesis workflow requires ComfyUI 0.3.60 or later (tested by the project on 0.43.0) and the Qwen Image Edit 2509 model files.

  • Not completed:

    Agent skills require keeping the full repository structure intact so relative ../../img/ paths in references/catalog.csv resolve to local images.

This report inspected source files and documentation only; it did not start Vite or ComfyUI locally or run any image generation requests.

Route One: Start the local Web Studio

bash
git clone https://github.com/anhao/ai-pose-gallery-zh.git
cd ai-pose-gallery-zh
pnpm install
pnpm dev

When connecting to a local ComfyUI instance, the default /comfy path is proxied same-origin by Vite to http://127.0.0.1:8000. If ComfyUI listens on port 8188, pass the environment variable on startup:

bash
COMFYUI_URL=http://127.0.0.1:8188 corepack pnpm dev

When the browser connects directly to local ComfyUI without the development proxy, start ComfyUI with the --enable-cors-header flag.

Route Two: Install as native ComfyUI custom nodes

bash
cd /path/to/ComfyUI/custom_nodes
git clone --depth 1 https://github.com/anhao/ai-pose-gallery-zh.git

After restarting ComfyUI, right-click on the canvas and open the three-in-one character reference category to add the 4 custom nodes.

Route Three: Link Claude Code / Agent reference skills

bash
git clone --depth 1 https://github.com/anhao/ai-pose-gallery-zh.git ~/ai-pose-gallery-zh
mkdir -p ~/.claude/skills
for d in ~/ai-pose-gallery-zh/skills/*-reference*; do ln -s "$d" ~/.claude/skills/; done

03Four operating routes and API endpoints

Core capabilities

Web synthesis studio

/studio

Assemble 3+N character reference recipes and prompts

Combine portrait, costume, pose (mannequin or depth map), and extra reference images, with 12 style presets and 1800×1200 Canvas three-in-one collage export.

ComfyUI recipe node

CharacterRecipeNode

Output four image tensors and bilingual prompts from one node

Outputs portrait, costume, pose, a horizontal three-in-one collage (12 px gap), and Chinese/English synthesis prompts with 4 built-in style presets.

ComfyUI single-library nodes

PoseGalleryNode / CostumeGalleryNode / PortraitGalleryNode

Load individual reference images and descriptions by ID

Supports original size, center crop, and padded resize (64 to 4096 px, step 8); pose supports use_depth and costume supports costume_view.

Agent pose and portrait skills

pose-reference-* / portrait-reference

Retrieve references by action, camera angle, or 51 hairstyles

Covers standard 365, upper-body 400, sexy 399, couple 275, all poses 1,439, and portraits 1,499 via relative paths in catalog.csv.

Agent costume skills

costume-reference / -anime / -sexy

Search outfits by season, item, color, and Danbooru tags

Covers 1,068 general realistic outfits, 440 CharaDB anime outfits (remote URLs), and 339 lingerie/sexy outfits.

Same-origin CORS proxy

POST /api/proxy

Forward cloud image generation API requests

Uses x-target-url to forward HTTPS requests to DashScope, Volcengine Ark, Gemini, and OpenAI allowlisted origins with a 10 MiB body limit.

The Web Studio supports 5 image generation backends in src/services/aiGenerator.ts and the README:

ProtocolSupported models or endpointsKey parameters and delivery
Google Geminigemini-3.1-flash-image-preview, gemini-3-pro-image-preview, gemini-2.5-flash-imageSupports aspectRatio and 1K/2K/4K resolutions
OpenAI GPT Imagegpt-image-2.5, gpt-image-2, gpt-image-1.5, gpt-image-1Calls /v1/images/edits with JSON URL delivery or multipart upload, size, quality, and background transparency
Alibaba DashScope Qwenqwen-image-3.0-pro, qwen-image-2.1-pro, qwen-image-2.0-pro, qwen-image-edit-plusUses multimodal-generation multi-image input, prompt_extend, and watermark toggles
Volcengine Ark Doubaodoubao-seedream-5-0, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828, doubao-seededit-3-0-i2i-250628Supports multi-image fusion image: [...] and 2K/4K resolutions
Local ComfyUI/upload/image, POST /prompt, /ws, /historyImports .api.json workflows, replaces double-brace variables, or matches CLIPTextEncode/KSampler/LoadImage nodes

04Multi-image fusion, workflow parameters, and cache management

Operating principles

Use pose mannequins for semantics or depth only

In the Qwen Image Edit 2509 workflow, connect only the portrait and costume to ReferenceLatent. Passing the 3D mannequin as a pixel reference copies ball joints and seam lines into the output; enable use_depth with ControlNet when exact skeleton alignment is needed.

Symlink Agent skills instead of copying

Local skill catalogs in references/catalog.csv read images via ../../img/ relative paths. Link skills into ~/.claude/skills/ with ln -s and keep the repository directory intact; copying skill folders breaks image resolution.

Distinguish _meta.studio extensions from standard API JSON

Workflow fields under _meta.studio.controls, hiddenInputs, imageRole, and referenceCombinations are frontend conventions of this project. Some ComfyUI canvas-to-API exporters strip custom _meta fields, so retain the API file that contains those declarations.

Lower megapixels first on 8 GB GPUs

The Qwen Image Edit 2509 fp8 diffusion model is 20.4 GB and the text-vision encoder is 9.4 GB. On an 8 GB GPU, lower node 10 megapixels to 0.6; the studio calls /free to release VRAM when memory runs out.

When importing a custom ComfyUI API workflow, the studio replaces double-brace variable names (prompt, seed, width, height, composite_image, portrait_image, costume_image, pose_image) with the active recipe values and uploaded filenames. When cfg=1 (such as with the 4-step Lightning LoRA), negative prompts have no effect; put exclusions such as no text or watermarks directly in the positive prompt.

05Three-in-one synthesis workflow and node execution

Worked example

Based on docs/comfyui-local.md and src/workflows/qwen_image_edit_2509_3img.api.json, run three-image character synthesis (portrait + costume + pose) locally with Qwen Image Edit 2509.

1. Prepare ComfyUI model files

Place the official Comfy-Org/Qwen-Image_ComfyUI models into the corresponding ComfyUI directories:

Component roleFilenameTarget directoryFile size
Diffusion modelqwen_image_edit_2509_fp8_e4m3fn.safetensorsmodels/diffusion_models or models/unet20.4 GB
Text and vision encoderqwen_2.5_vl_7b_fp8_scaled.safetensorsmodels/text_encoders9.4 GB
VAEqwen_image_vae.safetensorsmodels/vae254 MB
4-step Lightning LoRAQwen-Image-Edit-2509-Lightning-4steps-V1.0-bf16.safetensorsmodels/loras850 MB

2. Start services and run three-image synthesis

Start local ComfyUI on port 8188 in the first terminal, then start the Web Studio in the second terminal:

bash
python main.py --listen 127.0.0.1 --port 8188
cd /path/to/ai-pose-gallery-zh
COMFYUI_URL=http://127.0.0.1:8188 corepack pnpm dev

Open http://localhost:5173/studio and follow these steps:

  1. Select 1 reference image each from /portraits, /costumes, and /poses (for example, default portrait f71f980dde3, costume SPR-0001, and pose full_single_P001_front).

  2. Select local ComfyUI in the interface settings and keep the default /comfy address (proxied same-origin by Vite to COMFYUI_URL).

  3. Load the built-in qwen_image_edit_2509_3img.api.json workflow and confirm the pipeline is UNETLoader → LoraLoaderModelOnly → ModelSamplingAuraFlow(shift=3) → CFGNorm → KSampler (4 steps, cfg=1, euler/simple).

  4. Submit the generation request; the studio opens a WebSocket connection with the same clientId, uploads images to /upload/image, submits the workflow to POST /prompt, and stores prompt_id in browser IndexedDB.

3. Deploy to Cloudflare Workers (optional)

Build the static bundle and deploy it with /api/proxy to Cloudflare Workers:

bash
bash scripts/build.sh
npx wrangler versions upload
npx wrangler deploy

scripts/build.sh runs pnpm build and copies _headers, robots.txt, sitemap.xml, og-cover.jpg, data, thumbs, and img into dist/.

06Asset licenses, remote loading, and task tracking boundaries

Limits and precautions

LimitTechnical boundary and action
Upstream asset licenses differGia poses, realistic/anime costumes, and portraits (CC0 1.0) belong to @giaaibusi; CharaDB 440 tags are CC0, while its images are reference-only, non-redistributable, and barred from real-person or minor use; Shisei 57 outfits are CC0 1.0 AI-generated creative references and do not serve as historical costume reconstructions
NSFW content is hidden by defaultFull-body sexy poses (399), couple poses (275), and lingerie/sexy outfits (339) include 18+ adult references; Safe Mode (SFW) is enabled by default and must not be unlocked by minors
Remote outfits depend on upstream and security checksGia anime (1,320) and CharaDB (440) images are not stored in the repository; open_reference_image allows only exact catalog HTTPS URLs, blocks redirects (_NoRedirect), and enforces a 20-second timeout, 10 MiB size cap, and 20,000,000-pixel limit
External ID and view lookup errorsfind_item raises ValueError for unknown charadb-, gia-anime-, or shisei- prefixed IDs, while falling back to the first library item for other unknown IDs. select_costume_view raises an error when a non-front view does not exist
Stopping tracking does not cancel the backend queueClicking stop-tracking in the Web Studio clears only the pending record in browser IndexedDB while the ComfyUI backend task continues running; inspect the queue before resubmitting
Remote auth gateway is not native ComfyUIWebSocket subprotocols comfyui and comfyui-auth.<token> are an optional reverse-proxy convention, not a built-in ComfyUI feature; a passing HTTP connection test does not verify WebSocket handshake auth

07Minimum verification and official references

Next actions

  • Start the local studio with pnpm dev and verify Chinese filtering, depth-map toggling, and 1800×1200 collage download across /poses, /costumes, and /portraits.

  • Test CharacterRecipeNode on the ComfyUI canvas to verify use_depth and costume_view (front, diag, side, back) tensor outputs.

  • Use python3 scripts/import_charadb.py, python3 scripts/import_gia_anime.py, or python3 scripts/import_shisei_costumes.py when refreshing external dataset snapshots, after checking pinned revision hashes and upstream licenses.

The source is pinned to 488939139c69acfe078372b39d4bd0c457dc060e. Official references:

References