# 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

```powershell
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`.

```text
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

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

Force Images API mode for one request:

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

Use Images API edit mode:

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

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

```text
[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

```toml
[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

```powershell
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:

```text
.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:

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

After publishing to GitHub:

```powershell
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

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