@hamaster/openai-image-gen-server

v1.0.3

Published

a month ago

OpenAI Compatible Image Generation MCP Server - 提供图片生成工具，兼容OpenAI API结构

0High
0Medium
0Low

hamaster

mcp openai image-generation sora_image,gemini-2.5-flash-image-preview

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 支持，自动管理图片存储

安装

npm install @hamaster/openai-image-gen-server

或者直接从源码安装：

cd openai-image-gen-server
npm install

配置

创建 .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. 本地运行

npm start

2. 在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加：

{
  "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 |

示例：

基础文本生成：

{
  "prompt": "一只可爱的小猫坐在花园里，阳光明媚",
  "ratio": "1:1",
  "return_type": "base64"
}

使用参考图片（URL）：

{
  "prompt": "将这张图片改成赛博朋克风格",
  "images": ["https://example.com/image1.jpg", "https://example.com/image2.png"],
  "ratio": "3:4",
  "return_type": "url"
}

指定模型：

{
  "prompt": "一个未来主义的城市景观",
  "model": "gpt-4o-image-vip",
  "ratio": "2:3",
  "return_type": "url"
}

返回格式：

Base64 返回：

{
  "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 返回：

{
  "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 格式发送请求：

无参考图片时：

{
  "model": "sora_image",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "一只可爱的小猫【1:1】"
    }
  ]
}

有参考图片时：

{
  "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 中提取图片数据，支持以下格式：

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...)（自动添加前缀）
完整的 data URL：data:image/png;base64,iVBORw0KGgo...
HTTP/HTTPS URL：https://example.com/image.png
纯 Base64 字符串：iVBORw0KGgo...（自动添加前缀）
对象格式：{"image_url": {"url": "data:image/png;base64,..."}}

根据 return_type 参数决定：

base64：直接返回提取的图片数据（base64 或 URL）
url：
- 如果图片数据是 http URL：直接返回该 URL
- 如果图片数据是 base64：上传到 MinIO 并返回公开访问 URL

错误处理

服务器会处理以下错误情况：

缺少必需的环境变量
API 密钥无效或耗尽
图片文件读取失败
API 请求失败
MinIO 上传失败（URL 模式）

错误信息会以 JSON 格式返回，包含详细的错误描述。

注意事项

API 密钥轮询：当配置多个 API 密钥时，服务器会自动轮询使用，避免单个密钥限流
MinIO 配置：如果选择 URL 返回模式，必须正确配置 MinIO，否则会失败
参考图片：参考图片必须是 URL 格式，支持 HTTP/HTTPS 协议
超时设置：API 请求超时时间为 6 分钟，大图生成可能需要更长时间
存储桶管理：服务器会自动创建配置的 MinIO 存储桶（如果不存在）

开发

# 安装依赖
npm install

# 运行开发服务器
npm start

# 测试
npm test

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！