OpenClaw NewAPI 图像生成插件 (NewAPI Image Provider)

基于 OpenClaw 原生 TypeScript 插件 SDK 构建的 ImageGenerationProvider 插件，迁移并完美继承了 Hermes newapi 图像后端的全部核心特性。

支持通过 NewAPI（Gemini 和 OpenAI-compatible 协议端点）进行文生图、带参考图的图片编辑（图生图）、多模型回退链降级（Fallback Chains）以及高级生图参数透传。

🌟 主要特性

1. 双协议兼容：支持以 OpenAI 兼容的 /images/generations 和 /images/edits 进行生图和编辑，同时支持以 Gemini 多模态 inlineData 进行 generateContent 生图和编辑。
2. 多模型链式回退 (Fallback)：支持 parallel（并行尝试）、openai_first（优先 OpenAI）和 gemini_first（优先 Gemini）回退模式，按配置的模型链自顶向下尝试，当某个模型或接口遇到不可用（如 502/504 等网络问题）时，无缝切换到备用模型。
3. 动态链式起点：支持显式请求具体模型，自动从该模型在链中的位置开始向后降级（非写死）。
4. 高级生图参数透传：支持将 OpenClaw 的高级参数自动映射和透传至上游（包括 quality、outputFormat、background=transparent、以及 openai.* 控制的压缩比与审核等）。
5. 极简配置：完全通过 .env 环境变量注入配置，无需修改 OpenClaw 核心，与您的现有环境天然融合。

⚙️ 环境变量配置

请在您的 OpenClaw .env 文件（例如 ~/.openclaw/.env）中写入以下配置块：

# ==============================================================================
# NewAPI Image Generation Configuration (Migrated from Hermes)
# ==============================================================================
# 您的 NewAPI 网关地址（v1 根路径）
NEWAPI_BASE_URL="https://api.aihao.de/v1"

# 您的 NewAPI 密钥（若未设置，插件会尝试回退读取全局 API_KEY）
NEWAPI_API_KEY="sk-YOUR_NEWAPI_API_KEY_HERE"

# 图像生成回退链优先模式: 'parallel' | 'openai_first' | 'gemini_first'
NEWAPI_MODE="openai_first"

# Gemini 图像模型降级链，用逗号分隔，越靠前优先度越高
NEWAPI_GEMINI_MODELS="gemini-3-pro-image-preview,gemini-3.1-flash-image-preview,gemini-2.5-flash-image"

# OpenAI 兼容图像模型降级链，用逗号分隔
NEWAPI_OPENAI_MODELS="gpt-image-2"

🚀 支持模型

• newapi/auto：智能路由，根据优先模式（如 openai_first）自动决策。
• newapi/gpt-image-2：使用 OpenAI-compatible 的图片生成与编辑。
• newapi/gemini-3-pro-image-preview：使用 Gemini 链中的 Pro 预览。
• newapi/gemini-3.1-flash-image-preview：使用 Flash 预览。
• newapi/gemini-2.5-flash-image：使用 Flash 精简生图。

💡 使用方法 (Usage Examples)

在 OpenClaw 中可以通过图像生成工具或 Chat 命令直接唤起本插件：

1. 基础文生图 (Text-to-Image)

/tool image_generate model=newapi/auto prompt="一只在太空中漂浮的赛博朋克猫咪，精致原画" aspectRatio=16:9 timeoutMs=180000

2. OpenAI 兼容图生图编辑 (/images/edits)

/tool image_generate model=newapi/gpt-image-2 image=/path/to/reference.png prompt="保持主体不变，把背景改成落日霓虹的都市霓虹灯" size=1024x1024 timeoutMs=180000

(注：如果遇到 504 Gateway Timeout 超时，请排查您的网络出口是否启用了 Cloudflare WARP 导致了大文件数据挂起)

3. Gemini 图生图多模态编辑 (inlineData)

/tool image_generate model=newapi/gemini-3-pro-image-preview image=/path/to/reference.png prompt="帮我在背景里加上雪山城堡，保持主体一致性" aspectRatio=16:9 resolution=2K timeoutMs=180000

🛠️ 安装与迁移

本插件已被正式发布至 ClawHub。

1. 自动从 ClawHub 安装

在新环境下，只需直接运行：

openclaw plugins install clawhub:@wstanfeng/newapi-image

2. 本地链接安装 (开发者模式)

如果您想在新环境继续对其进行二次开发，请将本项目克隆/解压到 /home/node/.openclaw/workspace/plugins/newapi-image 目录后运行：

cd /home/node/.openclaw/workspace/plugins/newapi-image
npm install
npm run build
openclaw plugins install /home/node/.openclaw/workspace/plugins/newapi-image --link

随后重启 OpenClaw Gateway 即可载入。