Cartoon Banner Generator

Produce warm, friendly cartoon banner illustrations that combine:

1. A mascot character (user-supplied reference image, e.g. a cute cartoon penguin / bear / fox / brand mascot).
2. A scene described in natural language (house, river, mountains, office, etc.).
3. A handwritten Chinese (or mixed-language) title rendered directly onto the image.

The default use case is a WeChat 公众号 article header (16:9), but other ratios are supported.

Required environment

• MULEROUTER_API_KEY — MuleRouter API key.
• One of MULEROUTER_BASE_URL (e.g. https://api.mulerouter.ai) or MULEROUTER_SITE (mulerouter or mulerun).
• The mulerouter-skills package available locally (the script invokes its nano-banana-2/edit model). Install from .

If MULEROUTER_API_KEY is missing, ask the user to set it before running.

Quick start

python3 scripts/generate_banner.py \
  --title "活水的本质：管理也可以市场化" \
  --mascot /path/to/mascot.png \
  --scene "a penguin swimming in a river, friends on the left bank cheering, a leader on the right bank reaching out" \
  --output /workspace/output/banner.png

Common flags:

• --title (required) — headline text drawn onto the image (handwritten brush style).
• --mascot (required) — local path to one reference image of the mascot/character.
• --scene (optional) — short natural-language description of what is happening around the mascot.
• --ratio (optional, default 16:9) — one of 1:1 4:3 3:2 16:9 9:16 2:3 21:9.
• --title-position (optional, default top) — top, bottom, left, right, or center.
• --style-preset (optional, default warm-pastel) — see references/STYLE_PRESETS.md.
• --mood (optional) — extra adjectives appended to the prompt, e.g. "cozy and dreamy".
• --accent (optional) — emphasized words from the title to highlight in color, e.g. "产品思维".
• --subtitle (optional) — small line under the main title.
• --resolution (optional, default 2K) — 1K, 2K, or 4K.
• --variants (optional, default 2) — how many images to generate per call.
• --edit-from (optional) — refine an existing banner instead of generating from scratch.
• --mulerouter-skills-dir (optional) — explicit path to the local mulerouter-skills checkout. Defaults to $MULEROUTER_SKILLS_DIR then common locations.

The script prints each saved output path. With --variants > 1, files are suffixed _1, _2, etc.

Workflow

1. Confirm inputs. If title, mascot reference, or ratio is missing, ask the user first. Without a mascot reference image, the output will not match a specific character.
2. Compose the prompt. The script combines style preset + scene + title + accent words automatically. See references/PROMPT_TEMPLATE.md for the master template.
3. Generate. Run the bundled script (see Quick start). It shells out to mulerouter-skills and calls the google/nano-banana-2/edit model.
4. Review and iterate. If title is mis-rendered or the scene is off, run again with a tighter --scene, switch --style-preset, or use --edit-from to refine a previous output. Detailed recipes in references/ITERATION.md.

Reference files

• references/PROMPT_TEMPLATE.md — the master prompt template with placeholder slots.
• references/STYLE_PRESETS.md — built-in style presets (warm-pastel, flat-cartoon, storybook-watercolor, night-cozy, monochrome-line) and how to add new ones.
• references/ITERATION.md — refinement recipes: title repositioning, text replacement, expression changes, background swaps, fallback to local text rendering.

Tips

• Provide a clean, well-cropped mascot reference. A plain background gives the strongest character fidelity.
• Keep titles to ~6–14 Chinese characters. Split longer ones into title + --subtitle.
• Model writes Chinese reasonably well but not perfectly — always inspect output. If wrong characters appear repeatedly, fall back to local Pillow text rendering (see ITERATION.md §"Fallback").
• For brand consistency, wrap the script in a shell alias that pins your default --mascot, --style-preset, and --accent.

Do not

• Do not silently use copyrighted mascots (Tencent QQ penguin, Disney, etc.) unless the user explicitly owns or provides them. The skill is mascot-agnostic by design.
• Do not embed API keys in saved outputs or commit .env files.