name: "universal-imagegen" description: "Bring the Codex imagegen workflow, prompt engineering, use-case taxonomy, edit invariants, and prompt library to any general-purpose agent, then generate or edit raster images through a configurable Images API. Supports OpenAI-compatible services and Qwen-Image deployments exposed through compatible gateways."

Universal Image Generation Skill

Adapted on 2026-09-24 from the OpenAI Codex imagegen skill. The unmodified source snapshot is preserved under upstream/imagegen/.

Runtime contract

This skill does not assume a host-specific built-in image tool.

• Preferred execution: the npm/pnpm-installed imagegen-agent CLI.
• If the global command is unavailable and package execution is allowed, use npx -y universal-imagegen-agent or pnpm dlx universal-imagegen-agent as the command prefix.
• Reuse the bundled Codex-derived prompt library and workflow regardless of which compatible image model serves the request.
• Machine-readable execution: always add --json.
• Safe validation: run with --dry-run before a costly or destructive retry.
• Credentials: read from environment variables only. Never ask a user to paste a complete API key into chat and never pass a key on the command line.
• API portability: model, base URL, headers, and API-key environment variable are configurable. Do not assume one provider's model catalog.
• Open models: Qwen-Image and similar deployments can be used when exposed through the bundled OpenAI-compatible interface. For native Diffusers, ComfyUI, SGLang, or another protocol, add a provider adapter rather than changing the agent-facing workflow.
• Output safety: do not overwrite existing files unless the user explicitly authorizes replacement and --force is supplied.

Installation

Install the CLI and this skill together:

npm install --global universal-imagegen-agent
imagegen-agent install-skill

Or install only the skill without keeping a global package:

npx universal-imagegen-agent install-skill

Restart or reload the host agent after installation. The installer defaults to $CODEX_HOME/skills/universal-imagegen, or ~/.codex/skills/universal-imagegen when CODEX_HOME is unset. Use --target for another compatible agent's skill directory.

Intent decision

Classify the request independently along two axes:

1. Intent:
   • generate: create a new image; reference images guide style, composition, mood, or subject.
   • edit: preserve an existing image while changing specified parts.
2. Execution:
   • one asset;
   • multiple variants of one prompt (--n);
   • many distinct jobs (batch with one JSONL record per asset).

Assume generate unless the user explicitly asks to modify an existing image. For edits, label each input image by index and role in the prompt.

Workflow

1. Determine whether the output is a preview or a project deliverable.
2. Collect the primary request, exact in-image text, constraints, avoid list, input images, and required output path.
3. Check configuration with imagegen-agent config --json.
4. Structure the prompt using the schema below without inventing unrelated objects, brands, slogans, characters, palettes, or narrative details.
5. For an edit, state invariants as change only X; keep Y unchanged.
6. Run the intended request with --dry-run --json.
7. Execute the real request only when configuration and paths are correct.
8. Inspect every output for subject, composition, exact text, edit invariants, unwanted artifacts, and alpha-channel requirements.
9. Iterate with one targeted change at a time.
10. Report output paths, effective model/provider, and final prompt.

Prompt schema

Use only the useful lines:

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's request>
Input images: <Image 1: role; Image 2: role>
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo, illustration, 3D, etc.>
Composition/framing: <viewpoint, crop, placement>
Lighting/mood: <lighting and mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep and must avoid>
Avoid: <negative constraints>

If the user prompt is already specific, normalize it without adding creative requirements. If it is generic, add only details that materially improve composition, intended use, or production quality.

Taxonomy

Generate:

• photorealistic-natural
• product-mockup
• ui-mockup
• infographic-diagram
• scientific-educational
• ads-marketing
• productivity-visual
• logo-brand
• illustration-story
• stylized-concept
• historical-scene

Edit:

• text-localization
• identity-preserve
• precise-object-edit
• lighting-weather
• background-extraction
• style-transfer
• compositing
• sketch-to-render

CLI recipes

Configuration:

imagegen-agent config --json

Generate:

imagegen-agent generate "A minimal ceramic mug product photo" \
  --use-case product-mockup \
  --composition "wide composition with usable negative space" \
  --constraints "no logos; no text; no watermark" \
  --out output/imagegen/mug.png \
  --json

Edit:

imagegen-agent edit \
  --image input.png \
  --prompt "Replace only the background with a warm sunset" \
  --constraints "keep the product, its edges, framing, and labels unchanged" \
  --out output/imagegen/sunset.png \
  --json

Batch:

imagegen-agent batch jobs.jsonl \
  --out-dir output/imagegen/batch \
  --concurrency 4 \
  --json

Transparent output

Request an actually transparent background and use PNG or WebP. API capability varies by provider and model. If native transparency is unsupported, explain the limitation and ask before switching models or using chroma-key extraction. Never silently change the selected model.

Text and edits

• Put exact text in quotes and request verbatim rendering with no extra text.
• Spell difficult words character by character when accuracy is critical.
• Preserve edit invariants on every iteration.
• A mask guides generation but does not guarantee pixel-perfect boundaries.
• For multi-image edits, image order is meaningful.

Boundaries

Use direct SVG, HTML/CSS, canvas, or repository-native editing instead when the task is deterministic vector work, a small change to an editable source asset, or an extension of an established icon/logo system.

References

• references/prompting.md: runtime-neutral prompting guidance.
• references/integration.md: configuration and agent integration.
• references/sample-jobs.jsonl: batch examples.
• upstream/imagegen/: complete original skill snapshot.

Universal ImageGen Agent

开始验证： 完整 generate → edit 案例 · 更新记录 · English · 作者展示页：Agent 与 AI

v0.1.1 修复了 Node.js 将 n=0 静默变成 n=1 的行为，并为 Node.js/Python CLI 加入共享的数量边界用例。未指定数量时仍默认生成一张。

这是一个从 OpenAI Codex imagegen skill 改造而来的、面向通用智能体的独立项目。它把 Codex 生图能力中已经沉淀下来的任务决策流程、提示词工程、用例分类、编辑不变量和提示词范例库抽离出来，使任意具备 shell 或 Python 调用能力的智能体，都能直接复用这套成熟方法来生成和编辑图片，而不必依赖 Codex 专有的内置图片工具。

随着 Qwen-Image、Qwen-Image-2.1 等开放图像模型快速发展，智能体已经拥有越来越多可选择的生图后端。本项目不绑定某个模型：既可以连接 OpenAI Images API，也可以连接实现兼容接口的第三方服务；将 Qwen-Image 部署到本地或推理服务后，还可以通过 OpenAI-compatible 网关或新增适配器，把 Qwen 的开放模型能力与本项目继承自 Codex 的提示词库、工作流和质量约束组合起来，让不同智能体获得更稳定、更专业的生图体验。

当前内置的是 OpenAI-compatible Images API 适配层。Qwen 本地 Diffusers、ComfyUI 或 SGLang 推理后端尚未直接内置，需要通过兼容网关接入或新增 provider adapter。

项目提供：

• 可由任意具备 shell 能力的智能体调用的 imagegen-agent CLI；
• 可通过 npm、pnpm 或 Python 安装；
• 可嵌入其他程序的 Node.js 与 Python 接口；
• 一条命令安装到 Codex 或兼容智能体的 universal-imagegen skill；
• --json 机器可读输出和稳定的退出码；
• 独立 API 密钥、自定义 base_url、模型、请求头和扩展请求参数；
• 生成、编辑、多图输入、遮罩和 JSONL 批处理；
• 非覆盖式输出、dry-run、提示词结构化和敏感配置脱敏；
• 完整保留的上游技能快照，位于 upstream/imagegen/。

当前改造日期为 2026-09-24。新配置默认使用 gpt-image-2.5-sunburst，但模型不是硬编码限制，任何部署都可以通过 环境变量、TOML 或命令行替换。

为什么适合 Qwen-Image 等开放模型

图像模型本身决定画面生成能力，而智能体侧的任务理解、提示词组织、输入图片角色标注、编辑不变量和结果检查同样决定最终质量。这个项目负责后半部分：

• 把用户的自然语言请求转换为结构清晰、面向生产的图片提示词；
• 区分新图生成、参考图生成、局部编辑、多图合成和批量资源等任务；
• 为编辑任务持续锁定人物身份、布局、文字、边缘和背景等不变量；
• 复用 Codex imagegen skill 中的 use-case taxonomy 和提示词范例；
• 用统一 CLI、Python API 和 JSON 结果，让不同智能体共享同一套生图能力；
• 通过可配置 provider，将相同工作流用于 OpenAI 模型、Qwen-Image 部署或其他兼容服务。

因此，接入 Qwen-Image 并不意味着每个智能体都要重新设计提示词系统。只要部署端提供兼容 API，智能体就可以继续使用本项目的 SKILL.md、提示词库和执行协议；如果部署端接口不同，也只需新增 provider adapter，而不需要重写上层智能体工作流。

目录

.
├── SKILL.md                    # 适用于通用智能体的技能说明
├── agents/openai.yaml          # Skill 的 UI 与自动发现元数据
├── bin/                        # npm/pnpm 安装后的 CLI 入口
├── node/                       # Node.js CLI、API 与 skill 安装器
├── node-tests/                 # Node.js 测试
├── src/universal_imagegen/     # CLI、配置、提示词与 API 适配层
├── tests/                      # 不调用真实 API 的单元测试
├── references/                 # 通用提示词与集成说明
├── upstream/imagegen/          # 未修改的原始 skill 快照
├── imagegen.example.toml       # 非敏感配置示例
└── .env.example               # API 环境变量示例

安装

安装本次修复版 v0.1.2

v0.1.2 已发布到 npm，可固定版本安装：

npm install --global universal-imagegen-agent@0.1.2
imagegen-agent --version

本版本修复了数量校验和 npm CLI 入口，并通过 GitHub Actions 可信发布。 需要直接下载安装包、Python wheel 或源码包时，可查看 v0.1.2 Release。

npm

npm install --global universal-imagegen-agent

pnpm

pnpm add --global universal-imagegen-agent

安装后可直接运行：

imagegen-agent --version
imagegen-agent config --json

也可以不进行全局安装：

npx universal-imagegen-agent generate "A ceramic mug" --dry-run --json
pnpm dlx universal-imagegen-agent generate "A ceramic mug" --dry-run --json

如果 npm registry 版本尚未发布或需要测试最新的 main：

npm install --global github:SnowSky1/universal-imagegen-agent
pnpm add --global github:SnowSky1/universal-imagegen-agent

安装相应 skill

全局安装 CLI 后：

imagegen-agent install-skill

不全局安装：

npx universal-imagegen-agent install-skill
pnpm dlx universal-imagegen-agent install-skill

默认安装位置为：

$CODEX_HOME/skills/universal-imagegen

未设置 CODEX_HOME 时使用：

~/.codex/skills/universal-imagegen

可通过 --target 安装到其他智能体的技能目录：

imagegen-agent install-skill --target /path/to/agent/skills

已有同名 skill 时默认不覆盖；确认替换时添加 --force。安装完成后重启或重新加载智能体，使其发现 $universal-imagegen。

Python 开发版

需要 Python 3.11 或更高版本：

uv sync --extra dev

配置 API

复制环境变量示例：

Copy-Item .env.example .env

在本机 .env 中填写密钥：

IMAGEGEN_API_KEY=your-local-secret
IMAGEGEN_BASE_URL=https://api.openai.com/v1
IMAGEGEN_MODEL=gpt-image-2.5-sunburst

.env 已被 Git 忽略。请勿把真实密钥提交到仓库。

如需项目级非敏感配置：

Copy-Item imagegen.example.toml .imagegen.toml

配置优先级从高到低为：

1. 命令行中的模型、URL、输出等非敏感参数；
2. IMAGEGEN_* 环境变量及 .env；
3. --config、IMAGEGEN_CONFIG 或当前目录 .imagegen.toml；
4. 项目默认值。

为了避免 shell 历史和进程列表泄密，CLI 故意不提供 --api-key 参数。 TOML 中只写 api_key_env，密钥本身放在环境变量。

自定义兼容服务

只要服务实现兼容的 Images API，即可配置：

IMAGEGEN_API_KEY=provider-secret
IMAGEGEN_BASE_URL=https://example.com/v1
IMAGEGEN_MODEL=provider-image-model
IMAGEGEN_HEADERS_JSON={"X-Project":"demo"}

自定义服务会收到提示词、输入图像及请求头，请只使用可信端点。

常用命令

检查配置，输出会自动隐藏密钥：

imagegen-agent config
imagegen-agent config --json

仅验证请求，不联网：

imagegen-agent generate "一只放在石桌上的陶瓷杯" `
  --use-case product-mockup `
  --style "clean product photography" `
  --constraints "no logo; no watermark" `
  --dry-run --json

生成：

imagegen-agent generate "A quiet alpine cabin at dawn" `
  --size 1536x1024 `
  --quality high `
  --out output/imagegen/alpine-cabin.png

编辑：

imagegen-agent edit `
  --image input.png `
  --prompt "Change only the background to a warm sunset" `
  --constraints "keep the subject, framing, and edges unchanged" `
  --out output/imagegen/sunset-edit.png

批处理：

{"prompt":"A gray wolf in snow","out":"wolf.png","size":"1024x1024"}
{"prompt":"A matte ceramic mug","out":"mug.png","quality":"high"}

imagegen-agent batch jobs.jsonl `
  --out-dir output/imagegen/batch `
  --concurrency 4 --json

智能体调用约定

智能体应优先执行 dry-run，确认提示词、模型与输出路径后再进行真实请求。 真实执行时建议使用 --json，其标准输出只包含结果对象，进度和错误写入 标准错误。成功退出码为 0，配置或输入错误为 2，API/网络/写入失败为 1。

完整的行为约束、决策树和提示词分类见 SKILL.md。

Node.js 接口

import {
  ImageGenClient,
  loadSettings,
} from "universal-imagegen-agent";

const settings = await loadSettings();
const client = new ImageGenClient(settings);
const result = await client.generate({
  prompt: "A minimal ceramic mug product photo",
  out: "output/imagegen/mug.png",
});
console.log(result.outputs);

Python 接口

from universal_imagegen import ImageGenClient, GenerateRequest, load_settings

settings = load_settings()
client = ImageGenClient(settings)
result = client.generate(
    GenerateRequest(
        prompt="A minimal ceramic mug product photo",
        out="output/imagegen/mug.png",
    )
)
print(result.outputs)

验证和使用反馈

从源码目录运行 node examples/verify-workflow.mjs，可以实际走通本地 HTTP 请求、PNG 文件保存和 multipart 编辑上传，并得到 verification.json。 该案例返回明确标注的单像素测试图片，用于验证集成链路；真实模型的运行说明和 验证边界见 案例文档。

如已接入自己的服务，欢迎通过 GitHub Issues 中的 Provider compatibility feedback 表单提供成功记录或错误复现。 请包含版本、运行环境、provider/model 名称和脱敏命令，不要提交密钥。

许可证和来源

项目使用 Apache License 2.0。原始 skill 未经修改保存在 upstream/imagegen/，改造说明见 NOTICE。根目录代码与文档是为通用 智能体重新组织的派生实现。

如果这个项目帮助你把 Codex 的提示词能力带到了更多智能体或开放模型中，欢迎给仓库点一个 Star，并分享你接入的模型或 provider adapter。