图片生成插件 (astrbot_plugin_free_image)

astrbot_plugin_free_image 是一个强大的面向 AstrBot 的图片生成插件，支持文生图、图生图、预设模板生图、LLM 函数工具调用、多模型回退、配额管理和 QQ 场景下的便捷交互。

插件的核心特色是“API 管线”：你可以在 WebUI 中配置多个图片生成节点，插件会按顺序调用，当前节点失败时自动回退到下一个节点。另外，插件内置了逆向 API，支持调用“大香蕉”无限次免费生成不带显式 Gemini 水印的 1K、2K、4K 图片。

主要特性

能力	说明
文生图	使用 #文生图 <描述> 直接生成图片。
图生图	支持直接发送图片、引用图片、@用户头像、默认使用发送者 QQ 头像作为参考图。
预设模板	通过 prompt_list 配置模板触发词，例如“手办化”“真人化”等。
多图输入	图生图最多读取 5 张参考图，传给 Provider 的张数由具体 Provider 能力决定。
动图处理	GIF/WebP 等动图会自动提取第一帧作为参考图。
多模型回退	api_pipeline 从上到下调度，成功即停止，失败自动尝试下一个节点。
Key 轮换	每个 Provider 节点可配置多个 api_keys，运行时自动 Round-robin 使用。
退避重试	对 429、资源耗尽、网络波动等错误进行重试和退避。
权限配额	支持管理员免限制、用户/群黑白名单、用户/群每日额度、永久次数和签到奖励。
LLM 工具	注册 image_generation 工具，允许模型在对话中主动调用生图能力。
QQ 优化	群聊简洁模式可贴 OK 表情，成功后只发送图片；也支持引用回复和多图分条策略。

安装与配置

1. 将本仓库放入 AstrBot 插件目录并启用插件。
2. 安装依赖：本仓库已在 requirements.txt 声明 curl_cffi。
3. 在 AstrBot WebUI 中配置 api_pipeline，至少添加一个已启用的图片生成节点。
4. 如果节点需要 API Key，请在对应 api_pipeline 节点的 api_keys 中填写。聊天命令不再提供 Key 增删查功能。

常用配置项：

配置项	说明
api_pipeline	图片生成 Provider 管线，决定模型、API 地址、Key、代理、超时和重试。
prefix	是否要求命令带前缀或 @机器人 唤醒，推荐开启。
prompt_list	预设模板列表，格式为 触发词:提示词。
concise_mode	QQ 群聊简洁模式：收到请求贴 OK 表情，成功后只发结果。
quote_reply_mode	控制生成成功后的图片消息是否引用回复。
multi_image_send_mode	控制多图结果是否合并发送或分条发送。
download_timeout	下载用户图片、头像或远程结果图片的超时时间。
rate_limit_seconds	非管理员全局生图冷却时间。
llm_tool_description	LLM 看到的工具描述。
llm_prompt_description	LLM 构造最终生图 Prompt 时参考的描述。

用户命令

命令	用途	示例
#文生图 <描述>	根据文字生成图片。	#文生图 一位在霓虹灯下的赛博朋克少女
#图生图 <描述>	根据图片和文字修改/重绘图片。	发送或引用图片后输入 #图生图 改成油画风格
#画图帮助	查看已加载的模板触发词。	#画图帮助
#画图帮助 <模板名>	查看某个模板的完整提示词。	#画图帮助 手办化
#画图签到	签到领取个人永久次数，需开启签到功能。	#画图签到
#画图查询次数	查询自己的个人剩余次数和当前群共享次数。	#画图查询次数
<模板名>	使用预设模板做图生图。	发送图片后输入 手办化

图生图输入优先级：

1. 引用消息中的图片
2. 当前消息中的图片
3. 当前消息中 @ 的 QQ 用户头像
4. 发送者自己的 QQ 头像

如果你开启了 prefix=true，模板触发也需要命令前缀或 @机器人 唤醒，避免日常聊天误触。

管理员命令

管理员指 AstrBot 全局管理员，名单来自 AstrBot 全局配置 admins_id。

命令	用途	示例
#画图添加模板	新增模板，若预设指令已存在则取消添加。	#画图添加模板 姿势表:为这幅图创建一个姿势表
#画图模型	查看当前 API 管线顺序和启用状态。	#画图模型
#画图模型 置顶 <序号>	将指定节点置顶。	#画图模型 置顶 3
#画图模型 开启 <序号>	启用指定节点。	#画图模型 开启 2
#画图模型 关闭 <序号>	关闭指定节点。	#画图模型 关闭 2
#画图简洁模式 开启/关闭	切换简洁模式，等效于 WebUI 的 concise_mode 开关。	#画图简洁模式 开启
#画图增加用户次数	给用户增加永久次数，支持 @ 或 QQ 号。	#画图增加用户次数 @某人 10
#画图增加群组次数	给群组增加永久次数。	#画图增加群组次数 987654 50
#画图查询次数 @用户	管理员查询指定用户次数。	#画图查询次数 @某人

API Key 请统一在 AstrBot WebUI 的 api_pipeline 节点中配置和管理。

输出行为

普通模式：

1. 收到请求后先回复“正在生成”。
2. 成功后发送图片，并附带耗时、剩余次数、命中模型等信息。
3. 失败后返回聚合错误信息，便于判断是哪一个 Provider 失败。

简洁模式：

1. 仅 QQ 群聊生效，私聊仍按普通模式处理。
2. 收到请求时尝试给原消息贴 OK 表情，不主动发“正在生成”。
3. 成功后只发图片或视频组件，不附带说明文字。
4. 失败仍会发送失败原因；当全部 API 均失败时，仅返回简短失败提示，避免刷屏。

发送策略由以下配置控制：

配置项	可选值
quote_reply_mode	始终引用回复、始终单独发送、命令引用回复，函数调用单独发送、命令单独发送，函数调用引用回复
multi_image_send_mode	始终不分条、始终分条、群聊不分条，私聊分条、群聊分条，私聊不分条

Provider 支持

template_key	需要 API Key	能力与备注
vertex_ai_anonymous	否	Vertex AI 匿名逆向接口，依赖 curl_cffi，内置 reCAPTCHA、浏览器指纹轮换和会话老化。
gemini	是	Gemini 原生 API，支持多模态输入、Gemini 3 图片清晰度配置和可选 Google Search。
openai_images	是	OpenAI Images API；无参考图走 /generations，有参考图走 /edits。
openai_responses	是	兼容 /v1/responses，通过 image_generation tool 解析图片结果。
openai_compat_chat	是	兼容 /v1/chat/completions，可解析 URL、Markdown 图片、data URI、JSON、SSE 和视频 URL。
siliconflow	是	通用 /images/generations 实现，支持远程 URL 或 base64 图片结果。
bigmodel	是	通用 /images/generations 实现，支持远程 URL 或 base64 图片结果。

Provider 行为说明：

1. 所有需要 Key 的 Provider 都通过 api_keys 自动轮换。
2. 429、quota、rate limit、resource exhausted 会触发资源限制退避。
3. 普通网络错误会触发 3-5 秒随机退避。
4. openai_compat_chat 若解析到视频 URL，会用 AstrBot Video.fromURL 发送；如果端点返回 base64 视频数据，插件会提示当前不支持直接发送内嵌视频。

权限、配额与签到

项	行为
管理员	不受黑白名单、次数、冷却限制，剩余次数显示为 ∞。
用户黑名单	优先级最高，命中后静默拒绝。
群黑名单	优先级最高，命中后静默拒绝。
用户白名单	非空时只允许名单内用户使用，管理员除外。
群白名单	非空时只允许名单内群使用。
用户次数	用户总次数 = 永久次数 + 今日剩余固定额度。
群组次数	群总次数 = 永久次数 + 今日剩余固定额度。
扣费顺序	同时启用用户和群限制时，优先扣群次数，群次数不足再扣用户次数。
签到奖励	只增加用户永久次数，不直接写入每日额度。
冷却限制	全局冷却，任何非管理员触发都会刷新冷却时间。

LLM 函数工具

插件会注册一个 LLM 工具：image_generation。

参数	说明
prompt	LLM 根据用户上下文改写后的最终生图提示词。

工具调用规则：

1. 当前消息或引用消息中含图片时，按图生图处理。
2. 没有图片组件时，按文生图处理。
3. LLM 工具入口不会把 @用户头像当作图生图输入，因为它只检查 Image 和 Reply(Image) 组件。
4. 工具被调用后，插件会创建后台任务发送结果，并 stop_event()，避免 LLM 继续输出导致超时。

持久化数据

插件使用 StarTools.get_data_dir() 获取数据目录，并保存以下 JSON 文件：

文件	用途
user_counts.json	用户永久次数。
group_counts.json	群组永久次数。
user_daily_counts.json	用户每日额度使用情况。
group_daily_counts.json	群组每日额度使用情况。
user_checkin.json	用户签到日期记录。

常见问题

提示“API 管线为空或无已启用的提供商”

请在 WebUI 的 api_pipeline 中添加至少一个节点，并确认该节点 enabled=true。

Vertex AI 匿名节点提示缺少 curl_cffi

该节点依赖 curl_cffi 模拟浏览器指纹。请确认插件依赖已安装。

模板触发没反应

先用 #画图帮助 确认模板名是否存在。如果开启了 prefix=true，请使用命令前缀或 @机器人 唤醒。

图生图提示“请发送或引用一张图片”

插件没有拿到可用底图。请直接发送图片、引用图片、@QQ 用户，或确认当前平台能通过发送者 ID 获取 QQ 头像。

返回了视频但没有图片

只有 openai_compat_chat 兼容端点可能返回视频 URL。插件会发送视频组件；如果端点返回 base64 视频数据，当前不会直接发送。