relay-image-gen

name	relay-image-gen
description	Multi-provider image generation with automatic priority fallback

Relay Image Generation

Multi-provider image generation with automatic priority fallback.

Priority Chain

1. qingyun Gemini (gemini-3-pro-image-preview) ← 首选，质量最佳
   ↓ 失败/不可用
2. OpenClaw image_generate tool ← 官方内置
   ↓ 失败/不可用
3. boluobao (中转API) ← relay fallback 1
   ↓ 失败/不可用
4. xingjiabi (多模型fallback) ← relay fallback 2
   ↓ 失败/不可用
5. 自定义扩展 providers ← 按需添加

1. qingyun Gemini（首选）

推荐用于所有内容封面和高质量图片生成。

export QINGYUN_API_KEY=$(pass show api/qingyun | head -n 1)
bash ~/clawd/skills/qingyun-api/scripts/qingyun-image-gemini.sh \
  "your prompt" \
  --ratio 3:4 \
  -o "/path/to/output"

参数	说明	默认值
--ratio	1:1 / 3:4 / 4:3 / 16:9 / 9:16	1:1
-o	输出路径（由调用方指定，不写死）	必填

优点：出图质量高、比例控制准确、支持中文提示词 要求：pass show api/qingyun 需配置 API Key

2. OpenClaw image_generate（官方）

直接使用 OpenClaw 内置图片生成工具：

image_generate(
  prompt="your prompt",
  size="1024x1024",
  aspectRatio="1:1"
)

优点：无需额外 API Key，自动路由到最佳可用 provider 注意：由 OpenClaw 运行时管理，不在 bash 中调用

3-4. Relay Providers（备选）

uv run ~/.openclaw/skills/relay-image-gen/scripts/relay_image_gen.py \
  -p "your prompt" \
  -f "/path/to/output.jpg" \
  -a "3:4" \
  -r "1k"

Flag	说明	默认值
-p	图片提示词（英文推荐）	必填
-f	输出文件路径	必填
-r	分辨率：1k / 2k / 4k	1k
-a	比例：1:1 / 16:9 / 9:16 / 3:4 等	1:1
-m	覆盖模型名	Provider默认
-P	强制 Provider：boluobao / xingjiabi	Auto

Relay 内部优先级：boluobao → xingjiabi

各 Provider 配置

Provider	API Key 来源	默认模型	Fallback
boluobao	pass show api/boluobao	gemini-3-pro-image-preview	—
xingjiabi	环境变量 XINGJIABIAPI_KEY	dall-e-3	gpt-image-1 → imagen-4

输出路径规范

不写死路径。由调用方指定，默认遵循：

~/clawd/projects/MediaClaw/output/articles/{YYYY-MM-DD}/{topic-slug}.{ext}

扩展自定义 Provider

添加新的中转 API 只需两步：

Step 1: 编辑 PROVIDER_CONFIG

在 ~/.openclaw/skills/relay-image-gen/scripts/relay_image_gen.py 中添加：

PROVIDER_CONFIG["my-provider"] = {
    "base_url": "https://api.my-provider.com/v1",
    "default_model": "my-model-name",
    "fallback_models": ["fallback-model-1", "fallback-model-2"],
    "env_key": "MY_PROVIDER_API_KEY",       # 环境变量名
    "pass_path": "api/my-provider",          # 或 pass 路径（二选一）
}

Step 2: 添加到优先级链

RELAY_PRIORITY = [
    {"name": "boluobao", "enabled": True},
    {"name": "my-provider", "enabled": True},  # ← 插入
    {"name": "xingjiabi", "enabled": True},
]

Provider 配置字段说明

字段	说明	必填
base_url	API endpoint	✅
default_model	主模型	✅
fallback_models	失败后尝试的模型列表	可选
env_key	环境变量名	与 pass_path 二选一
pass_path	pass show 路径	与 env_key 二选一

调用示例

# 内容封面（首选 qingyun）
export QINGYUN_API_KEY=$(pass show api/qingyun | head -n 1)
bash ~/clawd/skills/qingyun-api/scripts/qingyun-image-gemini.sh \
  "Editorial flat illustration of AI tools comparison..." \
  --ratio 3:4 \
  -o "~/clawd/projects/MediaClaw/output/articles/2026-04-15/ai-tools-cover.png"

# 通用图片（relay fallback）
uv run ~/.openclaw/skills/relay-image-gen/scripts/relay_image_gen.py \
  -p "A serene Japanese garden with cherry blossoms" \
  -f "~/clawd/projects/MediaClaw/output/articles/2026-04-15/garden-bg.jpg" \
  -a "16:9" -r "2k"

# 强制指定 provider
uv run ~/.openclaw/skills/relay-image-gen/scripts/relay_image_gen.py \
  -p "Robot waving hello" \
  -f "robot.jpg" \
  -P xingjiabi -m gpt-image-1

# OpenClaw 内置（无bash）
image_generate(prompt="sunset over mountains", size="1792x1024", aspectRatio="16:9")

内容封面

生成内容封面时，请先读取 content-cover-gen skill 获取完整的视觉隐喻设计方法论和提示词模板：

cat ~/clawd/skills/content-cover-gen/SKILL.md

核心原则：每张封面提示词必须包含文章核心观点的视觉隐喻 + 中文文字，严禁纯风格通用提示词。

Provider 详细信息

参见 references/providers.md 了解 API 格式、模型列表和添加方法。