Openai Compatible Imagegen

OpenAI-Compatible Image Generation

Use this skill to call the bundled image generation script. Do not rewrite the API client inline.

Workflow

1. Run info first to inspect the local configuration. If auth.json is missing, run init.
2. Choose the mode:

• generate: text-to-image
• edit: image editing, inpainting, or reference-image generation
• batch: JSONL batch generation with limited concurrency
• info: configuration summary

1. Resolve parameters in this order:

• explicit user request
• per-row batch parameters
• agent judgment from the prompt
• auth.json defaults

1. Choose quality deliberately:

• use low or medium for drafts and broad exploration
• use high for final assets, UI, posters, covers, dense text, or user requests for finished detail
• use auto only when leaving the decision to the backend is acceptable

1. Before execution, decide output path, image count, aspect/size, resolution, quality, transparency intent, and reference images.
2. Call scripts/imagegen.py.
3. Report output image paths, manifest path, success count, failure count, and short failure summaries.

Never read, print, quote, or summarize the secret value in auth.json.

For explicit post-processing, delivery-size normalization, image inspection, or grid splitting, read references/postprocess.md first. Do not load it for ordinary image generation.

Local Auth

The private config file is always auth.json in this skill directory. It is local-only and must not be committed.

Initialize it:

$SkillDir = "$env:USERPROFILE/.codex/skills/openai-compatible-imagegen"
python "$SkillDir/scripts/imagegen.py" init

Initialize non-secret fields:

$SkillDir = "$env:USERPROFILE/.codex/skills/openai-compatible-imagegen"
python "$SkillDir/scripts/imagegen.py" init `
  --base-url "https://example.com/v1" `
  --model "gpt-image-2" `
  --api-key-env "OPENAI_API_KEY"

API key options:

• Put the key directly in auth.json as api_key.
• Put an environment variable name in api_key_env, then set that environment variable.

If both are present, the script uses api_key. If api_key is still the template placeholder, the script reads api_key_env.

Config fields:

• base_url: OpenAI-compatible API base URL, usually ending in /v1.
• api_key: API key stored directly in local auth.json.
• api_key_env: optional environment variable name for the API key.
• model: default image model, for example gpt-image-2.
• capabilities.transparent_background: whether the backend supports background=transparent.
• defaults: weak defaults used only when parameters are missing.
• postprocess.enabled: optional post-processing opt-in. Missing means false and preserves legacy behavior.

Commands

All commands can be run from any working directory.

Configuration summary:

$SkillDir = "$env:USERPROFILE/.codex/skills/openai-compatible-imagegen"
python "$SkillDir/scripts/imagegen.py" info

Text-to-image:

$SkillDir = "$env:USERPROFILE/.codex/skills/openai-compatible-imagegen"
python "$SkillDir/scripts/imagegen.py" generate `
  -p "Warcraft 3 style frost skill icon, single rune, centered, no text" `
  -f "outputs/frost-rune.png" `
  --aspect 1:1 `
  --resolution 1K `
  --quality high

Reference-image edit:

$SkillDir = "$env:USERPROFILE/.codex/skills/openai-compatible-imagegen"
python "$SkillDir/scripts/imagegen.py" edit `
  -p "Convert this to a dark magic UI style" `
  -i "input.png" `
  -f "outputs/dark-ui.png"

Batch generation:

$SkillDir = "$env:USERPROFILE/.codex/skills/openai-compatible-imagegen"
python "$SkillDir/scripts/imagegen.py" batch `
  --input "prompts.jsonl" `
  --out "outputs/imagegen" `
  --concurrency 3

Transparent-background asset intent:

$SkillDir = "$env:USERPROFILE/.codex/skills/openai-compatible-imagegen"
python "$SkillDir/scripts/imagegen.py" generate `
  -p "Centered fire orb game item asset, no text" `
  -f "outputs/fire-orb.png" `
  --asset `
  --transparent

Parameters

Core parameters:

• -p, --prompt: required for generate and edit.
• -f, --file: output file. If omitted, the script writes to the current directory.
• -i, --image: reference image. Repeat for multiple images. Uses the edit endpoint.
• -m, --mask: mask image for edit mode.
• --size: examples include 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
• --aspect: 1:1, 16:9, 4:3, 3:4, or 9:16. Use this when the user describes shape but not exact pixels.
• --resolution: 1K, 2K, or 4K. Used with --aspect to choose a concrete supported size.
• --quality: low, medium, high, or auto.
• --n: number of images returned by one request.
• --format: png, jpeg, or webp.
• --background: auto, opaque, or transparent. The script sends transparent only when the config declares backend support.
• --transparent: transparent-background asset intent shortcut. Forces PNG and injects transparent-background constraints into the prompt. If supported, also sends background=transparent.
• --asset: asset shortcut. Prefers PNG and is suitable for icons, game items, textures, and sprites.
• --concurrency: limited batch concurrency.

Read references/parameters.md for detailed behavior.

Batch Format

batch input is JSONL, one task per line. See examples/batch.example.jsonl.

Common fields:

• id
• mode
• prompt
• file
• size
• aspect
• resolution
• quality
• n
• format
• background
• transparent
• asset
• images
• mask
• model
• timeout

Batch mode uses limited concurrency. Concurrency priority:

command --concurrency > auth.json defaults.concurrency > 3

Do not add model switching, endpoint switching, background removal, retries with altered parameters, or any other fallback strategy unless the user explicitly asks for it.

Post-processing is also opt-in. Unless auth.json postprocess.enabled=true or the user explicitly requests normalization, resizing, cropping, image inspection, or grid splitting, keep the legacy generate/edit/batch behavior.

Transparent Assets

When the user asks for assets, icons, items, textures, sprites, transparent background, or transparent PNG, prefer --asset. Add --transparent when the user explicitly wants a transparent background.

Transparency has two layers:

• prompt layer: always available; asks the model for an isolated subject and alpha-friendly edges
• API parameter layer: only sent when capabilities.transparent_background=true

When background=transparent or --transparent conflicts with the selected model and resolution, the script stops before sending the request. Ask the user to choose whether to switch to a transparent-capable model or keep the current model with background=auto.

Do not promise a real alpha channel unless the backend actually returns one. Do not add local background-removal post-processing unless the user explicitly asks for that implementation.

Output

The script saves images and writes manifest.json in batch mode.

Report only:

• output image paths
• manifest path
• success and failure counts
• short failure summaries

Do not show API keys, full request headers, or config content that contains secrets.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Syh1906
• Source: Syh1906/openai-compatible-imagegen
• License: MIT

Install and usage instructions live in the source repository linked above.