npm package: @hamaster/openai-image-gen-server
Description: OpenAI Compatible Image Generation MCP Server - 提供图片生成工具，兼容OpenAI API结构
Author: hamaster
Latest version: 1.0.3

# OpenAI Compatible Image Generation MCP Server

一个兼容 OpenAI API 的图片生成 MCP 服务器，支持文本描述和参考图片生成，可选择不同的图片比例和返回格式。

## 功能特性

- ✅ **OpenAI Chat Completions 兼容**：使用标准 Chat Completions API 格式
- ✅ **API 密钥轮询**：支持配置多个 API 密钥自动轮询使用
- ✅ **灵活配置**：API 基础路径、模型名称等通过环境变量配置
- ✅ **多模型支持**：支持 sora_image、gpt-4o-image-vip、gemini 等模型
- ✅ **参考图片**：支持最多 3 张图片 URL 进行图片编辑或参考生成
- ✅ **多种比例**：支持 1:1、2:3、3:4 等图片比例
- ✅ **灵活返回**：可选择返回 Base64 或 URL（自动上传到 MinIO）
- ✅ **MinIO 集成**：内置 MinIO 支持，自动管理图片存储

## 安装

```bash
npm install @hamaster/openai-image-gen-server
```

或者直接从源码安装：

```bash
cd openai-image-gen-server
npm install
```

## 配置

创建 `.env` 文件并配置以下环境变量：

```env
# OpenAI API 配置
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_API_KEY=sk-your-api-key-1,sk-your-api-key-2,sk-your-api-key-3
OPENAI_MODEL=dall-e-3

# MinIO 配置（可选，用于 URL 返回模式）
MINIO_ENDPOINT=minio.example.com
MINIO_PORT=9000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=generated-images
MINIO_PUBLIC_URL=https://minio.example.com
```

### 环境变量说明

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `OPENAI_API_BASE` | 否 | `https://api.openai.com/v1` | API 基础路径 |
| `OPENAI_API_KEY` | 是 | - | API 密钥，支持逗号分隔多个 |
| `OPENAI_MODEL` | 否 | `dall-e-3` | 默认模型名称 |
| `MINIO_ENDPOINT` | 否 | `minio.example.com` | MinIO 服务器地址 |
| `MINIO_PORT` | 否 | `9000` | MinIO 端口 |
| `MINIO_USE_SSL` | 否 | `false` | 是否使用 SSL |
| `MINIO_ACCESS_KEY` | 否 | `minioadmin` | MinIO 访问密钥 |
| `MINIO_SECRET_KEY` | 否 | `minioadmin` | MinIO 密钥 |
| `MINIO_BUCKET_NAME` | 否 | `generated-images` | MinIO 存储桶名称 |
| `MINIO_PUBLIC_URL` | 否 | `https://minio.example.com` | MinIO 公开访问 URL |

## 使用

### 1. 本地运行

```bash
npm start
```

### 2. 在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "openai-image-gen": {
      "command": "node",
      "args": ["path/to/openai-image-gen-server/src/index.js"],
      "env": {
        "OPENAI_API_BASE": "https://api.openai.com/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "OPENAI_MODEL": "dall-e-3",
        "MINIO_ENDPOINT": "minio.example.com",
        "MINIO_PORT": "9000",
        "MINIO_USE_SSL": "false",
        "MINIO_ACCESS_KEY": "minioadmin",
        "MINIO_SECRET_KEY": "minioadmin",
        "MINIO_BUCKET_NAME": "generated-images",
        "MINIO_PUBLIC_URL": "https://minio.example.com"
      }
    }
  }
}
```

## 可用工具

### openai_image_generation

使用兼容 OpenAI Chat Completions API 的接口生成图片。

**参数：**

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `prompt` | string | 是 | 图片生成的文本描述 |
| `model` | string | 否 | 使用的模型名称（可选值：sora_image, gpt-4o-image-vip, gemini-2.5-flash-image-preview, gemini-3-pro-image-preview） |
| `images` | array | 否 | 参考图片的 URL（最多 3 张） |
| `ratio` | string | 否 | 图片比例（1:1, 2:3, 3:4），默认 1:1 |
| `return_type` | string | 否 | 返回格式（base64 或 url），默认 base64 |

**示例：**

1. 基础文本生成：

```json
{
  "prompt": "一只可爱的小猫坐在花园里，阳光明媚",
  "ratio": "1:1",
  "return_type": "base64"
}
```

2. 使用参考图片（URL）：

```json
{
  "prompt": "将这张图片改成赛博朋克风格",
  "images": ["https://example.com/image1.jpg", "https://example.com/image2.png"],
  "ratio": "3:4",
  "return_type": "url"
}
```

3. 指定模型：

```json
{
  "prompt": "一个未来主义的城市景观",
  "model": "gpt-4o-image-vip",
  "ratio": "2:3",
  "return_type": "url"
}
```

**返回格式：**

- Base64 返回：
```json
{
  "success": true,
  "model": "sora_image",
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "ratio": "1:1",
  "prompt": "一只可爱的小猫...",
  "reference_images_count": 0,
  "return_type": "base64",
  "request_id": "xxx"
}
```

- URL 返回：
```json
{
  "success": true,
  "model": "sora_image",
  "url": "https://cdn.deepix.hk/tmp/image_1234567890.png",
  "ratio": "1:1",
  "prompt": "一只可爱的小猫...",
  "return_type": "url"
}
```

## 支持的图片比例

| 比例 | 分辨率 |
|------|--------|
| 1:1 | 1024x1024 |
| 2:3 | 1024x1536 |
| 3:4 | 1024x1365 |

## 支持的模型

- sora_image
- gpt-4o-image-vip
- gemini-2.5-flash-image-preview
- gemini-3-pro-image-preview

*注意：实际可用的模型取决于你的 API 提供商*

## 技术实现说明

### 请求格式

服务器使用 OpenAI Chat Completions API 格式发送请求：

**无参考图片时：**
```json
{
  "model": "sora_image",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "一只可爱的小猫【1:1】"
    }
  ]
}
```

**有参考图片时：**
```json
{
  "model": "sora_image",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "将这张图片改成赛博朋克风格【3:4】"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image1.jpg"
          }
        }
      ]
    }
  ]
}
```

### 响应处理

服务器从 API 响应的 `choices[0].message.content` 中提取图片数据，支持以下格式：

1. **Markdown 格式图片链接**：`![image](url)`
   - 如果 url 是 data URL：`![image](data:image/png;base64,iVBORw0KGgo...)`
   - 如果 url 是 http URL：`![image](https://example.com/image.png)`
   - 如果 url 是纯 base64：`![image](iVBORw0KGgo...)`（自动添加前缀）

2. **完整的 data URL**：`data:image/png;base64,iVBORw0KGgo...`

3. **HTTP/HTTPS URL**：`https://example.com/image.png`

4. **纯 Base64 字符串**：`iVBORw0KGgo...`（自动添加前缀）

5. **对象格式**：`{"image_url": {"url": "data:image/png;base64,..."}}`

根据 `return_type` 参数决定：
- `base64`：直接返回提取的图片数据（base64 或 URL）
- `url`：
  - 如果图片数据是 http URL：直接返回该 URL
  - 如果图片数据是 base64：上传到 MinIO 并返回公开访问 URL

## 错误处理

服务器会处理以下错误情况：

- 缺少必需的环境变量
- API 密钥无效或耗尽
- 图片文件读取失败
- API 请求失败
- MinIO 上传失败（URL 模式）

错误信息会以 JSON 格式返回，包含详细的错误描述。

## 注意事项

1. **API 密钥轮询**：当配置多个 API 密钥时，服务器会自动轮询使用，避免单个密钥限流
2. **MinIO 配置**：如果选择 URL 返回模式，必须正确配置 MinIO，否则会失败
3. **参考图片**：参考图片必须是 URL 格式，支持 HTTP/HTTPS 协议
4. **超时设置**：API 请求超时时间为 6 分钟，大图生成可能需要更长时间
5. **存储桶管理**：服务器会自动创建配置的 MinIO 存储桶（如果不存在）

## 开发

```bash
# 安装依赖
npm install

# 运行开发服务器
npm start

# 测试
npm test
```

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！