gpt-image-gen

GPT Image Gen

Call OpenAI gpt-image-2 model to generate images. A single script covers three modes:

Mode	Trigger condition	Backend
Text-to-image	Only -p	API key → images.generate / Codex OAuth → Responses API
Reference image editing	-p + -i	API key → images.edit / Codex OAuth → Responses API (input_image)
Mask inpainting	-p + -i + -m	Only API key → images.edit; Codex does not support

Auth auto-selection: When a JWT token (eyJ...) is detected, use the Codex Responses API (chatgpt.com/backend-api/codex), otherwise use the standard OpenAI REST API (api.openai.com)。

Trigger conditions (almost any image generation request should load this skill)

As long as the user mentions any of the following keywords/scenarios, load immediately:

• Image generation, generate images, draw images, text-to-image, image generation, AI drawing
• gpt-image, gpt-image-2, GPT drawing, OpenAI image generation, GPT images
• img2img, image-to-image, reference-image-to-image, text+image, upload-image-to-image, image editing
• inpainting, mask inpainting, local redraw, paint-over redraw
• The user sent an image and asked to generate/modify based on it (this is an img2img scenario)

Special note: If the user sends an image attachment and says "generate with this image", "based on this image", "change this image into", etc., this is an img2img scenario — this skill must be loaded, because the built-in image_generate does not support image input.

Dependencies

pip install openai python-dotenv

• openai: API calls
• python-dotenv: automatically loads ./.env and ~/.env(optional, works without it)

Auth auto-resolution

The script looks for the API key in the following priority order:

1. OPENAI_API_KEY environment variable
2. ./.env file (current directory)
3. ~/.env file (home directory)
4. Pi agent auth (~/.pi/agent/auth.json → openai-codex.access)
5. Codex OAuth token（hermes auth codex logged in)
6. config.yaml → image_gen.openai.api_key
7. --api-key manually passed in

⚠️ Codex token limitation: Codex OAuth token/pi auth token can only authenticate chatgpt.com/backend-api/codex，cannotdirectly connect to api.openai.com. If auth resolution falls to a Codex token (priority 4-5), the script will use it as a standard API key to call api.openai.com/v1/images/*, returning 401 Missing scopes: api.model.images.request. For text-to-image, use Hermes' built-in image_generate tool (goes through the Codex backend); img2img / inpainting (images.edit) must have a real OPENAI_API_KEY. See references/auth-pitfalls.md。

Usage

Text-to-image

python3 scripts/gen.py -p "a cat astronaut on the moon" --quality high

# 多张
python3 scripts/gen.py -p "..." -n 4

Reference image editing (img2img)

# 单参考图
python3 scripts/gen.py -p "make it cyberpunk style" -i photo.jpg

# 多参考图
python3 scripts/gen.py -p "collab poster" -i cat.png -i logo.png -f out.png

Mask inpainting (inpainting)

# opaque 区域保留，transparent 区域重绘
python3 scripts/gen.py -p "replace sky with aurora" -i photo.jpg -m sky_mask.png

High resolution / custom format

python3 scripts/gen.py -p "..." --size 2k --quality high --format webp --compression 85
python3 scripts/gen.py -p "..." --size 3840x2160 --quality high

Prompt templates

Reference file:references/templates.md(833 lines, 16 categories of industrial-grade templates + pitfall guide).

Workflow: Agent reads templates.md → matches the appropriate template category → assembles a complete prompt using the template structure → calls gen.py to generate the image.

After loading the skill, the Agent needs to read references/templates.md in full or locate the relevant sections as needed. The templates cover 16 categories including UI, infographics, posters, e-commerce, branding, photography, characters, history, and industrial design, each with standard templates + pitfall guides.

Typical Agent workflow:

1. User says "draw a bowl of ramen" → Agent reads templates.md and locates the "E-commerce & Products" or "Photography & Realism" category
2. Agent refers to the template structure and pitfall-avoidance guide, assembles the complete prompt (filling in parameters such as lighting, materials, composition)
3. Agent uses clarify to display the optimized prompt and waits for user confirmation
4. After confirmation, calls gen.py -p "<prompt>" --quality high

If the prompt provided by the user is already detailed enough, skip optimization and call gen.py directly.

⚠️ Mandatory confirmation rule:

• User explicitly says "optimize and generate", "help me optimize the prompt", "optimize first then draw", etc. → Agent optimizes and thengenerates directly, no confirmation needed
• User only gives a vague prompt butdoes not request optimization → If the Agent modified the prompt,mustuse clarify to display the full modified prompt for the user to confirm; only after confirmation can gen.py be called
  • When confirming, must state "I optimized the prompt; upon confirmation it will generate:" so the user knows the prompt was changed
• If unmodified, generate directly

Parameter table

Parameter	Short form	Type	Default value	Description
--prompt	-p	str	Required	Prompt
--image	-i	path	—	Reference image, can be passed multiple times
--mask	-m	path	—	Alpha channel mask PNG (requires -i）
--output	-f	path	Auto-naming	Output file path
--n	-n	int	1	Number of images to generate
--model		str	gpt-image-2	Model ID
--quality	-q	literal	high	See quality strategy below
--size	-s	literal	1024x1024	See size table below
--format		literal	png	png / jpeg / webp
--compression		int	—	Compression level 0-100 (jpeg/webp)
--moderation		literal	low	low / auto
--background		literal	—	opaque / auto
--input-fidelity		literal	—	low / high(automatically removed by gpt-image-2)
--api-key		str	Auto-parse	Manually specify API key
--json		flag	—	JSON format output
--verbose	-v	flag	—	Verbose logging

Size quick-reference table

Shortcut name	Resolution	Use case
1k / square	1024×1024	Square, social avatar
2k	2048×2048	High-definition printing
4k	3840×2160	Widescreen cinematic
landscape	1536×1024	Landscape photo/game screenshot
portrait	1024×1536	Portrait poster/mobile wallpaper
wide	2048×1152	Wide landscape
tall	2160×3840	Extra-long portrait

Custom WxH is also supported:--size 1536x1536. Constraints: multiple of 16px, total pixels 655,360 ~ 8,294,400, aspect ratio ≤ 3:1.

Quality strategy

Quality	Speed	Cost (1024²)	When to use
auto	Adaptive	Adaptive	Let the API decide
low	~15s	~$0.006	Quick drafts, batch exploration, composition checks
medium	~40s	~$0.05	Style testing, everyday browsing
high	~2min	~$0.21	Chinese fonts, posters, infographics, formal delivery

Default high. Agent should automatically choose the tier based on the scenario: use low for exploration, medium for style experimentation, high for final delivery.

Output

• Default output format:── PROMPT ── + prompt + ── IMAGE ── + image path + ── PARAMS ── + parameters
• After receiving the output, the Agent must display both the image and the prompt, using ![desc](path) + prompt text
• Save to ~/.hermes/cache/images/（--output to overwrite)
• Each generation also saves a .prompt.txt sidecar file, with the same name and path as the image, recording the full prompt and all parameters for easy reuse
• --json mode outputs structured JSON

Exit codes

Code	Meaning	Handling
0	Success	Output path to stdout
1	API error	Check the moderation/rate-limit/content-policy response message
2	Parameter error	Missing API key, mask without image, n<1, etc.

Notes

• gpt-image-2 does not support transparent backgrounds (for transparency use gpt-image-1.5）
• --input-fidelity is automatically stripped on gpt-image-2 (the model rejects this parameter)
• --moderation only applies to images.generate，images.edit path is automatically stripped
• Codex backend does not support --mask mask inpainting, does not support -n multiple images
• The edit endpoint has a strict content policy for photos of real people and may return 400
• Complex prompts may take more than 2 minutes
• Requires OpenAI Organization Verification (standard API key); Codex OAuth does not
• Reference images are uploaded directly as binary; mind the file size
• --mask must be a PNG with an alpha channel, opaque=keep, transparent=redraw
• For the Codex backend architecture, see references/codex-backend.md
• Image attachment paths: Discord/Telegram caches are usually in ~/.hermes/image_cache/img_*.jpeg
• End-to-end test report:references/test-report.md
• img2img does not depend on the chat model's vision capability: reference images are sent directly as base64 to the Codex/OpenAI image backend, bypassing the chat model. Even if the current model (e.g. DeepSeek) does not support vision,vision_analyze fails,gen.py -i 's img2img still works normally. The Agent does not need to "understand" the image first to do reference-image editing—the image model handles visual understanding independently. If you really need to know the original image's content to write the prompt, you can use PIL for color/edge analysis to help judge the composition.<｜end▁of▁thinking｜>

<｜｜DSML｜｜parameter name="old_string" string="true">## Notes

• gpt-image-2 does not support transparent backgrounds (for transparency use gpt-image-1.5）
• --input-fidelity is automatically stripped on gpt-image-2 (the model rejects this parameter)
• --moderation only applies to images.generate，images.edit path is automatically stripped
• Codex backend does not support --mask mask inpainting, does not support -n multiple images
• The edit endpoint has a strict content policy for photos of real people and may return 400
• Complex prompts may take more than 2 minutes
• Requires OpenAI Organization Verification (standard API key); Codex OAuth does not
• Reference images are uploaded directly as binary; mind the file size
• --mask must be a PNG with an alpha channel, opaque=keep, transparent=redraw
• For the Codex backend architecture, see references/codex-backend.md
• Image attachment paths: Discord/Telegram caches are usually in ~/.hermes/image_cache/img_*.jpeg
• End-to-end test report:references/test-report.md