koishi-plugin-ai-image

项目介绍 (Project Introduction)

中文

一款为 Koishi 聊天机器人框架开发的 AI 绘图插件，支持文生图 + 图生图，兼容 OpenAI 标准接口的同时支持自定义 API 端点，可接入任意图像生成服务。
内置多 API 负载均衡、图片压缩、Base64 自动转换、预置提示词、主/副模型分离、端口自动适配、调试日志、超时等待机制，配置灵活、开箱即用、稳定可靠。
图生图支持同时发送多张参考图片，并可自定义最大图片数量。
提供黑名单管理功能，数据持久化到数据库，管理员可通过指令添加、移除用户及查看黑名单。

English

An AI image generation plugin for the Koishi chatbot framework, supporting text-to-image & image-to-image.
Compatible with OpenAI‑standard APIs, and also supports custom API endpoints for any image generation service.
Built‑in multi‑API load balancing, image compression, automatic Base64 conversion, preset prompts, primary/secondary model separation, port auto-detection, debug logging, and timeout mechanism.
Image‑to‑image supports multiple reference images with configurable maximum count.
Blacklist management with database persistence.

核心指令 (Core Commands)

| 指令 (Command) | 说明 (Description) | 示例 (Example) | |----------------|--------------------|----------------| | draw <提示词> | 进入收集模式：可发送文字/图片，输入「开始」生成，「取消」退出。支持 -p <预设> 直接应用预置提示词模板。 (Enter collection mode: send text/images, then "start" to generate. Use -p <preset> to apply a preset prompt template.) | draw 一只猫 -p 动漫风格 | | draw2 <提示词> | 使用副模型进入收集模式，操作同 draw。 (Same as draw but using the secondary model.) | draw2 一只猫 | | redraw / rd / 重绘 | 重绘上一次的文生图结果。 (Redraw the last text-to-image result.) | redraw | | blacklist list | 查看当前黑名单（仅管理员）。 (Show current blacklist, admin only.) | blacklist list | | blacklist add <QQ号...> | 将指定 QQ 号加入黑名单（仅管理员）。 (Add QQ numbers to blacklist, admin only.) | blacklist add 123456 | | blacklist remove <QQ号...> | 将指定 QQ 号移出黑名单（仅管理员）。 (Remove QQ numbers from blacklist, admin only.) | blacklist remove 123456 |

配置项说明 (Configuration)

基本设置 (Basic Settings)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | debug | boolean | false | 调试模式，输出完整请求/响应日志 (Debug mode, logs full request/response) | | timeout | number | 300000 | API 请求超时时间（毫秒） (Request timeout in ms) | | rateLimit | number | 200 | 每小时调用次数上限 (Hourly call limit) | | collectTimeout | number | 120 | 收集模式等待用户输入的超时秒数 (Collection mode wait timeout in seconds) | | defaultImageSize | string | 1024x1024 | 全局默认图片尺寸（宽x高） (Global default image size WxH) | | maxImages | number | 5 | 图生图最大支持图片数量 (Max reference images) | | imageSendMode | string | image | 图片发送方式：image（仅图片） / url（仅链接） / both（图片+链接） (Send mode: image, url, both) | | enableForward | boolean | true | 多图结果是否使用合并转发 (Use forward message for multiple images) | | enableTxt2Img | boolean | true | 启用文生图功能 (Enable txt2img) | | enableImg2Img | boolean | true | 启用图生图功能 (Enable img2img) | | defaultResponseImageFormat | string | url | 全局默认图片数据格式：url（直链） / pure_base64（Base64） (Global default image format: url, pure_base64) |

扩展功能 (Extended Features)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | imageCompression.enable | boolean | false | 启用图片压缩（需安装 sharp 模块） (Enable image compression, requires sharp) | | imageCompression.maxWidth | number | 1024 | 压缩后最大宽度 (Max width after compression) | | imageCompression.maxHeight | number | 1024 | 压缩后最大高度 (Max height after compression) | | imageCompression.quality | number | 80 | JPEG 压缩质量 0-100 (JPEG quality 0-100) | | imageInputAsBase64 | boolean | false | 图生图时将参考图片转为 Base64 发送 (Convert reference images to Base64 for img2img) | | presetPrompts | array | [] | 预置提示词列表，每项包含 name（名称）、keywords（触发关键词数组）、template（提示词模板，支持 {prompt} {keyword} 变量） (List of preset prompts: name, keywords array, template with {prompt} and {keyword} variables) |

主模型设置 (Primary Model)

主模型始终使用自定义 API 列表，支持多个端点与负载均衡。
The primary model always uses a custom API list with multiple endpoints and load balancing.

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | apiStrategy | string | roundrobin | 主模型调度策略：sequence（顺序） / roundrobin（轮询） (Load balancing strategy for primary model) | | primaryApiList | array | [] | 主模型 API 条目列表，每个条目包含以下配置 (List of primary API entries, each with the following fields) |

API 条目公共配置 (API Entry Common Fields)（主模型与副模型通用）

| 字段 (Field) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |--------------|-------------|-------------------|---------------------| | enable | boolean | true | 是否启用此 API (Enable this API) | | adapterType | string | (空) | 接口类型：chat / flat；留空则根据端口自动判断（7860/5000/8888 → flat，其余 → chat） (Adapter type; auto-detect by port if empty) | | endpoint | string | https://api.openai.com/v1/chat/completions | API 端点 (Endpoint) | | apiKey | string | (空) | API 密钥 (API key) | | model | string | gpt-image-2 | 模型名称 (Model name) | | img2imgModel | string | (空) | 图生图专用模型 (Img2img model) | | imageSize | string | (空) | 图片尺寸，留空使用全局默认 (Image size, falls back to global default) | | responseImageFormat | string | (空) | 图片数据格式，留空跟随全局 (Image format, falls back to global) | | txt2imgPrompt | string | (空) | 文生图提示词模板 (Prompt template for txt2img) | | img2imgPrompt | string | (空) | 图生图提示词模板 (Prompt template for img2img) | | customHeaders | string | 预设 (Preset) | 自定义请求头 JSON，支持 {apiKey} 变量 (Custom headers JSON) | | bodyTemplate | string | 预设 (Preset) | 自定义请求体 JSON，包含 txt2imgBody、img2imgBody、responseImagePath 等字段 (Custom request body template JSON) |

副模型设置 (Secondary Model)

副模型通过 draw2 指令调用，其 API 列表完全独立于主模型；若副模型列表为空，则自动回退到主模型的 primaryApiList。
The secondary model is invoked via the draw2 command. Its API list is completely independent; if empty, it falls back to the primary primaryApiList.

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | secondaryApi.enable | boolean | false | 启用副模型功能 (Enable secondary model) | | secondaryApi.strategy | string | roundrobin | 副模型调度策略：sequence / roundrobin (Load balancing strategy for secondary model) | | secondaryApi.list | array | [] | 副模型 API 条目列表，结构与主模型条目完全相同（留空则使用主模型列表） (Secondary API entry list, same structure as primary entries; if empty, uses primary list) |

副模型列表的每个条目配置项与主模型 API 条目完全一致，详见上方 API 条目公共配置 表格。
Each entry in the secondary list has the same fields as a primary API entry; see the API Entry Common Fields table above.

代理设置 (Proxy Settings)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | proxyEnabled | boolean | false | 启用 HTTP/HTTPS 代理 (Enable proxy) | | proxyProtocol | string | http | 代理协议：http / https (Proxy protocol) | | proxyHost | string | (空) | 代理地址 (Proxy host) | | proxyPort | number | 8080 | 代理端口 (Proxy port) | | proxyAuth | boolean | false | 代理是否需要认证 (Proxy requires auth) | | proxyUsername | string | (空) | 代理用户名 (Proxy username) | | proxyPassword | string | (空) | 代理密码 (Proxy password) |

权限管理 (Permissions)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | blacklistAdmins | array | [] | 黑名单管理员 QQ 号列表 (Admin QQ number list) |

消息文本 (Messages)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | messages.* | object | 见配置页 (See schema) | 所有提示文案均可自定义，支持模板变量 (All messages customizable, supports template variables) |

功能特性 (Features)

• 文生图 / 图生图，支持同时上传多张参考图片 (Txt2img & img2img, multiple reference images)
• 多图合并转发 / 单图发送灵活切换 (Flexible multi-image sending: forward or single)
• 主/副模型独立，均可配置多端点负载均衡（顺序 / 轮询）(Independent primary & secondary models, each with multi-endpoint load balancing)
• 预置提示词模板，关键词自动匹配 (Preset prompts with keyword auto-matching)
• 图片压缩与 Base64 输入转换，兼容更多后端 (Image compression & Base64 conversion)
• 端口自动适配（7860/5000/8888 → flat 格式）(Port auto-detect for adapter type)
• 响应图片支持 URL / Base64 自动转换 (Auto conversion between URL and Base64)
• 黑名单管理（持久化到数据库）(Blacklist with database persistence)
• 全配置化提示文案，调试日志，超时控制，频率限制 (Fully configurable messages, debug log, timeout, rate limit)

依赖 (Dependencies)

• 数据库 (database)：必须启用，用于黑名单持久化。 (Required for blacklist persistence)
• 图生图 (img2img)：需要 assets 服务及正确的 selfUrl 配置。 (Requires assets service and correct selfUrl)
• 图片压缩 (optional)：需要安装 sharp 模块。 (Optional: sharp module for compression)

自定义 API 端点示例 (Custom Endpoint Examples)

DALL-E 风格 API（图片 URL 数组）

{
  "endpoint": "https://api.agnes-ai.com/v1/images/generations",
  "apiKey": "sk-xxxx",
  "headers": {"Authorization":"Bearer {apiKey}","Content-Type":"application/json"},
  "txt2imgBody": "{\"model\":\"{model}\",\"prompt\":\"{prompt}\",\"size\":\"{size}\"}",
  "img2imgBody": "{\"model\":\"{model}\",\"prompt\":\"{prompt}\",\"size\":\"{size}\",\"extra_body\":{\"image\":{{image_urls}},\"response_format\":\"url\"}}",
  "responseImagePath": "data.0.url",
  "responseImageFormat": "url"
}

### OpenAI Chat Completions（图片对象列表）
```json
{
  "endpoint": "https://api.openai.com/v1/chat/completions",
  "apiKey": "sk-xxxx",
  "headers": {"Authorization":"Bearer {apiKey}","Content-Type":"application/json"},
  "txt2imgBody": "{\"model\":\"{model}\",\"messages\":[{\"role\":\"user\",\"content\":\"{prompt}\"}]}",
  "img2imgBody": "{\"model\":\"{model}\",\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"{prompt}\"},{{image_objects}}]}]}",
  "responseImagePath": "choices.0.message.content",
  "responseImageFormat": "url"
}

项目贡献者 (Contributors)

| 贡献者 (Contributor) | 贡献内容 (Contribution) | | --- | --- | | Minecraft-1314 | 插件完整开发 (Complete plugin development) | | Stalker-404 | 插件功能建议-base64格式传递参考图片-已添加 (Suggestion - Base64 input for reference images - adopted) | | xiaochuqiangda | 参考了 koishi-plugin-imagedraw-selfuse 插件的功能 (This feature references the koishi-plugin-imagedraw-selfuse plugin) | | （欢迎提交 PR / Issues 加入贡献者列表） | | (Welcome to join the contributor list via PR or Issues) |

许可协议 (License)

本项目采用 MIT 许可证，详情参见 LICENSE 文件。

This project is licensed under the MIT License, see the LICENSE file for details.

支持我们 (Support Us)

如果这个项目对您有帮助，欢迎点亮右上角的 Star 支持我们，这将是对所有贡献者最大的鼓励！

If this project is helpful to you, please feel free to star it in the upper right corner to support us, which will be the greatest encouragement to all contributors!

问题反馈 (Feedback)

如有问题或建议，可通过 Issues 提交反馈。

If you have any questions or suggestions, please submit feedback via Issues.