图片生成插件 (astrbot_plugin_free_image)

astrbot_plugin_free_image 是一个面向 AstrBot 的图片生成插件，支持文生图、图生图、预设模板生图、LLM 函数工具调用、多模型回退、配额管理、WebUI、图片缓存和沉浸式自拍功能。

插件的核心特色是“API 管线”：你可以在 WebUI 中配置多个图片生成节点，插件会按顺序调用，当前节点失败时自动回退到下一个节点。插件还支持高度自定义自拍人设和自拍风格，赋予机器人更生动的交互体验。

快速开始

1. 安装并启用插件。
2. 在 AstrBot WebUI 的「FreeImage」配置中打开「API 管线」，添加至少一个图片生成节点，填写 API 地址、模型、Key 和能力。
3. 发送 /文生图 一只在月球上喝咖啡的猫 测试。

推荐新用户先完成这几项设置：

配置项	建议
general.prefix	保持开启，避免普通聊天误触模板。
api_pipeline	至少添加一个可用节点；需要回退时按优先级从上到下排列。
quota	按需开启用户次数、群次数和全局冷却。
cache.enable_image_cache	想保留生成图片时开启。
selfie	需要自拍功能时再配置。

命令

生成图片

命令	用途	示例
/文生图 <描述>	根据文字生成图片。	/文生图 赛博朋克少女
/图生图 <描述>	根据图片和文字修改或重绘图片。	引用或发送图片后输入 /图生图 改成油画风格
/<模板名>	使用预设模板做图生图。	发送图片后输入 /手办化
/自拍 <描述>	使用自拍人设生成机器人自拍。	/自拍 在便利店喝咖啡
/画图帮助	查看已加载模板。	/画图帮助
/画图帮助 <模板名>	查看某个模板的完整提示词。	/画图帮助 手办化
/自拍帮助	查看自拍命令速查。	/自拍帮助
/自拍人设 查看 [ID或名称]	查看当前或指定自拍人设。	/自拍人设 查看 椰子
/自拍人设 列表	查看所有自拍人设。	/自拍人设 列表
/自拍风格 查看 [ID或名称]	查看当前或指定自拍风格。	/自拍风格 查看 cinematic
/自拍风格 列表	查看所有自拍风格。	/自拍风格 列表
/画图查询次数	查询个人和当前群的剩余次数。	/画图查询次数
/画图签到	领取个人永久次数。	/画图签到
/文生视频 <描述>	预留命令，当前版本暂未适配。	/文生视频 海边日落
/图生视频 <描述>	预留命令，当前版本暂未适配。	发送图片后输入 /图生视频

/画图帮助 也可使用 lmh 或 lm帮助；/画图添加模板 也可使用 lma 或 lm添加。

指定模型

在 文生图、图生图、自拍 或模板名后追加 -<序号>，可以指定本次只使用某个节点，不触发回退。

命令	示例
/文生图-<序号> <描述>	/文生图-2 赛博朋克少女
/图生图-<序号> <描述>	/图生图-2 改成油画风格
<模板名>-<序号> [描述]	手办化-2
/自拍-<序号> <描述>	/自拍-2 在窗边看书

序号来自 /画图模型，从 1 开始，包含已关闭节点。指定模型失败时不会回退到其他模型。

管理命令

命令	用途
/画图模型	查看管线顺序和启用状态。所有用户可用。
/画图模型 置顶 <序号>	将指定节点移到管线顶部。
/画图模型 开启 <序号>	启用指定节点。
/画图模型 关闭 <序号>	关闭指定节点。
/停止画图	强行停止当前所有画图任务。
/画图添加模板 <触发词>:<提示词>	新增预设模板。
/画图缓存 状态	查看生成图片缓存状态。
/画图缓存 开启 / /画图缓存 关闭	切换生成图片缓存。
/画图缓存 清理	清理未收藏缓存，保留收藏、历史记录和自拍参考图。
/画图简洁模式 开启 / /画图简洁模式 关闭	切换 QQ 群聊简洁模式。
/画图增加用户次数 <用户> <数量>	给用户增加永久次数，支持 @ 或 QQ 号。
/画图增加群组次数 <群号> <数量>	给群增加永久次数。
/画图查询次数 <用户>	查询指定用户剩余次数。
/自拍人设 添加 <ID> <名称>	将消息中的显式图片保存为自拍人设参考图。
/自拍人设 绑定 <ID或名称>	将当前会话绑定到指定人设。
/自拍人设 默认 <ID或名称>	设置全局默认人设。
/自拍风格 添加 <ID> <名称> <提示词> [关键词|关键词]	新增自拍风格，可选关键词用于自动命中。
/自拍风格 模式 <不注入/自动/指定>	切换风格注入模式。
/自拍风格 选择 <ID或名称>	在指定模式下选择默认风格。

/停止画图 仅管理员可用。没有任务时回复「当前无画图任务」；有任务时回复「已停止x个画图任务」。串行批量按 1 个任务计数，管理员并发批量按已启动的单张图片计数。

图片输入规则

普通图生图和模板

用户显式提供的图片会全部参与生成：引用消息中的图片在前，当前消息附带的图片在后，重复图片会去重，最多读取 10 张。实际传给 API 的张数由 Provider 能力决定。

场景	参考图
引用图片，或引用图片并附带新图片	使用这些显式图片，不追加 @头像。
只发送当前消息图片	使用这些图片。
当前消息图片 + @其他用户	使用图片和该用户头像。
无图片，只 @其他用户	使用该用户头像。
无图片，只 @机器人	按 general.ignore_bot_at_avatar 决定是否使用机器人头像。
无图片，也无 @	尝试使用发送者头像。

GIF、WebP 等动图会自动提取第一帧。general.ignore_bot_at_avatar 开启时，普通图生图和模板会忽略机器人自身的 @头像；如果因此没有可用参考图，不会改用发送者头像。

LLM 工具

image_generation 只有在当前消息或引用消息中存在显式图片时才按图生图处理。没有显式图片时按文生图处理，不会把 @头像或发送者头像当作图生图输入。已有显式图片时，@头像规则与普通图生图一致。

自拍

自拍会先使用人设参考图，再把用户显式提供的图片作为额外参考图。显式图片同样会合并引用图片和当前消息图片，总数不超过 10 张；超出时优先保留人设参考图。

场景	额外参考图
引用图片，或引用图片并附带新图片	使用这些显式图片，不追加 @头像。
只发送当前消息图片	使用这些图片。
当前消息图片 + @其他用户	使用图片和该用户头像。
无图片，只 @其他用户	使用该用户头像。
无图片，只 @机器人	不添加额外参考图。
无图片，也无 @	不添加额外参考图。

自拍始终忽略机器人自身的 @头像。/自拍人设 添加 只保存用户显式发送或引用的图片，不会保存头像。

模型与 Provider

插件按 api_pipeline 从上到下调度。当前节点失败时，自动尝试下一个支持当前模态的节点；指定序号时不回退。

能力	说明
text2image	文生图。
image2image	图生图、模板和自拍。
text2video / image2video	视频能力预留，当前版本命令尚未适配。

模板	需要 Key	说明
vertex_ai_anonymous	否	Vertex AI 匿名逆向接口，依赖 curl_cffi，可用性受上游影响。
gemini	是	Gemini 原生 API，支持多图输入和 Gemini 3 清晰度配置。
openai_images	是	OpenAI Images API；无参考图走生成，有参考图走编辑。
openai_responses	是	OpenAI Responses API 的图片生成工具。
openai_compat_chat	是	OpenAI Chat Completions 兼容端点，可解析图片和视频 URL。
siliconflow	是	通用图片生成端点，最多传 3 张参考图。
bigmodel	是	通用图片生成端点，最多传 3 张参考图。

每个节点支持多个 Key 轮换、节点级代理、超时和重试配置。429、配额耗尽和频率限制会使用更长的退避时间。用户图片、头像和远程结果图片的下载超时由 general.download_timeout 控制。

输出行为

普通模式下，插件先发送“正在生成”，成功后发送图片和耗时、剩余次数、命中模型等信息；失败时返回聚合错误。QQ 群聊开启简洁模式后，插件会尝试给原消息贴表情，成功后只发送图片，失败时仍发送原因。

general.quote_reply_mode 控制生成结果是否引用回复原消息。general.multi_image_send_mode 控制多图结果是合并发送还是分条发送。general.generation_start_message 可自定义开始文案，支持 {type} 和 {prompt} 占位符。

send_selfie 始终按简洁模式发送结果。openai_compat_chat 返回视频 URL 时会发送视频组件；返回内嵌 base64 视频时，当前版本会提示不支持直接发送。

权限与配额

管理员不受黑白名单、次数和冷却限制，剩余次数显示为 ∞。

项	行为
用户/群黑名单	命中后静默拒绝。
用户/群白名单	非空时只允许名单内用户或群使用，管理员除外。
用户次数	永久次数 + 今日剩余固定额度。
群组次数	永久次数 + 今日剩余固定额度。
扣费顺序	用户和群限制同时开启时，优先扣群次数。
签到	增加用户永久次数。
冷却	全局冷却，任何非管理员触发都会刷新冷却时间。

批量生图每张独立调用 API 并独立扣费。次数不足时，剩余张数会收到配额提示，不会调用 API。

LLM 工具

插件注册两个可供模型调用的工具。

工具	触发场景	参数
image_generation	用户要求生成或修改图片。	prompt：最终提示词；count：生成数量，1~3。
send_selfie	用户要求机器人本人出镜、自拍或合影。	action：动作和场景；style_id：可选风格；count：生成数量，1~3。

工具不支持指定模型，始终走自动回退。调用后插件会在后台发送结果，并停止本次 LLM 回复，避免模型继续输出造成超时。两个工具都受权限、配额和冷却限制。

自拍功能

1. 发送或引用一张、多张角色参考图。
2. 执行 /自拍人设 添加 yeko 椰子，插件会把显式图片保存为人设参考图。
3. 可选：执行 /自拍人设 绑定 椰子，将当前会话绑定到该人设。
4. 执行 /自拍 在便利店门口喝冰咖啡 生成自拍。

人设解析支持三种模式：

模式	行为
优先 AstrBot persona	先按当前 AstrBot 人设绑定匹配，再按会话绑定，最后用全局默认。
优先会话 SID	先按当前群或私聊绑定匹配，再按 AstrBot 人设，最后用全局默认。
只使用手动指定的selfie人设	始终使用 selfie.selfie_persona_manual_override，找不到时回退全局默认。

风格注入支持不注入、自动识别和固定指定三种模式。可用 /自拍帮助、/自拍人设 列表、/自拍风格 列表 查看当前状态。

Pages 控制台

AstrBot Pages 中提供插件控制台，可管理管线、模板、自拍、缓存、统计和通用设置，与 WebUI 修改同一份配置。

• 生图历史支持关键词、日期、触发人、模式、模型和收藏筛选。
• 可收藏单张生成图片；收藏不计入缓存限额，也不会被一键清理。
• 删除历史记录时会同时删除关联生成图片；自拍参考图不受影响。
• 缓存支持按大小、时间和数量自动清理，也可用命令手动清理。

目录结构

下面用相对路径说明插件代码、配置和运行数据的职责。

插件代码目录（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       # 某个自拍人设的参考图文件

常见问题

提示「API 管线为空或无已启用的提供商」

在 WebUI 或 Pages 的 API 管线中添加至少一个节点，并确认节点已启用且支持当前模态。

模板触发没反应

先用 /画图帮助 确认模板名存在。如果开启 general.prefix，需要使用命令前缀或 @机器人唤醒。

图生图提示「请发送或引用一张图片」

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

明明发了多张图，模型只使用部分图片

插件最多读取 10 张显式参考图。部分 Provider 会进一步限制参考图数量，例如 siliconflow 和 bigmodel 最多传 3 张；被截断时会写入日志。

停止画图没反应

/停止画图 只停止已经启动的画图任务。任务已经完成后无法撤回生成或发送结果。