Genetic Character Studio

Genetic Character Studio is an open-source FastAPI application for iterative AI character image generation. It turns character design into a controllable genetic workflow: define field groups, generate a population, select the best candidate, and let the next round inherit selected traits while mutating the rest.

The project is designed for creators who need stable character exploration without rewriting prompts from scratch every time.

Highlights

• Genetic character evolution: candidate images are treated as a population, and each round inherits from the selected parent.
• Field-level control: gender, hair, outfit, body type, background, style, camera, and custom dimensions can all become genes.
• Retention and mutation rates: each field group can be tuned so important traits stay stable while creative traits keep changing.
• Creator-in-the-loop selection: the user chooses the best result before the next generation begins.
• Yunwu GPT Image integration: the open-source version uses the same gpt-image-2-all style API path as MJJ AI Studio.
• LLM prompt engineering layer: the app can convert structured genes into final image prompts through a configurable chat completion endpoint.
• Web UI included: session management, generation history, field library editing, prompt template editing, and API testing.
• Open-source safe defaults: API keys are read from environment variables and are never stored in config.json.

Why It Is Different

Most image generation tools use a one-shot prompt loop: write a prompt, generate, rewrite, generate again. This project uses a genetic selection algorithm instead.

The workflow is:

1. Define a character gene library.
2. Generate several variants in one round.
3. Select the candidate closest to the creator's intention.
4. Keep anchor genes stable, such as gender or background.
5. Mutate selected non-anchor genes based on configurable probabilities.
6. Generate the next population from the selected candidate.

This makes visual exploration feel closer to breeding and selection than random prompt guessing. It is especially useful for character libraries, short-video personas, virtual influencers, game NPC concepts, advertising models, and repeatable style experiments.

Keywords

AIGC, AI image generation, GPT Image, GPT Image 2, Yunwu API, character generation, genetic algorithm, genetic prompt engineering, evolutionary design, creator-in-the-loop, human-in-the-loop, prompt workflow, character design, virtual character, digital human, AI model generation, visual identity, persona design, FastAPI, Python, AI workflow, content production automation, short video character, ecommerce model, game character concept, iterative image generation

Architecture

flowchart TD
  A["Field Groups / Character Genes"] --> B["Generate Population"]
  B --> C["LLM Prompt Builder"]
  C --> D["Yunwu GPT Image API"]
  D --> E["Candidate Images"]
  E --> F["Creator Selection"]
  F --> G["Inheritance + Mutation"]
  G --> B
  E --> H["Session Assets + History"]

Loading

Requirements

• Python 3.10+
• A Yunwu-compatible image API key
• Optional: a Yunwu-compatible chat completion API key for LLM prompt polishing

Quick Start

cd E:\xinde\ycsf
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

Set your keys in the shell or a process manager:

$env:GENETIC_CHARACTER_STUDIO_IMAGE_API_KEY="your-yunwu-image-key"
$env:GENETIC_CHARACTER_STUDIO_LLM_API_KEY="your-yunwu-chat-key"
uvicorn app:app --host 127.0.0.1 --port 8099

Open:

http://127.0.0.1:8099/static/index.html

Environment Variables

Variable	Required	Description
GENETIC_CHARACTER_STUDIO_IMAGE_API_KEY	Yes	Yunwu image generation API key. Fallbacks: YUNWU_IMAGE_API_KEY, YUNWU_API_KEY.
GENETIC_CHARACTER_STUDIO_LLM_API_KEY	Optional	Chat completion key for prompt polishing. If empty, the app uses an offline prompt fallback.
GENETIC_CHARACTER_STUDIO_BASE_PATH	Optional	URL prefix when deploying behind a reverse proxy.
GENETIC_CHARACTER_STUDIO_SAVE_ROOT	Optional	Legacy /generate export directory. Defaults to data/legacy_exports.

API Providers

The open-source image provider is Yunwu GPT Image:

POST https://yunwu.ai/v1/images/generations
model: gpt-image-2-all

The previous local reverse txt2img service is intentionally removed from the open-source version. This keeps the project easier to run, easier to audit, and safer to publish.

Main Endpoints

Endpoint	Method	Purpose
/health	GET	Service health and runtime paths
/api/config	GET/PUT	Read and update public configuration
/api/llm/test	POST	Test the chat completion layer
/api/image/test	POST	Test Yunwu GPT Image generation
/api/sessions	GET/POST	List or create generation sessions
/api/sessions/{id}/generate	POST	Generate the next population
/api/sessions/{id}/choose	POST	Select a candidate as the parent

Repository Hygiene

The repository intentionally excludes runtime and private artifacts:

• data/
• output/
• generated images
• session JSON
• Playwright cache
• Python caches
• local .env files
• IDE folders

Use .env.example as the public template. Never commit real API keys.

License

MIT License.

Author Note

The genetic character generation workflow and selection logic were designed by the original author of this project. If you build on it, attribution is appreciated.