mage-images-gen

name	mage-images-gen
description	AI image generation with OpenAI, Google, DashScope, and Seedream APIs. Supports text-to-image, reference images, aspect ratios, provider selection, and reusable preferences. Sequential by default; parallel generation available on request. Use when user asks to generate, create, draw, render, or iterate on images.

Image Generation (AI SDK)

Official API-based image generation. Supports OpenAI, Google, DashScope (阿里通义万象), and Seedream (火山方舟).

Script Directory

Agent Execution:

1. SKILL_DIR = this SKILL.md file's directory
2. Script path = ${SKILL_DIR}/scripts/main.ts

Preferences (EXTEND.md)

Use Bash to check EXTEND.md existence (priority order):

# Check project-level first
test -f .mage-skills/mage-images-gen/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.mage-skills/mage-images-gen/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────┬───────────────────┐ │ Path │ Location │ ├──────────────────────────────────────────────────┼───────────────────┤ │ .mage-skills/mage-images-gen/EXTEND.md │ Project directory │ ├──────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.mage-skills/mage-images-gen/EXTEND.md │ User home │ └──────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ Result │ Action │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Found │ Read, parse, apply settings │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Not found │ Use defaults │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md Supports: Default provider | Default quality | Default aspect ratio | Default image size | Default models

Schema: references/config/preferences-schema.md

Reference Loading Guide

Read references/config/preferences-schema.md only when:

• EXTEND.md needs to be created or edited
• the user asks to persist defaults for provider, quality, aspect ratio, image size, or models
• command behavior should follow saved preferences

Preference Update Workflow

If the user asks to save or change defaults:

1. ask whether the preference should apply to the current project or all projects
2. create or update:
   • project: .mage-skills/mage-images-gen/EXTEND.md
   • user: ~/.mage-skills/mage-images-gen/EXTEND.md
3. write only the fields the user actually wants to set
4. keep unspecified fields as null unless the user wants explicit defaults

Usage

# Basic
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image cat.png

# With aspect ratio
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9

# High quality
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k

# From prompt files
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png

# With reference images (Google multimodal or OpenAI edits)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

# With reference images (explicit provider/model)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png

# Specific provider
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai

# DashScope (阿里通义万象)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope

# Seedream (火山方舟)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider seedream

Options

Option	Description
--prompt <text>, -p	Prompt text
--promptfiles <files...>	Read prompt from files (concatenated)
--image <path>	Output image path (required)
--provider google|openai|dashscope|seedream	Force provider (default: auto-detect)
--model <id>, -m	Model ID (--ref with OpenAI requires GPT Image model, e.g. gpt-image-1.5)
--ar <ratio>	Aspect ratio (e.g., 16:9, 1:1, 4:3)
--size <WxH>	Size (e.g., 1024x1024)
--quality normal|2k	Quality preset (default: 2k)
--imageSize 1K|2K|4K	Image size for Google (default: from quality)
--ref <files...>	Reference images. Supported by Google multimodal, OpenAI edits (GPT Image models), and Seedream image inputs. If provider omitted: Google first, then OpenAI, then Seedream
--n <count>	Number of images
--json	JSON output

Environment Variables

Variable	Description
OPENAI_API_KEY	OpenAI API key
GOOGLE_API_KEY	Google API key
DASHSCOPE_API_KEY	DashScope API key (阿里云)
SEEDREAM_API_KEY	Seedream API key
ARK_API_KEY	Seedream API key alias for Volcengine Ark
OPENAI_IMAGE_MODEL	OpenAI model override
GOOGLE_IMAGE_MODEL	Google model override
DASHSCOPE_IMAGE_MODEL	DashScope model override (default: z-image-turbo)
DASHSCOPE_TEXT_IMAGE_MODEL	DashScope text-heavy fallback model override (default behavior prefers qwen-image-2.0-pro for text-heavy prompts)
DASHSCOPE_IMAGE_MODEL_FALLBACK	Optional; on API failure retry once with another DashScope model
SEEDREAM_IMAGE_MODEL	Seedream model override (default: doubao-seedream-5-0-260128)
ARK_IMAGE_MODEL	Seedream model alias
OPENAI_BASE_URL	Custom OpenAI endpoint
GOOGLE_BASE_URL	Custom Google endpoint
DASHSCOPE_BASE_URL	Custom DashScope endpoint
SEEDREAM_BASE_URL	Custom Seedream endpoint
ARK_BASE_URL	Seedream endpoint alias

Load Priority: CLI args > EXTEND.md > env vars > project .mage-skills/.env（从 cwd 向上查找）> ~/.mage-skills/.env（见 .mage-skills/README.md）

Provider Selection

1. --ref provided + no --provider → auto-select Google first, then OpenAI, then Seedream
2. --provider specified → use it (if --ref, must be google or openai or seedream)
3. Only one API key available → use that provider
4. Multiple available → default to DashScope, then Seedream, then Google, then OpenAI

Model behavior notes:

• DashScope keeps z-image-turbo as the normal default for general image generation
• When the prompt clearly looks text-heavy and no explicit DashScope model override is set, mage-images-gen prefers qwen-image-2.0-pro
• Seedream keeps doubao-seedream-5-0-260128 as the default unless overridden

Quality Presets

Preset	Google imageSize	OpenAI Size	Use Case
normal	1K	1024px	Quick previews
2k (default)	2K	2048px	Covers, illustrations, infographics

Google imageSize: Can be overridden with --imageSize 1K|2K|4K

Aspect Ratios

Supported: 1:1, 16:9, 9:16, 4:3, 3:4, 2.35:1

• Google multimodal: uses imageConfig.aspectRatio
• Google Imagen: uses aspectRatio parameter
• OpenAI: maps to closest supported size

Generation Mode

Default: Sequential generation (one image at a time). This ensures stable output and easier debugging.

Parallel Generation: Only use when user explicitly requests parallel/concurrent generation.

Mode	When to Use
Sequential (default)	Normal usage, single images, small batches
Parallel	User explicitly requests, large batches (10+)

Parallel Settings (when requested):

Setting	Value
Recommended concurrency	4 subagents
Max concurrency	8 subagents
Use case	Large batch generation when user requests parallel

Agent Implementation (parallel mode only):

# Launch multiple generations in parallel using Task tool
# Each Task runs as background subagent with run_in_background=true
# Collect results via TaskOutput when all complete

Seedream Best Practices

When using --provider seedream:

1. keep the main prompt concise and concrete; prefer staying within roughly 300 Chinese characters for the core instruction
2. prefer 2K for normal infographic, cover, and social-image use cases; use explicit pixel sizes only when the target aspect ratio is important
3. use reference images sparingly even though Seedream supports multiple inputs; prefer 1 strong reference image for consistency unless the user explicitly wants multi-image fusion
4. when using references, describe the subject, style, and layout goal explicitly instead of relying on the model to infer everything from the images
5. for multi-page carousel workflows, prefer generating pages sequentially instead of relying on provider-side group-image generation by default
6. if provider-side prompt optimization is available, prefer the higher-quality standard mode over speed-first settings for text-heavy or layout-sensitive images
7. if Chinese text fidelity is weak, shorten the copy, enlarge the text blocks, and simplify the layout before switching providers

Operational notes:

• Seedream supports URL and Base64 image inputs for references
• Seedream supports preset sizes such as 2K and explicit pixel dimensions
• keep the total number of input reference images low for predictable outputs unless the task specifically needs image fusion
• for Xiaohongshu-style assets, dense knowledge-card pages should still avoid micro-text even when Seedream is selected

Text Fidelity Best Practices

Use these rules whenever the requested image must contain readable titles, labels, captions, command lines, or technical annotations:

1. treat text rendering as a primary requirement, not a decorative afterthought
2. provide an exact text whitelist and explicitly forbid any extra words, random letters, pseudo-text, fake UI copy, or decorative micro-text
3. define the layout before the styling: title area, card labels, code cards, caption strip, and other dedicated text zones
4. keep each label isolated in its own text zone; do not ask the model to pack many unrelated phrases into one crowded block
5. for command lines or long English strings, use wide code-style cards or horizontal bars instead of tiny inline labels
6. for technical diagrams, prefer clean printed sans-serif typography and horizontal text; do not force handwritten lettering unless the visual style truly depends on it
7. ask for generous padding around each text block and high contrast between text and background
8. when text corruption appears, fix prompt structure first: shorten labels, reduce simultaneous text regions, and remove extra annotation layers before switching providers

Provider Notes

• seedream: Best for text-heavy technical diagrams when prompts are concise and layout-first. Structure prompts as subject -> layout -> style -> exact text regions -> negative constraints.
• dashscope: Prefer qwen-image-2.0-pro for text-rich posters or diagram-heavy work when available. If fine text control matters more than model-side creativity, keep prompt optimization conservative and strengthen the negative constraints against blurred or distorted text.
• google / openai: still useful for reference-driven edits, but for prompt-only Chinese technical diagrams, validate text quality carefully before batching many outputs.

Recommended Prompt Pattern

SUBJECT:
- [what image this is]

SCENE AND LAYOUT:
- [aspect ratio, composition, number of cards/nodes, text zones]

STYLE:
- [visual style, line treatment, palette, typography choice]

EXACT TEXT REGIONS:
- title: `[exact text]`
- card 1: `[exact text]`
- card 2: `[exact text]`

NEGATIVE CONSTRAINTS:
- no extra text, no random letters, no pseudo-text, no tiny annotations

Error Handling

• Missing API key → error with setup instructions
• Generation failure → auto-retry once
• Invalid aspect ratio → warning, proceed with default
• Reference images with unsupported provider/model → error with fix hint (switch to Google multimodal, OpenAI GPT Image edits, or Seedream)

Extension Support

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.