astrbot_plugin_free_image 是一个面向 AstrBot 的图片生成插件，支持文生图、图生图、预设模板生图、LLM 函数工具调用、多模型回退、配额管理、生成历史、图片缓存和沉浸式自拍功能。
插件的核心特色是“API 管线”：你可以在 WebUI 中配置多个图片生成节点，插件会按顺序调用，当前节点失败时自动回退到下一个节点。插件还支持高度自定义自拍人设和自拍风格，赋予机器人更生动的交互体验。另外，插件内置了 Vertex AI 匿名逆向节点，可用性受上游服务状态影响。
| 能力 | 说明 |
|---|---|
| 文生图 | 使用 #文生图 <描述> 直接生成图片。 |
| 图生图 | 支持直接发送图片、引用图片、@用户头像、默认使用发送者 QQ 头像作为参考图。 |
| 预设模板 | 通过 prompt_list 配置模板触发词，例如“手办化”“真人化”等。 |
| 多图输入 | 图生图最多读取 10 张参考图，传给 Provider 的张数由具体 Provider 能力决定。 |
| 动图处理 | GIF/WebP 等动图会自动提取第一帧作为参考图。 |
| 多模型回退 | api_pipeline 从上到下调度，当前节点失败时自动回退到下一个节点。 |
| 指定模型生图 | 使用 文生图-<序号> 等命令指定单个模型生图，不回退；所有用户可用。 |
| Key 轮换 | 每个 Provider 节点可配置多个 api_keys，运行时自动 Round-robin 使用。 |
| 退避重试 | 对 429、资源耗尽、网络波动等错误进行重试和退避。 |
| 权限配额 | 支持管理员免限制、用户/群黑白名单、用户/群每日额度、永久次数和签到奖励。 |
| 历史与缓存 | 记录生图历史；可选保存生成图片缓存，并支持按大小、时间和数量自动清理。 |
| LLM 工具 | 注册 image_generation 工具，允许模型在对话中主动调用生图能力。 |
| 人设自拍 | 配置好自拍人设后，支持 #自拍 命令和 send_selfie LLM 工具，让机器人用固定形象出镜。 |
| QQ 优化 | 群聊简洁模式可贴表情，成功后只发送图片；也支持引用回复和多图分条策略。 |
| 插件控制台 | AstrBot Pages 内提供管线、模板、自拍、统计和设置页面，与 WebUI 修改插件配置等价。 |
- 将本仓库放入 AstrBot 插件目录并启用插件。
- 安装依赖：本仓库已在
requirements.txt声明aiohttp、beautifulsoup4、curl_cffi、Pillow。 - 在 AstrBot WebUI 中配置
api_pipeline，至少添加一个已启用的图片生成节点。 - 如果节点需要 API Key，请在对应
api_pipeline节点的api_keys中填写。聊天命令不再提供 Key 增删查功能。
常用配置项：
| 配置项 | 说明 |
|---|---|
api_pipeline |
图片生成 Provider 管线，决定模型、API 地址、Key、代理、超时和重试。 |
prompt_list |
预设模板列表，格式为 触发词:提示词。 |
general.prefix |
是否要求命令带前缀或 @机器人 唤醒，推荐开启。 |
general.concise_mode |
QQ 群聊简洁模式：收到画图请求贴 OK 表情（124），收到自拍请求贴爱心表情（66），成功后只发图片。 |
general.quote_reply_mode |
控制生成成功后的图片消息是否引用回复。 |
general.multi_image_send_mode |
控制多图结果是否合并发送或分条发送。 |
general.download_timeout |
下载用户图片、头像或远程结果图片的超时时间。 |
cache.enable_image_cache |
是否保存成功生成的图片缓存。关闭后仍会记录生图历史，但不保存图片文件。 |
cache.image_cache_max_size_mb |
最大缓存大小（MB），留空或 0 表示不限制。 |
cache.image_cache_max_age_hours |
最长缓存保存时间（小时），留空或 0 表示不限制。 |
cache.image_cache_max_count |
最多保存缓存图片张数，留空或 0 表示不限制。 |
quota.rate_limit_seconds |
非管理员全局生图冷却时间。 |
llm_tools.llm_tool_description |
LLM 看到的普通画图工具描述。 |
llm_tools.llm_prompt_description |
LLM 构造最终生图 Prompt 时参考的描述。 |
selfie.selfie_binding_mode |
自拍人设绑定模式，默认"优先 AstrBot persona"。 |
selfie.selfie_default_persona_id |
全局默认自拍人设 ID，留空则自动取列表第一个。 |
selfie.selfie_persona_manual_override |
手动指定 selfie 人设 ID，仅在“只使用手动指定的selfie人设”模式下生效。 |
selfie.selfie_style_mode |
自拍风格注入模式：不注入 / 自动 / 指定。 |
| 命令 | 用途 | 示例 |
|---|---|---|
#文生图 <描述> |
根据文字生成图片。 | #文生图 一位在霓虹灯下的赛博朋克少女 |
#文生图-<序号> <描述> |
指定单个模型生图，不回退。序号见 #画图模型。 |
#文生图-2 赛博朋克少女 |
#图生图 <描述> |
根据图片和文字修改/重绘图片。 | 发送或引用图片后输入 #图生图 改成油画风格 |
#图生图-<序号> <描述> |
指定单个模型做图生图，不回退。 | 发送图片后输入 #图生图-2 改成油画风格 |
#画图帮助 |
查看已加载的模板触发词。 | #画图帮助 |
#画图帮助 <模板名> |
查看某个模板的完整提示词。 | #画图帮助 手办化 |
#画图签到 |
签到领取个人永久次数，需开启签到功能。 | #画图签到 |
#画图查询次数 |
查询自己的个人剩余次数和当前群共享次数。 | #画图查询次数 |
<模板名> |
使用预设模板做图生图。 | 发送图片后输入 手办化 |
<模板名>-<序号> |
指定单个模型使用预设模板，不回退。 | 发送图片后输入 手办化-2 |
#自拍 <描述> |
用配置好的自拍人设生成机器人自拍。 | #自拍 在便利店门口喝冰咖啡 |
#自拍-<序号> <描述> |
指定单个模型生成自拍，不回退。 | #自拍-2 在便利店门口喝冰咖啡 |
#自拍帮助 |
查看自拍相关命令速查、当前风格模式和绑定模式。 | #自拍帮助 |
#自拍人设 查看 [ID或名称] |
查看当前命中的人设，或浏览指定人设详情。 | #自拍人设 查看 椰子 |
#自拍人设 列表 |
查看所有自拍人设。 | #自拍人设 列表 |
#自拍风格 查看 [ID或名称] |
查看当前命中的风格，或浏览指定风格详情。 | #自拍风格 查看 cinematic |
#自拍风格 列表 |
查看所有风格模板。 | #自拍风格 列表 |
图生图输入优先级：
- 引用消息中的图片
- 当前消息中的图片
- 当前消息中 @ 的 QQ 用户头像
- 发送者自己的 QQ 头像
如果你开启了 general.prefix=true，模板触发也需要命令前缀或 @机器人 唤醒，避免日常聊天误触。
在 文生图、图生图、自拍 或任意模板名后追加 -<序号>，即可指定本次只使用管线中对应序号的模型，不回退。序号来自 #画图模型 显示的列表（从 1 开始，含已关闭节点）。
| 命令 | 说明 |
|---|---|
#文生图-<序号> <描述> |
指定模型做文生图。 |
#图生图-<序号> <描述> |
指定模型做图生图（需附带图片）。 |
<模板名>-<序号> [额外描述] |
指定模型使用预设模板图生图（需附带图片）。 |
#自拍-<序号> <动作描述> |
指定模型生成自拍。 |
行为说明：
- 指定模型模式下，管线只调用该序号对应的 Provider，不回退到其他节点。
- 该序号节点已关闭时，回复
模型 X🔴<名称> 已关闭，请选择其他模型。 - 序号超出范围时，回复
命令格式或参数错误，请重试。并附上当前管线列表。 - 指定模型生图失败时，回复
❌ 指定模型生成失败 (<耗时>s)\n原因: <错误>，不会触发回退。 - LLM 工具（
image_generation/send_selfie）不支持指定模型，始终走自动回退。
管理员指 AstrBot 全局管理员，名单来自 AstrBot 全局配置 admins_id。
| 命令 | 用途 | 示例 |
|---|---|---|
#画图添加模板 |
新增模板，若预设指令已存在则取消添加。 | #画图添加模板 姿势表:为这幅图创建一个姿势表 |
#画图模型 |
查看当前 API 管线顺序和启用状态（所有用户可用，管理员额外看到置顶/开启/关闭提示）。 | #画图模型 |
#画图模型 置顶 <序号> |
将指定节点置顶。 | #画图模型 置顶 3 |
#画图模型 开启 <序号> |
启用指定节点。 | #画图模型 开启 2 |
#画图模型 关闭 <序号> |
关闭指定节点。 | #画图模型 关闭 2 |
#画图缓存 状态/开启/关闭/清理 |
查看、开关或清理生成图片缓存。清理会删除全部已保存缓存图片，不删除生图历史记录。 | #画图缓存 状态 |
#画图简洁模式 开启/关闭 |
切换简洁模式，等效于 WebUI 的 general.concise_mode 开关。 |
#画图简洁模式 开启 |
#画图增加用户次数 |
给用户增加永久次数，支持 @ 或 QQ 号。 | #画图增加用户次数 @某人 10 |
#画图增加群组次数 |
给群组增加永久次数。 | #画图增加群组次数 987654 50 |
#画图查询次数 @用户 |
管理员查询指定用户次数。 | #画图查询次数 @某人 |
#自拍人设 添加 <ID> <名称> |
发送/引用图片后执行，保存为自拍人设参考图。 | #自拍人设 添加 yeko 椰子 |
#自拍人设 绑定 <ID或名称> |
将当前会话 SID 绑定到指定人设。 | #自拍人设 绑定 椰子 |
#自拍人设 默认 <ID或名称> |
设置全局默认回退人设。 | #自拍人设 默认 椰子 |
#自拍风格 添加 <ID> <名称> <提示词> |
新增自定义风格模板，关键词用竖线追加。 | #自拍风格 添加 warm 日常暖光 soft warm light|暖光|窗光 |
#自拍风格 模式 <不注入/自动/指定> |
切换风格注入模式。 | #自拍风格 模式 自动 |
#自拍风格 选择 <ID或名称> |
在"指定"模式下设定默认风格。 | #自拍风格 选择 cinematic |
API Key 请统一在 AstrBot WebUI 的 api_pipeline 节点中配置和管理。
普通模式：
- 收到请求后先回复“正在生成”。
- 成功后发送图片，并附带耗时、剩余次数、命中模型等信息。
- 失败后返回聚合错误信息，便于判断是哪一个 Provider 失败。
简洁模式：
- 仅 QQ 群聊生效，私聊仍按普通模式处理。
- 收到请求时尝试给原消息贴 OK 表情，不主动发“正在生成”。
- 成功后只发图片或视频组件，不附带说明文字。
- 失败仍会发送失败原因；当全部 API 均失败时，仅返回简短失败提示，避免刷屏。
发送策略由以下配置控制：
| 配置项 | 可选值 |
|---|---|
general.quote_reply_mode |
始终引用回复、始终单独发送、命令引用回复，函数调用单独发送、命令单独发送，函数调用引用回复 |
general.multi_image_send_mode |
始终不分条、始终分条、群聊不分条，私聊分条、群聊分条，私聊不分条 |
| 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。支持 n（生成数量）和 size（尺寸，留空自动推断）。 |
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 行为说明：
- 所有需要 Key 的 Provider 都通过
api_keys自动轮换。 - 429、quota、rate limit、resource exhausted 会触发资源限制退避。
- 普通网络错误会触发 3-5 秒随机退避。
openai_compat_chat若解析到视频 URL，会用 AstrBotVideo.fromURL发送；如果端点返回 base64 视频数据，插件会提示当前不支持直接发送内嵌视频。
| 项 | 行为 |
|---|---|
| 管理员 | 不受黑白名单、次数、冷却限制，剩余次数显示为 ∞。 |
| 用户黑名单 | 优先级最高，命中后静默拒绝。 |
| 群黑名单 | 优先级最高，命中后静默拒绝。 |
| 用户白名单 | 非空时只允许名单内用户使用，管理员除外。 |
| 群白名单 | 非空时只允许名单内群使用。 |
| 用户次数 | 用户总次数 = 永久次数 + 今日剩余固定额度。 |
| 群组次数 | 群总次数 = 永久次数 + 今日剩余固定额度。 |
| 扣费顺序 | 同时启用用户和群限制时，优先扣群次数，群次数不足再扣用户次数。 |
| 签到奖励 | 只增加用户永久次数，不直接写入每日额度。 |
| 冷却限制 | 全局冷却，任何非管理员触发都会刷新冷却时间。 |
插件会注册两个 LLM 工具。
image_generation — 普通画图/改图：
| 参数 | 说明 |
|---|---|
prompt |
LLM 根据用户上下文改写后的最终生图提示词。 |
count |
可选。生图数量（1~3），默认 1。除非用户明确要求多张，否则 LLM 不会主动传该参数。 |
工具调用规则：
- 当前消息或引用消息中含图片时，按图生图处理。
- 没有图片组件时，按文生图处理。
- LLM 工具入口不会把 @用户头像当作图生图输入，因为它只检查
Image和Reply(Image)组件。 - 工具被调用后，插件会创建后台任务发送结果，并
stop_event()，避免 LLM 继续输出导致超时。 - 批量生图（
count > 1）时，每张图独立调用 API 并独立扣费；个人/群次数不足时，剩余张数会回复配额提示，不调用 API。
send_selfie — 机器人自拍（需要先配置自拍人设）：
| 参数 | 说明 |
|---|---|
action |
动作、场景、姿势描述，例如"在咖啡店窗边喝拿铁"。 |
style_id |
可选。指定风格 ID 或名称，留空由插件自动选择。 |
count |
可选。生图数量（1~3），默认 1。除非用户明确要求多张，否则 LLM 不会主动传该参数。 |
工具调用规则：
- 用户说"看看你""自拍一张""你现在的样子"等时，LLM 应调用
send_selfie，而非image_generation。 - 当前消息或引用消息中含图片时，图片会作为本次自拍的额外参考图；只有 @其他用户且无图时，会使用该用户头像作为额外参考图。
send_selfie始终按简洁模式发送结果；成功后直接发图，不给用户发送机械化成功文案。- 失败时插件会在后台尝试调用当前会话的 LLM，用角色语气自然解释失败原因；如果当前没有可用 LLM，则发送降级提示。
- 自拍同样受权限、配额、冷却限制，不能绕过。
自拍功能让机器人拥有固定形象，可以用命令或对话触发出图。
第一步：准备参考图
发送一张（或多张）角色参考图，然后引用图片执行：
#自拍人设 添加 <ID> <名称>
例如：先发一张图，再发 #自拍人设 添加 yeko 椰子，插件会把图片保存为"椰子"人设。也支持直接发送一条包含命令和附带图片的消息。
第二步：绑定人设（可选）
插件提供三种绑定模式（在 WebUI 的 selfie.selfie_binding_mode 中选择）：
- 优先 AstrBot persona（默认）：根据当前对话使用的 AstrBot persona 自动匹配自拍人设。在 WebUI 的人设库里，每个人设条目内有"绑定的 AstrBot Persona 名称列表"，填入 AstrBot persona 的名称即可。找不到再回退到会话 SID 绑定，再找不到用全局默认。
- 优先会话 SID：先按当前群/私聊绑定，找不到再按 AstrBot persona，再找不到用全局默认。适合同一 persona 在不同群显示不同形象。
- 只使用手动指定的selfie人设：始终用
selfie.selfie_persona_manual_override中填写的人设，找不到则回退到全局默认。适合极简配置。
用命令绑定当前会话 SID 到指定人设：
#自拍人设 绑定 椰子
不绑定时，插件会使用全局默认人设（用 #自拍人设 默认 <名称> 设置，或在 WebUI 的 selfie.selfie_default_persona_id 中填写）。全局默认也未设置时，自动取人设库第一个。
第三步：生成自拍
#自拍 在便利店门口喝冰咖啡
或者在对话中自然说"看看你现在的样子"，LLM 会自动调用 send_selfie。
自拍输出行为：
#自拍命令受general.concise_mode控制。QQ 群聊开启简洁模式时，触发后尝试贴[表情:66]，成功后只发图片；关闭简洁模式时，会发送“正在生成”和成功说明。send_selfie函数工具始终按简洁模式发送结果，不给用户发送机械化成功文案；aiocqhttp 群聊中会尝试贴[表情:66]，失败只记录 debug 日志，不影响生成。- 成功状态会写入 info 日志，格式类似：
✅ 生成成功 (50.48s) | 人设: xx | 风格: 自拍专用极致真实 | 个人剩余次数: 8 | 模型: gpt-image-2。
自拍额外参考图规则：
| 场景 | 额外参考图 |
|---|---|
| 只有文字，无图片 | 不添加额外参考图，只用自拍人设参考图。 |
| 引用了图片 | 使用引用图片。 |
| 引用了图片且 @机器人 | 仅使用引用图片。 |
| 引用了图片且 @其他用户 | 仅使用引用图片。 |
| 发送了显式图片 | 使用显式图片。 |
| 发送了显式图片且 @其他用户 | 使用显式图片 + 该用户头像。 |
| 只有 @其他用户，无图 | 使用该用户头像。 |
| 只有 @机器人，无图 | 不添加额外参考图，只用自拍人设参考图。 |
自拍总参考图最多 10 张；超出时优先保留靠前的人设参考图，额外参考图只补齐剩余名额。
风格管理
#自拍风格 列表— 查看已配置的风格模板（默认内置"自拍专用极致真实"）#自拍风格 模式 自动— 让插件根据描述关键词自动选风格#自拍风格 模式 指定+#自拍风格 选择 <风格>— 固定使用某套风格#自拍风格 添加 <ID> <名称> <提示词>— 新增自定义风格
下面用相对路径说明插件代码、配置和运行数据的职责。
插件代码目录（data/plugins/astrbot_plugin_free_image/）
├─ main.py # AstrBot 插件入口、命令注册、LLM 工具、核心生图/自拍执行
├─ commands.py # 聊天命令处理逻辑：画图、模型管理、次数、自拍人设/风格管理
├─ pipeline.py # 图片生成 Provider 管线，负责多节点顺序调用和失败回退
├─ quota.py # 权限、冷却、配额、签到和 JSON 持久化
├─ history_cache.py # 生图历史、图片缓存、Pages 偏好设置的持久化
├─ sender.py # 图片/视频发送策略、成功文案、引用回复、多图分条
├─ workflow.py # 用户图片、引用图、@头像、动图首帧等输入图片读取
├─ selfie.py # 自拍人设解析、风格选择、自拍 Prompt 拼接、参考图组合
├─ providers/ # 各图片生成 Provider 的适配实现
│ ├─ base.py # Provider 基类、Key 轮换、重试退避公共逻辑
│ ├─ gemini.py # Gemini 原生 API
│ ├─ vertex_ai_anonymous.py # Vertex AI 匿名逆向节点
│ ├─ openai_images.py # OpenAI Images API
│ ├─ openai_responses.py # OpenAI Responses API
│ ├─ openai_compat_chat.py # OpenAI Chat Completions 兼容端点
│ └─ generic.py # SiliconFlow / BigModel 等通用图片接口
├─ pages/ # AstrBot Pages 页面资源
│ └─ 插件配置/ # 管线、模板、自拍、统计缓存和设置页面
├─ .astrbot-plugin/ # AstrBot 插件附加元数据
├─ _conf_schema.json # AstrBot WebUI 配置项定义
├─ metadata.yaml # 插件元数据
├─ requirements.txt # 插件依赖
├─ README.md # 使用说明
├─ LICENSE # 开源协议
└─ logo.png # 插件图标
AstrBot 插件配置目录（data/config/）
└─ astrbot_plugin_free_image_config.json # WebUI 保存的插件配置，如 api_pipeline、配额、人设和风格模板
AstrBot 分配给本插件的数据目录（通常位于 data/plugin_data/astrbot_plugin_free_image/，以运行时实际路径为准）
├─ user_counts.json # 用户永久次数
├─ group_counts.json # 群组永久次数
├─ user_daily_counts.json # 用户每日额度使用记录
├─ group_daily_counts.json # 群组每日额度使用记录
├─ user_checkin.json # 用户签到日期记录
├─ generation_history.json # 生图历史记录
├─ pages_prefs.json # Pages 用户偏好设置
├─ cache/
│ ├─ index.json # 缓存图片索引
│ └─ images/ # 已保存的生成图片缓存
└─ selfie_personas/ # 命令添加的自拍人设参考图
└─ <persona_id>/ref_*.png # 某个自拍人设的参考图文件
说明：
data/plugins/astrbot_plugin_free_image/是插件代码目录。data/config/astrbot_plugin_free_image_config.json是 WebUI 配置文件，保存用户显式配置。- AstrBot 分配给本插件的数据目录用于保存次数、签到、生图历史、缓存索引、缓存图片和自拍参考图，便于卸载或迁移时统一处理。
请在 WebUI 的 api_pipeline 中添加至少一个节点，并确认该节点 enabled=true。
先用 #画图帮助 确认模板名是否存在。如果开启了 general.prefix=true，请使用命令前缀或 @机器人 唤醒。
插件没有拿到可用底图。请直接发送图片、引用图片、@QQ 用户，或确认当前平台能通过发送者 ID 获取 QQ 头像。
只有 openai_compat_chat 兼容端点可能返回视频 URL。插件会发送视频组件；如果端点返回 base64 视频数据，当前不会直接发送。