Image Relay Bridge

Portable CLI, MCP server, and agent skill for third-party image-generation relay services.

This project is for cases where a relay exposes OpenAI-compatible image endpoints, but Codex, Claude Code, or another coding agent cannot call that relay directly. The bridge calls the configured relay, saves the generated image locally, and returns paths plus Markdown display hints that agents can use in conversation.

Supported upstream styles:

• POST /v1/responses with an image-generation tool and SSE events.
• POST /v1/images/generations for text-to-image.
• POST /v1/images/edits for image editing with source images and optional masks.

No relay URL, API key, local username, or personal GitHub account is hardcoded. All sensitive values belong in environment variables or an uncommitted .env.

Install

git clone https://github.com/qa594741/image-relay-bridge.git
cd image-relay-bridge
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test,mcp]"

Configure

Copy .env.example to .env and replace the example values with your relay's real values. Do not commit .env.

IMAGE_RELAY_BASE_URL=https://relay.example.com/v1
IMAGE_RELAY_API_KEY=replace-with-your-relay-key
IMAGE_RELAY_TEXT_MODEL=example-text-model
IMAGE_RELAY_IMAGE_MODEL=example-image-model
IMAGE_RELAY_API_MODE=responses
IMAGE_RELAY_REQUEST_POLICY=openai
IMAGE_RELAY_OUTPUT_DIR=./outputs
IMAGE_RELAY_DEFAULT_SIZE=auto
IMAGE_RELAY_DEFAULT_QUALITY=high
IMAGE_RELAY_DEFAULT_OUTPUT_FORMAT=png
IMAGE_RELAY_DEFAULT_BACKGROUND=auto
IMAGE_RELAY_DEFAULT_OUTPUT_COMPRESSION=100
IMAGE_RELAY_DEFAULT_PARTIAL_IMAGES=0
IMAGE_RELAY_DEFAULT_PROMPT_TEMPLATE={prompt}。请根据主题自动判断最合适的画幅与构图：风景、城市空间、室内环境、多人关系或需要展示背景层次时优先横向；单人肖像、单主体海报、垂直建筑或手机壁纸场景优先竖向；构图不确定或主体与环境同等重要时使用方形。优化主体比例、景深、光线、材质、空间层次和细节密度；保持画面清晰、主体明确、边缘干净，避免低清晰度、过度柔焦、文字水印和无关元素。
IMAGE_RELAY_DEFAULT_NEGATIVE_PROMPT=
IMAGE_RELAY_CLI_OPEN_IMAGE=true
IMAGE_RELAY_SHOW_PROGRESS=true
IMAGE_RELAY_SHOW_DEBUG_SUMMARY=true

IMAGE_RELAY_DEFAULT_PROMPT_TEMPLATE supports a {prompt} placeholder. This lets users keep a scene-agnostic directing template in config and only type the short subject each time.

IMAGE_RELAY_API_MODE:

• responses: POST /v1/responses, best when the relay supports image-generation SSE events.
• images: POST /v1/images/generations and POST /v1/images/edits, useful for relays that expose Images API compatible routes.

IMAGE_RELAY_REQUEST_POLICY:

• openai: only send official OpenAI-style image fields.
• compat: also send relay-style fields such as negative_prompt and seed when supported by the relay.

CLI Usage

image-relay-generate "一只白猫坐在上海夜景窗边"

Force Images API mode for one request:

image-relay-generate --api-mode images "一只白猫坐在窗边"

Use Images API edit mode:

image-relay-generate --api-mode images --image .\source.png --mask .\mask.png "把窗外改成雪夜"

The CLI prints progress lines to stderr with elapsed time, for example:

[progress] [0.8s] Connected to upstream.
[progress] [1.0s] Upstream accepted the request.
[progress] [1.4s] Image generation started.
[progress] [12.6s] Image is rendering.
[progress] [87.3s] Final image received from upstream.
[progress] [87.4s] Generation completed.

The JSON result includes image_path, markdown_image, actual_size, elapsed_seconds, raw_log_path, and a filtered debug_summary when enabled.

In CLI use, the bridge opens the generated image with the OS image viewer by default. Use --no-open or IMAGE_RELAY_CLI_OPEN_IMAGE=false for automation.

MCP Capability Scope

The MCP server exposes one tool: generate_image.

It can:

• Generate images from prompts.
• Edit images when the relay supports /v1/images/edits.
• Pass source image paths and optional mask paths.
• Save generated images under the configured output directory.
• Return absolute local paths and markdown_image so Codex App can display the image in the conversation.
• Return raw SSE/log paths and filtered debug summaries for troubleshooting.

It does not:

• Store API keys.
• Discover relay model names.
• Guarantee that a relay supports every OpenAI image parameter.
• Guarantee percentage progress unless the relay sends trustworthy percentage data.
• Manage billing, rate limits, relay account status, or model availability.

Codex MCP Registration

[mcp_servers.image_relay_bridge]
command = "image-relay-mcp"
cwd = "PATH_TO_IMAGE_RELAY_BRIDGE_REPO"

The API key should come from your shell environment or a local uncommitted .env.

Claude Code

python -m pip install -e ".[mcp]"
claude mcp add image-relay-bridge image-relay-mcp

The MCP tool is named generate_image. If no image options are passed, it uses the defaults from .env, including the prompt template.

MCP results include markdown_image; in Codex App, agents should include that Markdown image tag in the assistant reply to display the generated image in the conversation.

Skill And Plugin Packaging

This repository contains:

.codex-plugin/plugin.json
.claude-plugin/plugin.json
.mcp.json
.agents/plugins/marketplace.json
skills/image-relay-bridge/SKILL.md

Skill responsibilities:

• Explain when to use MCP versus CLI.
• Tell agents how to display generated images.
• Warn agents not to print keys, raw headers, real relay URLs, or raw logs.

Plugin responsibilities:

• Package skill metadata and MCP metadata for easier installation.
• Avoid storing secrets.
• Leave the actual relay configuration to local environment variables.

Local Codex plugin install flow:

codex plugin marketplace add "PATH_TO_IMAGE_RELAY_BRIDGE_REPO"
codex plugin add image-relay-bridge --marketplace image-relay-bridge

After publishing to GitHub:

codex plugin marketplace add qa594741/image-relay-bridge --ref master
codex plugin add image-relay-bridge --marketplace image-relay-bridge

For Claude Code or other agents with skill support, install or copy skills/image-relay-bridge as a skill and register image-relay-mcp as the MCP server.

Test

python -m pip install -e ".[test]"
python -m pytest