happy-image-gen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

happy-image-gen

Generates still images across 8 providers through one CLI:

bun scripts/main.ts ...

. The same CLI handles text-to-image and image-to-image (reference-driven) edits.

通过一个CLI工具

bun scripts/main.ts ...

实现8个提供商的静态图像生成。该CLI同时支持文本转图像和以参考图像为驱动的图像编辑功能。

Quick usage

快速使用

bash

bun scripts/main.ts --prompt "A calico cat on green grass, cinematic light" --ar 16:9 --image ./out.png

bash

bun scripts/main.ts --prompt "A calico cat on green grass, cinematic light" --ar 16:9 --image ./out.png

When to invoke this skill

何时调用此技能

Invoke this skill whenever the user:

Asks to generate, create, draw, render, illustrate, or synthesize an image from text.
Asks to restyle or transform an existing image they provide a path to.
Names any image-generation model (DALL·E, gpt-image, Flux, SDXL, Gemini Image, Imagen, Seedream, Kolors, Wanx, Stable Diffusion) without specifying 即梦/Dreamina/Jimeng.

Route to

happy-dreamina

instead when the user explicitly names 即梦, Jimeng, or the

dreamina

CLI.

当用户出现以下需求时，调用此技能：

请求根据文本生成、创建、绘制、渲染、制作插图或合成图像。
请求对提供路径的现有图像进行重新风格化或转换。
提及任何图像生成模型（DALL·E、gpt-image、Flux、SDXL、Gemini Image、Imagen、Seedream、Kolors、Wanx、Stable Diffusion）但未指定即梦/Dreamina/Jimeng。

当用户明确提及即梦、Jimeng或

dreamina

CLI时，请转至

happy-dreamina

处理。

Step 0: Preflight (BLOCKING — run before any generation)

步骤0：前置检查（必须完成——生成前执行）

Run these checks:

Locate EXTEND.md config. Check in order:

./.happy-skills/happy-image-gen/EXTEND.md

(project)

$XDG_CONFIG_HOME/happy-skills/happy-image-gen/EXTEND.md

~/.happy-skills/happy-image-gen/EXTEND.md

(user)

If none exist, run

bun scripts/main.ts --setup

and follow

references/config/first-time-setup.md

to create one. Do not proceed to generation until the user has at least one provider configured.

Verify a provider is usable. Confirm either an env var is set (e.g.,
```
OPENAI_API_KEY
```
) or EXTEND.md references an
```
api_key_env
```
/
```
api_key_source
```
that resolves. If nothing resolves, loop back to setup.
Verify Bun is available. Run
```
command -v bun
```
. If missing, fall back to
```
npx -y bun scripts/main.ts ...
```
.

执行以下检查：

定位EXTEND.md配置文件，按以下顺序查找：
- ```
./.happy-skills/happy-image-gen/EXTEND.md
```
  （项目级）
- ```
$XDG_CONFIG_HOME/happy-skills/happy-image-gen/EXTEND.md
```
- ```
~/.happy-skills/happy-image-gen/EXTEND.md
```
  （用户级）
如果不存在任何配置文件，运行
```
bun scripts/main.ts --setup
```
并按照
```
references/config/first-time-setup.md
```
创建配置文件。在用户完成至少一个提供商的配置前，请勿继续生成操作。
验证提供商可用：确认已设置环境变量（如
```
OPENAI_API_KEY
```
），或EXTEND.md中引用的
```
api_key_env
```
/
```
api_key_source
```
可解析。若无法解析，返回步骤0重新配置。
验证Bun已安装：运行
```
command -v bun
```
。若未安装， fallback 至
```
npx -y bun scripts/main.ts ...
```
。

Step 1: Choose a provider

步骤1：选择提供商

Pick in this order of preference:

```
--provider <id>
```
explicitly passed by the user.
The
```
default_provider
```
in EXTEND.md.
The first provider whose API key is present in the environment. Priority when auto-detecting:
```
openai
```
→
```
google
```
→
```
replicate
```
→
```
stability
```
→
```
fal
```
→
```
ark
```
→
```
bailian
```
→
```
siliconflow
```
.

See

references/providers.md

for each provider's required env vars, default models, and strengths (e.g., prefer

google

for text-in-image,

replicate

for Flux-family photorealism,

ark

for Chinese text fidelity).

按以下优先级选择：

用户明确传入的
```
--provider <id>
```
参数。
EXTEND.md中设置的
```
default_provider
```
。
环境中已配置API密钥的首个提供商。自动检测优先级：
```
openai
```
→
```
google
```
→
```
replicate
```
→
```
stability
```
→
```
fal
```
→
```
ark
```
→
```
bailian
```
→
```
siliconflow
```
。

查看

references/providers.md

获取各提供商所需的环境变量、默认模型及优势（例如，优先选择

google

处理图像中嵌入文本的需求，

replicate

适合Flux系列的照片级写实效果，

ark

适合中文文本保真度）。

Step 2: Fill in parameters

步骤2：填充参数

--prompt
: the user's full request, trimmed. Always double-quote.
--ar
: aspect ratio —
```
1:1
```
/
```
16:9
```
/
```
9:16
```
/
```
3:4
```
/
```
4:3
```
. See
```
references/aspect_ratio_map.md
```
for how each provider interprets this.
--quality
:
```
draft
```
(fastest + cheapest),
```
hd
```
(default), or
```
ultra
```
(4K-class, slower).
--ref <path>
: repeat for multiple reference images. Not every provider supports this — see providers.md.
--model
: override the default model for the chosen provider. Omit unless the user asked for a specific one.
--image <path>
: REQUIRED — output file path. Use a descriptive name (e.g.,
```
./out/hero-landscape.png
```
).

--prompt
：用户的完整请求，已去除首尾空格。务必使用双引号包裹。
--ar
：宽高比——可选值
```
1:1
```
/
```
16:9
```
/
```
9:16
```
/
```
3:4
```
/
```
4:3
```
。查看
```
references/aspect_ratio_map.md
```
了解各提供商对该参数的解析方式。
--quality
：质量等级，可选
```
draft
```
（最快且最便宜）、
```
hd
```
（默认）或
```
ultra
```
（4K级别，速度较慢）。
--ref <path>
：可重复传入多个参考图像路径。并非所有提供商都支持此功能——详见providers.md。
--model
：覆盖所选提供商的默认模型。除非用户明确指定，否则无需填写。
--image <path>
：必填参数——输出文件路径。建议使用描述性名称（例如
```
./out/hero-landscape.png
```
）。

Step 3: Run

步骤3：运行命令

bash

bun scripts/main.ts \
  --prompt "..." \
  --image ./out.png \
  --provider openai \
  --ar 1:1 \
  --quality hd

On success the CLI prints the resolved absolute path and byte count. In

--json

mode it emits:

json

{ "success": true, "provider": "openai", "model": "gpt-image-1", "image": "/abs/path.png", "size_bytes": 1416341, "format": "png" }

Echo the path back to the user.

bash

bun scripts/main.ts \
  --prompt "..." \
  --image ./out.png \
  --provider openai \
  --ar 1:1 \
  --quality hd

运行成功后，CLI会输出解析后的绝对路径和文件字节数。在

--json

模式下，会输出：

json

{ "success": true, "provider": "openai", "model": "gpt-image-1", "image": "/abs/path.png", "size_bytes": 1416341, "format": "png" }

将输出路径反馈给用户。

Step 4: Handle errors

步骤4：错误处理

config: No provider selected ...
— no API key in env and no EXTEND.md. Loop back to Step 0.
[openai] OpenAI images API 401 ...
— key invalid or expired. Ask the user to refresh it.
[openai] ... 400 ... content_policy_violation
— prompt blocked. Show the raw error to the user; do not paraphrase.
Timeouts / network errors — retry once. If still failing, surface the raw message and
```
provider
```
so the user knows what to check.

See

references/error_codes.md

for a per-provider error table.

config: No provider selected ...
：环境中无API密钥且未配置EXTEND.md。返回步骤0重新配置。
[openai] OpenAI images API 401 ...
：密钥无效或过期。请用户更新密钥。
[openai] ... 400 ... content_policy_violation
：提示词违反内容政策。向用户展示原始错误信息，请勿转述。
超时/网络错误：重试一次。若仍失败，展示原始错误信息及对应的
```
provider
```
，以便用户排查问题。

查看

references/error_codes.md

获取各提供商的错误对照表。

References

参考文档

Read on demand:

references/providers.md
— all 8 providers, required env vars, default models, strengths.
references/aspect_ratio_map.md
— how each provider interprets
```
--ar
```
.
references/error_codes.md
— common errors per provider and fixes.

references/config/first-time-setup.md
— step-by-step for

--setup

references/config/extend-schema.md
— EXTEND.md schema reference.

Template for

EXTEND.md

assets/EXTEND.template.md

按需查阅：

references/providers.md
：所有8个提供商的详细信息、所需环境变量、默认模型及优势。
references/aspect_ratio_map.md
：各提供商对
```
--ar
```
参数的解析方式。
references/error_codes.md
：各提供商常见错误及修复方案。

references/config/first-time-setup.md
：

--setup

命令的分步指南。

references/config/extend-schema.md
：EXTEND.md的 schema 参考文档。

EXTEND.md模板文件：

assets/EXTEND.template.md

。