baoyu-image-gen

Name: baoyu-image-gen
Author: jimliu

byjimliu· 68 skills

Installs

31k

Stars

24k

Forks

2.7k

How to install baoyu-image-gen?

jimliu/baoyu-skills/baoyu-image-gen

$npx -y skills add jimliu/baoyu-skills --skill baoyu-image-gen

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/jimliu/baoyu-skills" --skill "jimliu/baoyu-skills/baoyu-image-gen"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/jimliu/baoyu-skills" that are relevant to the current task. Run `npx skills add "https://github.com/jimliu/baoyu-skills"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Image Generation (AI SDK)
2
3	Official API-based image generation. Supports OpenAI GPT Image 2, Azure OpenAI, Google, OpenRouter, DashScope (阿里通义万象), Z.AI GLM-Image, MiniMax, Jimeng (即梦), Seedream (豆包), Replicate and Agnes.
4
5	## User Input Tools
6
7	When this skill prompts the user, follow this tool-selection rule (priority order):
8
9	1. Prefer built-in user-input tools exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
10	2. Fallback: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
11	3. Batching: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
12
13	Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
14
15	## Script Directory
16
17	`{baseDir}` = this SKILL.md's directory. All `scripts/...` paths below are relative to `{baseDir}`. Main script: `{baseDir}/scripts/main.ts`. Batch payload helper: `{baseDir}/scripts/build-batch.ts`. Resolve `${BUN_X}`: prefer `bun`; else `npx -y bun`; else suggest `brew install oven-sh/bun/bun`.
18
19	## Step 0: Load Preferences ⛔ BLOCKING
20
21	This step MUST complete before any image generation — generation is blocked until EXTEND.md exists.
22
23	Check these paths in order; first hit wins:
24
25	\| Path \| Scope \|
26	\|------\|-------\|
27	\| `.baoyu-skills/baoyu-image-gen/EXTEND.md` \| Project \|
28	\| `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-image-gen/EXTEND.md` \| XDG \|
29	\| `$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md` \| User home \|
30
31	- Found → load, parse, apply. If `default_model.[provider]` is null → ask model only.
32	- Not found → run first-time setup (`references/config/first-time-setup.md`) using AskUserQuestion to collect provider + model + quality + save location. Save EXTEND.md, then continue. Do not generate images before this completes.
33
34	Legacy compatibility: if `.baoyu-skills/baoyu-imagine/EXTEND.md` exists and the new path doesn't, the runtime renames it to `baoyu-image-gen`. If both exist, the runtime leaves them alone and uses the new path.
35
36	EXTEND.md keys: default provider, default quality, default aspect ratio, default image size, OpenAI image API dialect, default models, batch worker cap, provider-specific batch limits. Schema: `references/config/preferences-schema.md`.
37
38	## Usage
39
40	Minimum working examples — see `references/usage-examples.md` for the full set including per-provider invocations and batch mode.
41
42	### Identity-preserving reference prompts
43
44	When the user wants a real person/character/object preserved from reference images, do not replace the reference with a long generic description. Prefer short, hard identity-preservation language:
45
46	- "Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject."
47	- "Only change scene, clothing, pose, lighting, rendering style, and composition. Keep the face/proportions/hair/key accessories/overall identity from the references."
48	- If using multiple references, state that they are the same subject and should jointly define identity.
49
50	Pitfall: long descriptions like "young East Asian woman, oval face, clear eyes..." can cause the model to synthesize a new person matching the description instead of preserving the referenced person.
51
52	```bash
53	# Basic
54	${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png
55
56	# With aspect ratio and high quality
57	${BUN_X} {baseDir}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9 --quality 2k
58
59	# Prompt from files
60	${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md content.md --image out.png
61
62	# With reference image
63	${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png
64
65	# Specific provider
66	${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider dashscope --model qwen-image-2.0-pro
67
68	# OpenAI GPT Image 2
69	${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openai --model gpt-image-2
70
71	# Codex CLI (uses logged-in Codex subscription — no OPENAI_API_KEY required; requires `codex` on PATH)
72	${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider codex-cli --ar 16:9
73
74	# Batch mode
75	${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
76
77	# Build a batch file from outline.md + prompts/ (e.g. baoyu-article-illustrator output)
78	${BUN_X} {baseDir}/scripts/build-batch.ts --outline outline.md --prompts prompts --output batch.json --images-dir attachments
79	${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
80	```
81
82	## Reference-Image Identity Preservation
83
84	When the user wants a person/object preserved from reference images:
85
86	- Prefer a small curated set of existing source references (usually 2–4) over many images; large multi-megabyte refs can destabilize streaming providers.
87	- Make the prompt say the references are the same subject and the output must use that identity. Avoid long generic facial-feature descriptions that can cause the model to synthesize a new similar-looking person.
88	- Do not use newly generated outputs as references unless the user explicitly asks; generated refs compound drift.
89	- If results become too polished or influencer-like, reduce stylized refs and add explicit anti-beautification constraints (no face slimming, eye enlargement, heavy makeup, commercial travel shoot, over-smoothing).
90	- If the subject should look younger/older, preserve the face and express age through clothing, posture, scene, and styling; do not ask the model to change facial identity.
91
92	## Options
93
94	\| Option \| Description \|
95	\|--------\|-------------\|
96	\| `--prompt <text>`, `-p` \| Prompt text \|
97	\| `--promptfiles <files...>` \| Read prompt from files (concatenated) \|
98	\| `--image <path>` \| Output image path (required in single-image mode) \|
99	\| `--batchfile <path>` \| JSON batch file for multi-image generation \|
100	\| `--jobs <count>` \| Worker count for batch mode (default: auto, max from config, built-in default 10) \|
101	\| `--provider google\\|openai\\|azure\\|openrouter\\|dashscope\\|zai\\|minimax\\|jimeng\\|seedream\\|replicate\\|codex-cli\\|agnes` \| Force provider (default: auto-detect; `codex-cli` is never auto-selected — must be pinned via CLI or EXTEND.md) \|
102	\| `--model <id>`, `-m` \| Model ID — see provider references for defaults and allowed values \|
103	\| `--ar <ratio>` \| Aspect ratio (`16:9`, `1:1`, `4:3`, …) \|
104	\| `--size <WxH>` \| Explicit size (e.g., `1024x1024`; for `gpt-image-2`, width/height must be multiples of 16, max edge 3840px, ratio no wider than 3:1) \|
105	\| `--quality normal\\|2k` \| Quality preset (default: `2k`) \|
106	\| `--imageSize 1K\\|2K\\|4K` \| Image size for Google/OpenRouter (default: from quality) \|
107	\| `--imageApiDialect openai-native\\|ratio-metadata` \| OpenAI-compatible endpoint dialect — use `ratio-metadata` for gateways that expect aspect-ratio `size` plus `metadata.resolution` \|
108	\| `--ref <files...>` \| Reference images. Supported by Google multimodal, OpenAI GPT Image edits, Azure OpenAI edits (PNG/JPG only), OpenRouter multimodal models, Replicate supported families, MiniMax subject-reference, Seedream 5.0/4.5/4.0, DashScope `wan2.7-image-pro`/`wan2.7-image`. Not supported by Jimeng, Seedream 3.0, SeedEdit 3.0, or any DashScope model outside the `wan2.7-image*` family \|
109	\| `--n <count>` \| Number of images. Replicate requires `--n 1` (single-output save semantics) \|
110	\| `--json` \| JSON output \|
111
112	## Environment Variables
113
114	\| Variable \| Description \|
115	\|----------\|-------------\|
116	\| `OPENAI_API_KEY` \| OpenAI API key \|
117	\| `AZURE_OPENAI_API_KEY` \| Azure OpenAI API key \|
118	\| `OPENROUTER_API_KEY` \| OpenRouter API key \|
119	\| `GOOGLE_API_KEY` \| Google API key \|
120	\| `DASHSCOPE_API_KEY` \| DashScope API key \|
121	\| `ZAI_API_KEY` (alias `BIGMODEL_API_KEY`) \| Z.AI API key \|
122	\| `MINIMAX_API_KEY` \| MiniMax API key \|
123	\| `REPLICATE_API_TOKEN` \| Replicate API token \|
124	\| `JIMENG_ACCESS_KEY_ID`, `JIMENG_SECRET_ACCESS_KEY` \| Jimeng (即梦) Volcengine credentials \|
125	\| `ARK_API_KEY` \| Seedream (豆包) Volcengine ARK API key \|
126	\| `<PROVIDER>_IMAGE_MODEL` \| Per-provider model override (`OPENAI_IMAGE_MODEL`, `GOOGLE_IMAGE_MODEL`, `DASHSCOPE_IMAGE_MODEL`, `ZAI_IMAGE_MODEL`/`BIGMODEL_IMAGE_MODEL`, `MINIMAX_IMAGE_MODEL`, `OPENROUTER_IMAGE_MODEL`, `REPLICATE_IMAGE_MODEL`, `JIMENG_IMAGE_MODEL`, `SEEDREAM_IMAGE_MODEL`, `AGNES_IMAGE_MODEL`) \|
127	\| `AZURE_OPENAI_DEPLOYMENT` (alias `AZURE_OPENAI_IMAGE_MODEL`) \| Azure default deployment \|
128	\| `<PROVIDER>_BASE_URL` \| Per-provider endpoint override \|
129	\| `AZURE_API_VERSION` \| Azure image API version (default `2025-04-01-preview`) \|
130	\| `JIMENG_REGION` \| Jimeng region (default `cn-north-1`) \|
131	\| `OPENAI_IMAGE_API_DIALECT` \| `openai-native` \\| `ratio-metadata` \|
132	\| `OPENROUTER_HTTP_REFERER`, `OPENROUTER_TITLE` \| Optional OpenRouter attribution \|
133	\| `BAOYU_IMAGE_GEN_MAX_WORKERS` \| Override batch worker cap \|
134	\| `BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY` \| Per-provider concurrency (e.g., `BAOYU_IMAGE_GEN_REPLICATE_CONCURRENCY`; for codex-cli use `BAOYU_IMAGE_GEN_CODEX_CLI_CONCURRENCY`) \|
135	\| `BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS` \| Per-provider start-gap \|
136	\| `BAOYU_CODEX_IMAGEGEN_BIN` \| Override the codex-imagegen wrapper path for the `codex-cli` provider (default: bundled `scripts/codex-imagegen/main.ts`; accepts `.ts` or legacy `.sh`/binary) \|
137	\| `BAOYU_CODEX_IMAGEGEN_CACHE_DIR` \| Enable idempotency cache for the `codex-cli` provider (off by default) \|
138	\| `BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS` \| Per-attempt `codex exec` timeout for the `codex-cli` provider (default: 300000 ms) \|
139	\| `BAOYU_CODEX_IMAGEGEN_RETRIES` \| Wrapper-side retry attempts on retryable errors for the `codex-cli` provider (default: 2) \|
140	\| `BAOYU_CODEX_IMAGEGEN_LOG_FILE` \| Append JSONL diagnostic log for the `codex-cli` provider \|
141
142	Load priority: CLI args > EXTEND.md > env vars > `<cwd>/.baoyu-skills/.env` > `~/.baoyu-skills/.env`
143
144	### Codex/ChatGPT OAuth is not an OpenAI API key
145
146	`--provider openai --model gpt-image-2` uses the standard OpenAI Images API (`/v1/images/generations` or `/v1/images/edits`) and requires `OPENAI_API_KEY`. A Codex or ChatGPT desktop login is a different entitlement and is not a drop-in replacement for `OPENAI_API_KEY`; do not paste a Codex OAuth token into `OPENAI_API_KEY` or only set `OPENAI_BASE_URL` to a Codex backend.
147
148	If the user wants to use their Codex subscription / GPT Image 2 entitlement without an OpenAI API key, route through a Codex-native backend instead of this skill's `openai` provider:
149
150	- In Codex runtime: use the native `imagegen` skill/tool.
151	- In non-Codex runtimes with `codex` CLI installed and logged in: use `baoyu-image-gen --provider codex-cli` (preferred — it gives you the same retry / cache / batch flow as every other provider). The provider spawns the bundled `scripts/codex-imagegen/main.ts`; the same code lives upstream at `packages/baoyu-codex-imagegen/src/main.ts` for standalone callers.
152	- In Hermes runtimes with a native `image_generate` tool: use that tool as a fallback, and state whether reference images were passed directly or reconstructed from extracted traits.
153
154	Do not modify the existing `openai` provider to silently consume Codex OAuth. The first-class Codex-CLI path is the dedicated `codex-cli` provider, which has its own auth (Codex login), route (`codex exec`), request shape, and tests. See `references/codex-oauth-vs-openai-api-key.md`.
155
156	## Model Resolution
157
158	Priority (highest → lowest) applies to every provider:
159
160	1. CLI flag `--model <id>`
161	2. EXTEND.md `default_model.[provider]`
162	3. Env var `<PROVIDER>_IMAGE_MODEL`
163	4. Built-in default
164
165	For OpenAI, the built-in default is `gpt-image-2`. `gpt-image-1.5`, `gpt-image-1`, and GPT Image snapshots remain selectable with `--model` or `OPENAI_IMAGE_MODEL`.
166
167	For Azure, `--model` / `default_model.azure` is the Azure deployment name. `AZURE_OPENAI_DEPLOYMENT` is the preferred env var; `AZURE_OPENAI_IMAGE_MODEL` is kept as a backward-compatible alias. If your Azure deployment is named after the underlying model, use `gpt-image-2`; otherwise use the exact custom deployment name.
168
169	EXTEND.md overrides env vars: if EXTEND.md sets `default_model.google: "gemini-3-pro-image"` and the env var sets `GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image`, EXTEND.md wins.
170
171	Display model info before each generation:
172
173	- `Using [provider] / [model]`
174	- `Switch model: --model <id> \| EXTEND.md default_model.[provider] \| env <PROVIDER>_IMAGE_MODEL`
175
176	## OpenAI-Compatible Gateway Dialects
177
178	`provider=openai` means the auth and routing entrypoint is OpenAI-compatible. It does not guarantee the upstream image API uses OpenAI native semantics. When a gateway expects a different wire format, set `default_image_api_dialect` in EXTEND.md, `OPENAI_IMAGE_API_DIALECT`, or `--imageApiDialect`:
179
180	- `openai-native`: pixel `size` (`1536x1024`) and native OpenAI quality fields
181	- `ratio-metadata`: aspect-ratio `size` (`16:9`) plus `metadata.resolution` (`1K\|2K\|4K`) and `metadata.orientation`
182
183	Use `openai-native` for the OpenAI native API or strict clones; try `ratio-metadata` for compatibility gateways in front of Gemini or similar models. Current limitation: `ratio-metadata` applies only to text-to-image; reference-image edits still need `openai-native` or a provider with first-class edit support.
184
185	## Provider-Specific Guides
186
187	Each provider has its own quirks (model families, size rules, ref support, limits). Read these when the user picks that provider or asks for non-default behavior:
188
189	\| Provider \| Reference \|
190	\|----------\|-----------\|
191	\| DashScope (Qwen-Image families, custom sizes) \| `references/providers/dashscope.md` \|
192	\| Z.AI (GLM-Image, cogview-4) \| `references/providers/zai.md` \|
193	\| MiniMax (image-01, subject-reference) \| `references/providers/minimax.md` \|
194	\| OpenRouter (multimodal models, `/chat/completions` flow) \| `references/providers/openrouter.md` \|
195	\| Replicate (nano-banana, Seedream, Wan) \| `references/providers/replicate.md` \|
196	\| Codex CLI (wraps bundled `scripts/codex-imagegen/`; Codex login, no `OPENAI_API_KEY`) \| `references/providers/codex-cli.md` \|
197	\| Agnes (agnes-image-2.1-flash, reference-image support) \| `references/providers/agnes.md` \|
198
199	## Provider Selection
200
201	1. `--ref` provided + no `--provider` → auto-select Google → OpenAI → Azure → OpenRouter → Replicate → Seedream → MiniMax → Agnes (MiniMax's subject reference is more specialized toward character/portrait consistency)
202	2. `--provider` specified → use it (if `--ref`, must be google/openai/azure/openrouter/replicate/seedream/minimax/codex-cli/agnes)
203	3. Only one API key present → use that provider
204	4. Multiple keys → default priority: Google → OpenAI → Azure → OpenRouter → DashScope → Z.AI → MiniMax → Replicate → Jimeng → Seedream → Agnes
205	5. `codex-cli` is never auto-selected — set `default_provider: codex-cli` in EXTEND.md or pass `--provider codex-cli`. It spawns `codex exec` via the bundled `scripts/codex-imagegen/main.ts` TS entrypoint (run with `bun`) and uses the user's Codex subscription (no `OPENAI_API_KEY`). Requires `codex` on `PATH` with an active `codex login`.
206
207	## Quality Presets
208
209	\| Preset \| Google imageSize \| OpenAI size \| OpenRouter size \| Replicate resolution \| Use case \|
210	\|--------\|------------------\|-------------\|-----------------\|----------------------\|----------\|
211	\| `normal` \| 1K \| 1024px target \| 1K \| 1K \| Quick previews \|
212	\| `2k` (default) \| 2K \| 2048px target \| 2K \| 2K \| Covers, illustrations, infographics \|
213
214	Google/OpenRouter `imageSize` can be overridden with `--imageSize 1K\|2K\|4K`.
215
216	For OpenAI native `gpt-image-2`, `normal` maps to `quality=medium` and a low-latency valid size near the requested aspect ratio; `2k` maps to `quality=high` and 2048px-class sizes such as `2048x2048`, `2048x1152`, or `1152x2048`. Use explicit `--size` for valid custom or 4K outputs, e.g. `3840x2160`.
217
218	## Aspect Ratios
219
220	Supported: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2.35:1`.
221
222	- Google multimodal: `imageConfig.aspectRatio`
223	- OpenAI: `gpt-image-2` uses the closest valid custom size for the requested ratio; older GPT Image and DALL·E models use their closest supported fixed size
224	- OpenRouter: `imageGenerationOptions.aspect_ratio`; if only `--size <WxH>` is given, the ratio is inferred
225	- Replicate: behavior is model-specific — `google/nano-banana` uses `aspect_ratio`, `bytedance/seedream-` uses documented Replicate ratios, Wan 2.7 maps `--ar` to a concrete `size`
226	- MiniMax: official `aspect_ratio` values; if `--size <WxH>` is given without `--ar`, sends `width`/`height` for `image-01`
227
228	## Generation Mode
229
230	Default: sequential. Batch parallel: enabled automatically when `--batchfile` contains 2+ pending tasks.
231
232	\| Situation \| Prefer \| Why \|
233	\|-----------\|--------\|-----\|
234	\| One image, or 1-2 simple images \| Sequential \| Lower coordination overhead, easier debugging \|
235	\| Multiple images with saved prompt files \| Batch (`--batchfile`) \| Reuses finalized prompts, applies shared throttling/retries, predictable throughput \|
236	\| Each image still needs its own reasoning / prompt writing / style exploration \| Subagents \| Work is still exploratory, each needs independent analysis \|
237	\| Input is `outline.md` + `prompts/` (e.g. from `baoyu-article-illustrator`) \| Batch — use `{baseDir}/scripts/build-batch.ts` to assemble the payload \| The outline + prompt files already contain everything needed \|
238
239	Rule of thumb: once prompt files are saved and the task is "generate all of these", prefer batch over subagents. Use subagents only when generation is coupled with per-image thinking or divergent creative exploration.
240
241	Parallel behavior:
242
243	- Default worker count is automatic, capped by config, built-in default 10
244	- Provider-specific throttling applies only in batch mode; defaults are tuned for throughput while avoiding RPM bursts
245	- Override with `--jobs <count>`
246	- Each image retries up to 3 attempts
247	- Final output includes success count, failure count, and per-image failure reasons
248
249	## Error Handling
250
251	- Missing API key → error with setup instructions
252	- Generation failure → auto-retry up to 3 attempts per image
253	- Invalid aspect ratio → warning, proceed with default
254	- Reference images with unsupported provider/model → error with fix hint
255
256	### Codex image2 fallback
257
258	If `--provider openai --model gpt-image-2` fails because `OPENAI_API_KEY` is missing but the current runtime has a native image-generation backend or the repo-level `codex-imagegen` wrapper is available, use that path rather than leaving the user waiting. Be explicit about whether the fallback is true reference-image generation or only a text-prompt reconstruction from extracted visual traits. See `references/codex-image2-fallback.md`.
259
260	## References
261
262	\| File \| Content \|
263	\|------\|---------\|
264	\| `references/usage-examples.md` \| Extended CLI examples across providers and batch mode \|
265	\| `references/codex-oauth-vs-openai-api-key.md` \| Why Codex/ChatGPT OAuth image2 entitlement is not usable through baoyu-image-gen's standard OpenAI API-key provider \|
266	\| `references/codex-image2-fallback.md` \| Practical fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available \|
267	\| `references/providers/dashscope.md` \| DashScope families, sizes, limits \|
268	\| `references/providers/zai.md` \| Z.AI GLM-image / cogview-4 \|
269	\|

6 picks

Type

Run `npx skills use "https://github.com/jimliu/baoyu-skills" --skill "jimliu/baoyu-skills/baoyu-image-gen"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/jimliu/baoyu-skills" that are relevant to the current task. Run `npx skills add "https://github.com/jimliu/baoyu-skills"` and select the relevant skills, then follow their instructions.

baoyu-image-gen

How to install baoyu-image-gen?

Related

baoyu-image-gen

How to install baoyu-image-gen?

Related