# Relay Imagegen

> Generate or edit raster images through a user-configured OpenAI-compatible image relay and save validated PNG, JPEG, or WebP files. Use when the user explicitly invokes $relay-imagegen or clearly asks to use an image relay or middle station for text-to-image generation, single-image editing, or optional PNG-mask inpainting. Do not use for ordinary image requests intended for the built-in imagegen skill.

- Skill: `zxbdzh/relay-imagegen` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add zxbdzh/relay-imagegen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zxbdzh/relay-imagegen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zxbdzh (https://skillmd.com/u/zxbdzh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zxbdzh/relay-imagegen

---


# Relay Imagegen

Use the bundled CLI to call an OpenAI-compatible relay. Do not depend on the built-in `imagegen` tool or the OpenAI Python SDK.

## Configuration

Require these dedicated environment variables:

- `IMAGE_RELAY_BASE_URL`: complete API root such as `https://relay.example.com/v1`
- `IMAGE_RELAY_API_KEY`: relay API key
- `IMAGE_RELAY_MODEL`: default model, unless `--model` is supplied
- `IMAGE_RELAY_PROXY`: default HTTP/HTTPS proxy for relay API requests and returned-image downloads. Set it for proxy-routed calls; an explicit `--proxy` overrides it for one invocation.

Proxy policy:

- For every `generate`, `edit`, or `check --network` call, use `--proxy "$env:IMAGE_RELAY_PROXY"` or an explicitly approved proxy URL.
- The bundled CLI resolves an explicit `--proxy` first, then `IMAGE_RELAY_PROXY`.
- Do not use `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY`; the CLI intentionally sets `trust_env=False` and ignores system proxy variables.
- Before a network or image call, fail clearly when neither `IMAGE_RELAY_PROXY` nor an explicit `--proxy` is present instead of silently falling back to a direct request.

Prefer HTTPS relay URLs. Plain HTTP remains supported for trusted local or development relays, but it sends the API key and prompt without transport encryption; report the CLI warning when it is used.

Never reuse `OPENAI_API_KEY`, load `.env`, store credentials in the skill, place a key in a command argument, or ask the user to paste a key into chat. For a manually managed one-time secret, the CLI supports `--api-key-stdin`; do not expose that secret in a tool call.

Run commands from the user's current project directory so relative inputs and outputs resolve against that project. Refer to this skill's installation directory as `<skill-dir>` below.

## Workflow

1. Choose `generate` for text-to-image or `edit` for one local target image.
2. Collect the prompt, model override, output path, size, quality, output format, and proxy before calling the relay.
3. For a specific prompt, preserve its details and constraints. For a vague prompt, add only useful composition or medium detail. Do not invent characters, brands, palettes, slogans, or story elements.
4. For edits, state what may change and what must remain unchanged. Accept one PNG/JPEG/WebP target and an optional same-size PNG mask with an alpha channel.
5. Treat explicit invocation as approval for the requested API call only. Ask again before retrying, creating extra variants, or running a live smoke test.
6. Parse the CLI's stdout as JSON. Do not infer success or paths from stderr text.
7. Perform only technical validation. Do not automatically inspect visual quality or regenerate.

## Check Configuration

For initial setup or after a configuration error, run:

Before a network or image call, verify the dedicated proxy is configured:

```powershell
if ([string]::IsNullOrWhiteSpace($env:IMAGE_RELAY_PROXY)) {
  throw "IMAGE_RELAY_PROXY is required for relay network calls"
}
```

Then run the local preflight:

```powershell
uv run "<skill-dir>/scripts/relay_image.py" check --proxy "$env:IMAGE_RELAY_PROXY"
```

Add `--network` to call the relay's `/models` endpoint without generating an image. Do not run a separate `check` process before a call that uses `--api-key-stdin`; `generate` and `edit` perform the same local preflight in-process.

## Generate

```powershell
uv run "<skill-dir>/scripts/relay_image.py" generate `
  --prompt "A minimal ceramic coffee mug product photo" `
  --size "1024x1024" `
  --output-format png `
  --proxy "$env:IMAGE_RELAY_PROXY" `
  --out "output/image-relay/coffee-mug.png"
```

Use `--n` for variants of one prompt. Invoke the script separately for distinct prompts. Do not add automatic retries.

## Edit

```powershell
uv run "<skill-dir>/scripts/relay_image.py" edit `
  --image "input/product.png" `
  --mask "input/mask.png" `
  --prompt "Replace only the transparent masked area; keep the product unchanged" `
  --proxy "$env:IMAGE_RELAY_PROXY" `
  --out "output/image-relay/product-edited.png"
```

Omit `--mask` for a whole-image edit. The CLI accepts one target image plus repeatable `--reference` images for identity or appearance guidance; multi-image requests use the relay-compatible repeated `image[]` multipart field, while single-image requests keep the standard `image` field. Do not use remote edit inputs or automatic format conversion.
The CLI reads each local input once, validates that in-memory snapshot, and uploads those same bytes, so validation and transmission use one immutable view of the file.

## Advanced Parameters

Use explicit options for `--model`, `--proxy`, `--size`, `--quality`, `--output-format`, `--timeout`, `--out`, and `--overwrite`. `--proxy` applies to the relay API request and any returned image URL download for that invocation; when omitted, the CLI uses `IMAGE_RELAY_PROXY`. System proxy environment variables are ignored. `--overwrite` requires an explicit output file. It replaces that exact lexical path, including replacing a final-component symbolic link rather than following it, only when the returned image format matches its suffix; otherwise the CLI preserves the target and writes a versioned file with the correct suffix. Use `--extra-json` only for relay-specific fields. It must be a JSON object and cannot override `prompt`, `model`, `image`, `mask`, `n`, `size`, `quality`, `output_format`, or `response_format`.

Response bytes are written through their original file descriptors inside a private per-call staging directory under the output directory. Normal non-overwriting publication then uses an atomic hard link. If the output filesystem does not support hard links, the CLI uses a non-atomic exclusive-copy fallback, never replaces an existing path, and reports a warning.

The CLI accepts both base64 image responses and HTTP/HTTPS image URLs. It does not force the optional `response_format` request field because some OpenAI-compatible relays reject it. The configured relay controls returned URLs, which the CLI may fetch from arbitrary public, private, or local addresses and follow across redirects. There is no application-level response or download size cap. Use only a trusted relay and environment; the separate download client never forwards relay authorization or cookies.

## Report Results

On success, report the operation, model, final prompt, and every saved absolute path from the JSON response. On failure, report the structured error kind and sanitized message. Sanitization is context-sensitive so artifact paths remain exact while error text, relay fields, and sensitive extension values are redacted. Do not retry unless the user explicitly approves another potentially billable request.

Do not claim transparent-background generation, multi-reference editing, prompt-batch JSONL, automatic visual scoring, or automatic iteration; those capabilities are outside this skill.