---
name: image-gen-custom
description: Generate images through any OpenAI-compatible Images API and save reproducible local PNG, JPEG, GIF, or WebP files. Use when Codex needs a custom image endpoint, explicit model and output path, or a dependable cross-platform image generation workflow.
---

# Image Gen Custom

Use `scripts/generate-image.ps1` on Windows or `scripts/generate-image.sh` on macOS/Linux. The wrappers create or reuse a private virtual environment; generation uses only the Python standard library. The Python core reads the API key, calls the Images API, validates the returned image, and writes it atomically.

```powershell
& "$env:USERPROFILE\.codex\skills\image-gen-custom\scripts\generate-image.ps1" `
  -Prompt "A concise prompt..." `
  -Out "outputs\generated-image.png" `
  -Size "1024x1024" `
  -Quality "low" `
  -Force
```

```bash
"$HOME/.codex/skills/image-gen-custom/scripts/generate-image.sh" \
  --prompt "A concise prompt..." \
  --out outputs/generated-image.png \
  --size 1024x1024 \
  --quality low \
  --force
```

## Credentials

Run the matching `configure` wrapper once. It prompts for the API base URL first, then prompts for the key in visible text so you can paste it. On Windows, the key is saved in a DPAPI-protected local file; on macOS and Linux, it uses the platform credential store.

```powershell
& "$env:USERPROFILE\.codex\skills\image-gen-custom\scripts\configure.ps1"
```

```bash
"$HOME/.codex/skills/image-gen-custom/scripts/configure.sh"
```

The URL and Windows key file are saved under the local Codex shared configuration folder. The normal image command then needs no URL argument. An explicit `-BaseUrl` on the image command still overrides the saved value.

Set `OPENAI_API_KEY` instead when an ephemeral environment variable is preferred. Set `OPENAI_BASE_URL` for a custom OpenAI-compatible root; `/v1` is appended when omitted. Never put a key in `SKILL.md`, scripts, shell history, command arguments, ZIP files, or source control.

## Options and behavior

- Default model: `gpt-image-2`; use `-Model` or `--model` to override it.
- Use low quality for drafts and high quality for final images.
- Accept `b64_json` and absolute HTTP(S) URL responses; URL downloads are capped at 50 MB and checked for image signatures.
- Use `CODEX_IMAGEGEN_VENV` to choose the private virtual environment location.
- Use `CODEX_IMAGEGEN_PYTHON` to choose the Python executable used to bootstrap that environment.
- Report the concrete failure category without exposing credentials: missing runtime/dependency, keyring or authentication, network/permission, unsupported model/endpoint, quota, response parsing, download, or output writing.

## Install a shared package

Extract the package and run `scripts/install-skill.ps1` on Windows or `scripts/install-skill.sh` on macOS/Linux. Add `-Force` or `--force` only when updating an existing installation; the installer never overwrites the destination's keyring data or any local secret file. Start a new Codex task after installation.