linyuebanzi-image-gen

Lin Yuebanzi General-purpose Image Generator

Execution layer supporting three image generation APIs, switched via the --provider parameter. The calling skill is responsible for prompt writing, style injection, and business validation; this skill only handles "receive prompt → call API → return result".

When to trigger this skill

This skill is infrastructure called by other skills, not triggered directly by users. When Claude is executing some image generation-related skill (such as linyuebanzi-cover-hero、linyuebanzi-inline-diagram), it calls this skill's script via bash.

Image generation API switching

Select the image generation platform automatically via the --provider parameter or environment variable:

# 方式 1: 自动检测 —— 只设一个环境变量就行
export APIMART_API_KEY=sk-xxx
python linyuebanzi-image-gen/scripts/generate.py \
  --mode generation --prompt "..." --output-dir ./out
# 自动检测到 APIMART_API_KEY，使用 apimart

Method 2: Explicit specification — when both are set, use this to override

python linyuebanzi-image-gen/scripts/generate.py
--provider apimart --mode generation --prompt "..." --output-dir ./out

| Provider | `--provider` | 环境变量 | 模型 |
|---|---|---|---|
| MuleRun | `mulerun`（默认） | `MULERUN_API_KEY` | Nano Banana 2 |
| APImart | `apimart` | `APIMART_API_KEY` | GPT Image 2 |
| Atlas Cloud | `atlascloud` | `ATLASCLOUD_API_KEY` | GPT Image 2 |

**自动检测逻辑**（不传 `--provider` 时）:
1. 只设了 `APIMART_API_KEY` → 自动用 apimart
2. 只设了 `ATLASCLOUD_API_KEY` → 自动用 atlascloud
3. 只设了 `MULERUN_API_KEY` → 用 mulerun
4. 多个都设了 → 默认 mulerun（向后兼容），想用其他需显式传 `--provider apimart` 或 `--provider atlascloud`

## 两种模式

### generation — 纯文本生图

从纯文字 prompt 生成图片,不依赖参考图。适合:概念图、流程图、信息图等。

```bash
# 单张
python linyuebanzi-image-gen/scripts/generate.py \
  --mode generation \
  --prompt "A notebook-style diagram showing..." \
  --name-tag diagram-001 \
  --output-dir ./out

# 单张(从文件读 prompt)
python linyuebanzi-image-gen/scripts/generate.py \
  --mode generation \
  --prompt-file ./prompt.txt \
  --name-tag diagram-001 \
  --output-dir ./out

edit — image editing with reference images

Generate a new image based on reference images, suitable for scenarios requiring character consistency.

# 单张
python linyuebanzi-image-gen/scripts/generate.py \
  --mode edit \
  --prompt "A portrait of..." \
  --images "https://r2.cloudnative101.net/portrait.png" \
  --name-tag cover-hero \
  --output-dir ./out

Batch mode

Submit in batch via manifest JSON, supporting serial and parallel.

# 串行
python linyuebanzi-image-gen/scripts/generate.py \
  --manifest ./batch.json \
  --output-dir ./out

# 并行
python linyuebanzi-image-gen/scripts/generate.py \
  --manifest ./batch.json \
  --output-dir ./out \
  --parallel

Manifest JSON format

{
  "mode": "generation",
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "items": [
    {
      "id": "diagram-001",
      "prompt": "完整提示词(调用方已注入风格前缀)"
    },
    {
      "id": "cover-001",
      "prompt": "完整提示词",
      "images": ["https://example.com/ref.png"]
    }
  ]
}

• mode: generation or edit(default generation)
• aspect_ratio / resolution: global default, can be omitted
• items[].id: required, used for output file naming
• items[].prompt: required, complete prompt (the caller has already done all concatenation)
• items[].images: optional, edit mode requires passing a reference image URL

CLI parameters

Parameter	Single	Batch	Required	Description
--provider	Y	Y	No	mulerun(default) / apimart / atlascloud
--mode	Y	N (in manifest)	Required for single	generation or edit
--prompt	Y (or --prompt-file)	N	No	Inline prompt
--prompt-file	Y (or --prompt)	N	No	Prompt file path
--manifest	N	Y	No	manifest JSON path
--images	Y (edit mode)	N (in items)	Required for edit mode	Comma-separated reference image URLs
--name-tag	Y	N	No	Output filename prefix (default image)
--output-dir	Y	Y	No	Output directory (default ./output)
--aspect-ratio	Y	Y (can be overridden by manifest)	No	Default 16:9
--resolution	Y	Y (can be overridden by manifest)	No	Default 2K
--parallel	N	Y	No	Enable parallel execution
--blocklist	Y	Y	No	Denylist file path (one word per line, stops when a word is matched)

Output structure

Single:

{output-dir}/
├── {name-tag}-{timestamp}.png   # 生成图片
├── {name-tag}-{timestamp}.txt   # 使用的 prompt
└── {name-tag}-{timestamp}.json  # 元数据

Batch:

{output-dir}/
├── {id}.png            # 每项图片
├── {id}.txt            # 每项 prompt
├── {id}.json           # 每项元数据
└── _run_metadata.json  # 整体运行信息

Environment variables

Set the corresponding API Key according to --provider :

• MULERUN_API_KEY: --provider mulerun : required when , MuleRun API's Bearer token
• APIMART_API_KEY: --provider apimart : required when , APImart API's Bearer token
• ATLASCLOUD_API_KEY: --provider atlascloud : required when , Atlas Cloud API's Bearer token

Caller skill integration guide

How new skills use it

1. Define the prompt generation workflow in your SKILL.md
2. After generating the prompt, call this skill via bash:

# 单张（默认 mulerun）
python /path/to/linyuebanzi-image-gen/scripts/generate.py \
  --mode generation \
  --prompt-file ./my-prompt.txt \
  --name-tag my-image \
  --output-dir ./my-output

# 单张（指定 apimart）
python /path/to/linyuebanzi-image-gen/scripts/generate.py \
  --provider apimart \
  --mode generation \
  --prompt-file ./my-prompt.txt \
  --name-tag my-image \
  --output-dir ./my-output

# 单张（指定 atlascloud）
python /path/to/linyuebanzi-image-gen/scripts/generate.py \
  --provider atlascloud \
  --mode generation \
  --prompt-file ./my-prompt.txt \
  --name-tag my-image \
  --output-dir ./my-output

# 批量:先写 manifest JSON,再调用
python /path/to/linyuebanzi-image-gen/scripts/generate.py \
  --manifest ./my-manifest.json \
  --output-dir ./my-output \
  --parallel

1. Script exit code: 0 for success, 1 for failure
2. Read the .txt file in the output directory to get the saved prompt, making it easy to rerun

What the caller is responsible for

• Prompt writing and concatenation (including style prefix injection)
• Business validation (e.g., banning specific words)
• Reference image URL management
• Post-processing (e.g., generating a manifest.md list of illustration positions)

Troubleshooting

Problem	Cause	Solution
API KEY not found	Environment variable not set	mulerun: export MULERUN_API_KEY=sk-xxx，apimart: export APIMART_API_KEY=sk-xxx，atlascloud: export ATLASCLOUD_API_KEY=sk-xxx
HTTP 403	Blocked by Cloudflare WAF	The script already has a built-in browser UA; check the network
Polling timeout	API service is busy	Wait and retry, or check the API status
edit mode did not pass --images	Missing reference image	edit mode must pass reference image URLs via --images