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:

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

Then run the local preflight:

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

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

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.