面向 AstrBot 的通用图像生成插件，支持多供应商、文生图、图生图、LLM 工具调用、预设/人设、任务队列、限流、任务历史和安全审核。
兼容 Xero-Team/AstrBot >=4.27.3,<5，要求 Python >=3.14；目标 AstrBot 仓库的测试解释器为 Python 3.14.6。本插件使用当前公开插件 SDK 与 Dashboard Extension Protocol v1，不兼容旧版插件 Web API 或内部 Agent 接口。
- AstrBot：
>=4.27.3,<5。 - Python：
>=3.14（目标 AstrBot 仓库固定使用 3.14.6）。 - 插件运行时依赖：
aiohttp、Pillow、pydantic，版本约束见requirements.txt。AstrBot 会在加载插件时按该文件检查依赖。
- 从可信来源下载插件 ZIP，在 AstrBot WebUI 的“插件”页面上传并安装；安装后启用插件。
- 在插件配置页添加至少一个“图像模型供应商”，填写 API Key，并维护可用模型列表。
- 使用
/image（或/生图）测试生成。没有可用供应商或 API Key 时，插件会拒绝创建任务并提示原因。
源码开发可在 AstrBot 源码根目录执行：
uv run astrbot plug install --editable /absolute/path/to/astrbot_plugin_image_generation插件不依赖某个消息平台的私有接口：可在 AstrBot 支持命令和图片发送的消息平台中使用；图片发送能力仍由实际平台适配器决定。Dashboard 控制台需要通过 AstrBot WebUI 使用。
- 多供应商配置：一个插件中配置多个生图服务，每个供应商可独立设置 API Key、Base URL、代理、模型列表和模型能力。
- 多适配器支持：内置 Gemini、OpenAI Chat、OpenAI Images、火山方舟、Gitee AI、硅基流动、Agnes AI、Jimeng2API、Grok 和自定义 HTTP 接口。
- 文生图与图生图：自动收集消息图片、引用消息图片、@ 用户头像和人设参考图；模型不支持图生图时会自动忽略参考图。
- 模型动态切换：通过指令查看和切换模型。
- 多图任务：单个任务可生成多张图片，支持请求级并发、任务级队列和分批发送。
- LLM 工具调用：可作为 LLM 工具自动生图、查询预设/人设、管理生图任务，也可按配置启用预设编辑工具。
- 预设与人设：支持普通预设、高级 JSON 预设、多人设拼接和人设参考图。
- Dashboard 控制台：在 AstrBot Dashboard 中提交任务、选择模型/预设/人设、上传参考图、查看任务详情与下载生成结果。
- 使用限制：支持会话黑名单、管理员/白名单绕过、请求频率限制、每日额度和参考图大小限制。
- 安全审核：支持屏蔽词、AI 提示词审核、AI 图片审核和审核白名单。
- 插件间公共 API：其他插件可提交任务、查询状态、取消任务、等待结果并获取本地图片路径。
| 命令 | 说明 |
|---|---|
/image <预设/人设...> [额外提示词] --count <数量>（别名 /生图） |
生成图片。开头连续命中的预设/人设会依次应用；数量使用 Orbit option --count 或 -n 指定。消息、引用消息、@ 用户和人设参考图会作为参考图。 |
/image-task [编号或任务ID]（别名 /生图任务） |
查看当前会话的任务或详情。编号只匹配进行中的任务；完整任务 ID 可查看仍保留的已结束记录。 |
/image-cancel <编号或任务ID>（别名 /生图取消） |
取消当前会话中排队或运行中的任务。 |
/image-model [序号]（别名 /生图模型） |
查看或切换模型。 |
/image-preset（别名 /预设） |
查看预设和人设。 |
/image-preset 添加 <预设名:预设内容> |
添加或覆盖预设，支持英文冒号 : 和中文冒号 ：。 |
/image-preset 删除 <预设名> |
删除预设。 |
插件在元数据中注册了 Dashboard Extension Protocol v1 页面 dashboard（标题为“通用生图控制台”）。启用插件后，该页面可执行以下受限操作：
- 读取当前模型、队列状态、可用模型、预设和人设；
- 提交生图任务、查看任务列表/详情、取消进行中的任务；
- 逐张上传参考图（单次任务最多选用 8 张）、预览较小的结果图和下载完整结果图。
上传仅接受 JPEG、PNG、GIF、WebP、HEIC 或 HEIF 图片；除 AstrBot Dashboard 提供的受限 Action 外，页面不会直接访问 Dashboard API 或外部网络。控制台中的模型选择会写入插件当前模型设置，因此会影响该插件后续任务，而不是仅影响当前浏览器页面。
| 适配器类型 | 使用接口类型 | 文生图 | 图生图 | 尺寸控制 | 说明 |
|---|---|---|---|---|---|
gemini |
Gemini 原生 generateContent |
✅ | ✅ | ✅ | Gemini 原生图像生成接口。 |
openai_chat |
OpenAI 兼容 chat/completions |
✅ | ✅ | ❌ | 通用 Chat Completions 图像生成接口，可配置提示词前缀、输出模态和额外请求体。 |
openai |
OpenAI Images API /v1/images/generations、/v1/images/edits |
✅ | ✅ | ✅ | DALL-E / GPT Image 系列；图生图仅 GPT Image 系列支持。 |
volcengine_ark |
火山方舟 Images Generations /api/v3/images/generations |
✅ | ✅ | ✅ | Seedream 系列；按模型能力发送水印、提示词优化、组图与联网搜索（5.0 Pro 自动跳过不支持参数）。 |
gitee_ai |
Gitee AI /v1/images/generations、/v1/images/edits |
✅ | ✅ | ✅ | Gitee AI 通用图像接口，可自动或手动选择生成/编辑接口。 |
siliconflow_adapter |
SiliconFlow Images API /v1/images/generations |
✅ | ✅ | ✅ | 支持 Kolors、Qwen-Image、Qwen-Image-Edit、Z-Image，并可配置反向提示词、步数和提示词遵循强度。 |
agnes_ai |
Agnes AI Images API /v1/images/generations |
✅ | ✅ | ✅ | 支持 agnes-image-2.0-flash 和 agnes-image-2.1-flash；参考图通过 extra_body.image 数组发送。 |
jimeng2api |
jimeng-api /v1/images/generations、/v1/images/compositions |
✅ | ✅ | ✅ | 适用于 iptag/jimeng-api，支持启动和每日自动领积分任务。 |
grok |
xAI Images API /v1/images/generations、/v1/images/edits |
✅ | ✅ | ✅ | 按 xAI 官方 JSON 格式请求；单图用 image，多图用 images（最多 3 张）。 |
codex_responses |
Codex Responses API /codex/responses |
✅ | ✅ | ❌ | 固定请求 model、input 和 image_generation 工具；支持同步图像编辑。 |
modelscope |
ModelScope API-Inference /v1/images/generations + task poll |
✅ | 按配置 | 按配置 | 异步提交、轮询并下载结果；收到远端任务 ID 后不会自动重新提交；详见 ModelScope 接口配置。 |
custom_http |
用户自定义 HTTP JSON 接口 | ✅ | ✅ | ✅ | 高级接口模板，详见 自定义 HTTP 接口配置。 |
能力开关以“模型能力”配置为准。未勾选的能力不会在请求中使用，LLM 工具参数也会按当前适配器能力动态隐藏。
| 配置名 | 默认值 | 说明 |
|---|---|---|
| 启用 LLM 工具 | 生图工具、预设查询工具、生图任务工具 | 选择允许 LLM 调用的工具。可选项包括生图工具、预设查询工具、生图任务工具和预设编辑工具；预设编辑工具开启后 AI 可创建或删除预设。 |
每个供应商都包含以下通用配置，部分供应商会额外提供适配器专属配置项。
| 配置名 | 说明 |
|---|---|
| 供应商名称 | 供应商显示名，也是模型格式 供应商名称/模型名称 的前半部分。 |
| 接口地址 | 供应商接口地址。多数适配器可留默认值或填写中转地址。 |
| 代理地址 | HTTP 代理，例如 http://127.0.0.1:7890。 |
| API 密钥 | API Key 或 Token 列表；多个 Key 会自动轮询和重试。 |
| 可用模型列表 | /生图模型 中展示和切换的模型列表。 |
| 模型能力 | 按实际模型能力勾选文生图、图生图、宽高比、分辨率。 |
| 超时时间覆盖 | 单个供应商的超时时间；填 0 使用“运行控制”中的默认超时。 |
| 重试次数覆盖 | 单个供应商的重试次数；填 0 使用“运行控制”中的默认重试次数。 |
常见专属配置：
openai_chat：可配置提示词前缀、modalities和额外请求体 JSON。openai：可选择模型系列，auto会按模型名识别 GPT Image 或 DALL-E 请求格式。volcengine_ark：可配置水印、组图模式、最大参考图数量、提示词优化模式和联网搜索；Seedream 5.0 Pro 会自动跳过组图与联网搜索参数，并将参考图上限限制为 10。gitee_ai：可通过图像接口模式自动或手动选择generations/edits。siliconflow_adapter：可配置反向提示词、推理步数和提示词遵循强度。agnes_ai：可选择base64或url响应格式；图生图参考图通过extra_body.image数组发送。codex_responses：固定向POST /codex/responses发送model、input与tools: [{"type":"image_generation","output_format":"png"}]；填写服务根地址后会自动拼接路径，使用 Bearer API Key。无参考图时发送文本input，有参考图时发送多模态 Responsesinput，仅支持同步结果；详见 Codex Responses 接口配置。modelscope：调用 API-Inference 异步图像接口，使用 ModelScope Access Token 提交、轮询并下载结果；可配置轮询间隔、总等待时间、反向提示词和尺寸映射。默认模板仅启用文生图；需要模型明确支持后才启用图生图。收到task_id后不会通过外层重试重新提交任务；详见 ModelScope 接口配置。custom_http：可配置请求方法、请求头、查询参数、请求体、图片结果路径、结果类型、错误路径和成功状态码。
| 配置名 | 默认值 | 说明 |
|---|---|---|
| 生图模型 | 自动选择首个可用模型 | 当前使用的模型，可通过 /生图模型 更新。 |
| 默认出图数量 | 1 | 未通过指令的 --count / -n option 或 LLM 工具指定数量时，单个生图任务默认生成的图片数量。 |
| 单次最大出图数量 | 10 | 单个生图任务最多生成的图片数量；用户请求超过该值时会自动截断。 |
| 单条消息最多图片数 | 5 | 多张图片发送给用户时，每条消息最多携带的图片数量；结果信息附加在最后一批。 |
| 默认图片宽高比 | 不指定 | 可选不指定、1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9；不指定时请求中不携带比例字段。 |
| 默认分辨率 | 不指定 | 可选不指定、1K、2K、4K；不指定时请求中不携带分辨率字段，仅部分适配器支持。 |
| 显示结果信息 | 用量 | 发送图片后可附加耗时、模型、生成数量、用量和任务ID；用量仅在开启每日额度时显示。 |
| 开始生图任务提示模板 | 已开始生图任务 | 生图开始时发送的提示文本；留空则不发送，默认包含任务 ID。 |
开始生图任务提示模板支持这些占位符：{reference_image_count}、{image_count}、{count}、{prompt}、{preset}、{presets}、{persona}、{personas}、{aspect_ratio}、{resolution}、{task_id}、{model}、{mode}、{reference_images_block}、{image_count_block}、{count_block}、{preset_block}、{persona_block}。其中 {preset}/{presets} 仅表示命中的预设，{persona}/{personas} 仅表示命中的人设。
当同时使用人设、预设和附加提示词时，插件会将最终提示词整理为轻量分块，例如 [人物设定]、[预设提示词]、[附加提示词]，帮助模型区分不同来源的意图；只有单一来源时会保留原始文本。
| 配置名 | 默认值 | 说明 |
|---|---|---|
| 超时时间 | 180 秒 | 单次模型请求的默认超时时间；供应商配置可单独覆盖。 |
| 重试次数 | 3 | 单次模型请求失败后的默认重试次数；供应商配置可单独覆盖。 |
| 打印调试请求日志 | 关闭 | 开启后以 debug 日志打印 JSON 请求/响应结构；长字符串、Base64 和 data URL 会摘要处理。 |
| 向用户显示详细错误信息 | 关闭 | 开启后，生图失败消息会包含经过脱敏和摘要处理的远端错误详情；关闭时只显示错误类型和状态码。 |
| 不可重试 HTTP 状态码 | 内置 | 命中这些状态码时会立即失败，例如参数错误、鉴权失败、权限不足或资源不存在。 |
| 不可重试错误关键词 | 内置 | 错误文本包含这些关键词时会立即失败，用于识别参数错误、模型不支持或内容安全拒绝。 |
| 最大并发生图请求数 | 3 | 同时调用图像模型接口的请求数量上限；多图任务会在该限制内并发请求，完成一个后继续补发剩余请求。 |
| 最大并发完整生图任务数 | 3 | 同时运行的完整生图任务数量上限；每个运行中任务内部仍受请求级并发限制控制。 |
| 最大排队生图任务数 | 20 | 尚未开始运行的完整生图任务队列上限，不包含运行中任务；队列满时会拒绝新任务。 |
| 配置名 | 默认值 | 说明 |
|---|---|---|
| 持久化生图任务历史 | 开启 | 将任务状态、会话标识、提示词摘要、结果路径和错误摘要保存到插件数据目录；关闭后仅保留运行期内存任务。 |
| 生图任务历史保留条数 | 1000 | 最多保留的生图任务记录数量；活跃任务不会因历史裁剪被删除。 |
| 生图任务历史保留天数 | 0 | 已结束任务超过该天数会被清理；0 表示不按时间清理，仅按条数限制。 |
| 配置名 | 默认值 | 说明 |
|---|---|---|
| 会话 UMO 黑名单 | 空 | 命中的会话无法使用指令和 LLM 工具。 |
| 管理员无视使用限制 | 开启 | AstrBot 管理员跳过会话黑名单、频率限制和每日额度，但仍记录每日用量；成功提示中显示为 n/∞。 |
| 使用限制白名单 UMO | 空 | 额外配置可跳过使用限制的会话 UMO，行为同管理员绕过。 |
| 黑名单拒绝提示 | ❌ 当前会话已被加入黑名单，无法使用生图功能 | 黑名单命中时返回的文本，留空则不提示。 |
| 速率限制 | 0 秒 | 同一用户两次请求之间的最小间隔；0 表示不限。 |
| 最大参考图大小 | 10 MB | 超过限制的参考图会被忽略。 |
| 启用每日额度 | 关闭 | 是否限制每日生成数量。 |
| 每日额度 | 10 | 开启每日额度后，每个会话每天可生成的最大图片数量。 |
| 配置名 | 说明 |
|---|---|
| 审核白名单 UMO | 命中的会话会跳过提示词和图片审核。 |
| 屏蔽词列表 | 提示词包含任一词时直接拒绝生图请求。 |
| 启用 AI 提示词审核 | 生图前调用对话模型审核提示词。 |
| AI 审核模型 | 指定提示词或图片审核使用的对话模型；留空时使用当前会话模型。 |
| 审核模型重试次数 | 审核模型调用失败、返回为空或无法解析时的最大尝试次数。 |
| AI 提示词审核提示词 | 提示词审核模板，支持 {prompt} 占位符，未包含时会自动附加用户提示词。 |
| 启用 AI 图片审核 | 生图后、发送前调用对话模型审核生成图片。 |
| AI 图片审核提示词 | 图片审核模板；只有显式写入 {prompt} 时才附带生图提示词。 |
预设提示词和人设模板在同一个配置组中维护。
| 配置名 | 说明 |
|---|---|
| 预设提示词 | 预定义提示词模板，可通过 /预设 命令增删。 |
| 人设名称 | 用于 /生图 <人设名称...> [额外提示词] 匹配。 |
| 人设文本描述 | 使用该人设生图时会作为人物设定提示词。 |
| 人设参考图 | 可选；当前模型支持图生图时会自动作为参考图。 |
简单预设格式：名称:提示词。
高级预设格式：名称:{"prompt":"提示词","aspect_ratio":"16:9","resolution":"2K","description":"描述"}。
/image-preset（或别名 /预设）会同时展示预设和人设。预设与人设同名时，/image 优先使用预设。/image 会从提示词开头按空格连续解析多个预设或人设，遇到第一个未命中的词后，剩余内容作为额外提示词；生成数量使用 --count / -n 指定。
| 工具名 | 配置项名称 | 说明 |
|---|---|---|
generate_image |
生图工具 | 根据提示词、预设、人设、参考图、头像引用和生成数量提交生图任务。 |
query_image_presets |
预设查询工具 | 查询预设或人设列表，也可查看指定预设/人设详情。 |
manage_image_tasks |
生图任务工具 | 查看当前会话任务列表、查看任务详情、取消仍在进行的任务。 |
edit_image_presets |
预设编辑工具 | 创建或删除预设；默认不启用，开启后 AI 可修改预设配置，但不会编辑人设。 |
LLM 生图工具支持 preset、persona、aspect_ratio、resolution、image_count、avatar_references 和 reference_images 参数。avatar_references 可填写 self、sender 或用户 ID；reference_images 支持网络图片 URL 与插件私有数据目录中的文件。
/生图指令、LLM 生图工具和公共 API 共用统一任务体系：任务提交后会生成task_id，进入排队/运行/完成/失败/取消状态。- 完整任务级并发由“最大并发完整生图任务数”控制，超过后任务保持排队，不会开始参考图转换或模型调用。
- 模型接口请求级并发仍由“最大并发生图请求数”控制，多图任务会在请求并发限制内发起多个子请求，完成一个后继续补发剩余请求。
- 插件会在收集参考图和预约额度前预检查队列容量；队列满时会直接拒绝新任务，避免不必要的下载和图片处理。
requested_count表示模型接口子请求数量，不保证等于最终图片数量；result_count表示实际保存的结果图片数量。部分适配器单次子请求可能返回多张图片。- 生成多张图片时会按“单条消息最多图片数”自动分批发送，结果信息附加在最后一批。
/生图任务只展示当前会话正在进行的任务，并为列表项添加编号；可通过/生图任务 <编号或任务ID>查看详情，通过/生图取消 <编号或任务ID>取消仍在排队或运行中的任务。- 取消排队任务后会立即更新用户可见状态并释放占用；底层队列项由 worker 后续惰性跳过，不会开始参考图转换或模型调用。
- 历史任务元数据可持久化到插件数据目录，插件重载后最近的已结束任务仍可查询；重启前未完成的任务会恢复为已取消，不会继续执行。
- 历史记录中的
result_paths只是当时保存的图片路径，临时文件可能已被 AstrBot 清理，调用方需要容忍路径不存在。
基础生图：
/生图 一只在森林里野餐的兔子
使用预设：
/预设 添加 赛博朋克:cyberpunk style, neon lights, futuristic city
/生图 赛博朋克 猫
使用人设：
/生图 看板娘 在咖啡店读书
组合多个预设/人设：
/生图 手办化 看板娘 夜景 微笑
一次生成多张：
/image 手办化 看板娘 夜景 微笑 --count 3
图生图：
发送或引用一张图片后输入：/生图 变成动漫风格
/生图 变成像素风 @用户A
切换模型：
/生图模型
/生图模型 2
查看或取消任务：
/生图任务
/生图任务 1
/生图任务 1a2b3c4d
/生图取消 1
/生图取消 1a2b3c4d
本插件提供 plugin.public_api 供其他 AstrBot 插件复用生图能力。公共 API 复用本插件的任务、审核、参考图处理和结果保存流程，但不会主动向用户发送图片；调用方通过任务 ID 或等待接口获取生成图片的本地路径。
| 接口 | 说明 |
|---|---|
submit_generation_task(...) |
提交后台任务，立即返回任务 ID。 |
get_generation_task(task_id) |
查询任务快照。 |
cancel_generation_task(task_id, *, unified_msg_origin=None) |
取消任务。 |
wait_generation_result(task_id, *, timeout_seconds=None, poll_interval_seconds=0.5) |
等待任务结束并返回图片路径。 |
generate_image_files(...) |
提交任务并等待完成的快捷方法。 |
详细接口参数、返回对象和调用示例见：插件间公共 API 文档。
- 火山方舟的可用模型列表需要按控制台实际 Model ID 或 Endpoint ID 配置。
- 配置
jimeng2api后，插件会在启动时和每天日期变更后自动领取积分；仅直接连接即梦逆向服务时有效。 - 即梦逆向图生图使用
/v1/images/compositions，使用中转可能会导致图生图失败。 - Codex Responses 接口支持在单次 HTTP 请求内返回最终图片的文生图和图生图；参考图会作为多模态
input_imagedata URL 发送，但宽高比和分辨率会被忽略。若日志在约 150 秒显示Server disconnected、后续任务仍成功，通常是服务端或中间网络主动断开后触发了插件重试，而不是本插件的请求超时；详见 Codex Responses 接口配置。 - 自定义 HTTP 接口为高级功能，建议先阅读 自定义 HTTP 接口配置。
- 开启调试请求日志或详细错误信息时，插件会做脱敏和摘要处理，但仍建议避免在公共环境暴露日志。
开发与验证应使用 Xero-Team/AstrBot 源码根目录及其 Python 3.14.6 工具链。插件只依赖 astrbot.api 提供的公开接口；修改 Dashboard 前端资源后，需要同步更新 pages/dashboard/assets.v1.json 中的文件大小和 SHA-256 摘要。
安装质量工具后，可使用与 AstrBot 一致的 Python 3.14 / Ruff 规则运行：
python -m pip install -r requirements-dev.txt
make format # 自动格式化并修复安全的 Ruff 问题
make check # 格式、Ruff、编译、测试、配置与 Dashboard 资源检查
make quality # check + Bandit、依赖审计、复杂度门禁如本机有目标 AstrBot 源码，还可运行完整插件契约检查：
make check-contract ASTRBOT_ROOT=/path/to/AstrBot真实消息平台、模型服务和 Dashboard 页面仍应在对应环境中手动验证。