图片、贴纸与媒体
配置图片生成、PixAI、贴纸理解和媒体回执，并处理异步任务。
图片能力由 Bot 工具、生成 Provider、Telegram 投递和面板记录共同组成。先在一个私聊或测试群验证，再开放群组图片权限；生成任务通常是异步的，发送“已接受”不等于图片已经成功投递。
两类图片路由
面板的治理和图片设置支持两类用途：
anime_illustration：面向动漫插画等预设路线，可以绑定允许的 preset。general_image：面向通用或写实图片；默认可以关闭，启用前应确认对应 Provider。
路由会根据请求意图、启用状态和 preset 过滤。关闭某一路由后，它不应出现在可用的生成和 preset 列表中；已经存在的任务记录不会因此消失。
PixAI
PixAI 是可选的图片 Provider。管理员需要在受保护的配置中提供 API Key，并选择支持的 API 模式；Key 不要放进聊天或前端代码。Bot 会创建后台任务、轮询状态、记录生成结果，并在完成后把图片发送回原聊天和原 topic。加载 Skill、查询预设和编写提示词只是准备，不表示已提交生成。
图片生成还可能经过内容安全检查、用量限制和并发限制。任务失败、超时、完成但没有图片、或者图片发送失败时，优先在面板 Generations 与日志页面查看同一个任务的状态和错误，不要对同一请求反复重试造成重复任务。
生成状态与投递状态
用 /image status <任务 ID> 或 get_image_generation 查询原任务。生成状态与 deliveryState 分开显示：
| 观测结果 | 含义 |
|---|---|
尚未调用 create_image，或请求被拒绝 | 尚未提交；准备工具成功也不能显示“操作完成” |
preparing | 已接收本地请求，尚未确认供应商提交 |
awaiting_approval / queued / running | 已提交，分别为待审批、排队、生成中 |
succeeded + pending / sending | 已生成，等待投递或正在投递 |
succeeded + failed | 图片保留，但已确定未发送；修复投递错误后可以安全重试 |
attention_required，或投递 unknown | 生成或发送结果未知，需要核对原任务；不要重新提交或盲目重发 |
delivered 且存在 Telegram 消息回执 | 已交付；供应商成功与 Telegram 交付是两个阶段 |
“已提交”不代表“已交付”。投递结果未知可能来自发送超时、连接断开，或 Telegram 已接收但本地回执保存失败。Bot 不会对这类失败自动重发；过期的发送 claim 也不会重新发送。历史未投递记录缺少足够发送证据时同样按未知处理，诊断记录为空不证明从未发送。
只有确定未发送的失败任务可以使用 /image retry <任务 ID> 或 retry_image_delivery 重试。重试使用原任务的图片、chat 和 topic，不创建新的付费生成，也不重复投递已交付任务。图片在发送前的本地读取或安全检查准备失败同样属于确定未发送，恢复原文件后可以重试。明确的 Telegram 限流会按等待时间安全重试；发送客户端不会使用对网络模糊失败自动重试的策略。
取消请求另有 cancellationState：requested 仅表示已请求，rejected 表示拒绝，unknown 表示取消结果未知；只有 confirmed 和生成状态 cancelled 才确认取消。取消被拒绝、取消调用失败，或供应商没有取消接口时，原任务仍保留并继续跟踪。取消请求会在发送前持久化尝试标记；重启发现已尝试但没有确定回执，或旧记录缺少标记时，只恢复原任务查询，不再次发送取消。停止本地请求不能证明供应商已取消。无持久 operation 的通用后端在重启中断后会标记结果未知，不自动重新生图。
服务正常关停时会停止接收新的图片执行和供应商查询，并取消后续轮询；已接纳的操作及其结果、快照和投递回执会等待收尾，再关闭图片连接和数据库。管理员删除图片记录也纳入等待，包括数据库删除和随后尝试清理本地文件；关停开始后不再接纳新的管理员删除。关停不表示远端生成已取消，也不会因此自动退款或重发。关停耗时取决于已有操作及其超时；强制终止进程不具备上述等待保证，重启后仍按原有持久化状态恢复。
NSFW 图片遮罩
Bot 在发送照片、照片相册、替换照片和发送作品图时统一检查图片，不依赖 AI 自行决定是否遮罩。NSFW 综合分数为 porn + hentai + sexy，默认达到 0.5 就使用 Telegram 剧透遮罩；用户点开后才能看到图片。现有 PixAI 配置中的 nsfwThreshold 也用于 Bot 发图。
检测服务超时、返回无效分数或没有配置时，未确认安全的照片也会加遮罩，不会生成虚假的安全评分。主动设置的遮罩会保留。富文本与流式草稿中的内嵌图片统一遮罩，普通消息的链接预览关闭，避免未经检查的预览图片直接显示。
图片作为 document 或 sticker 发送时，Telegram 不支持同样的遮罩。检测出 NSFW 或无法确认安全的图片附件、贴纸会被拒绝，应改用照片发送；无法检测的动态贴纸同样不会直接发送。普通文档附件可正常发送。
新生成的每张图片会保存真实检测分数或检测失败状态。生成记录的 技术详情 中，artifacts[].nsfw 包含检测状态和五类分数；接口同时返回 nsfwScores，用于生成图库的 NSFW 提示。历史已投递图片不会自动重评分；旧的未投递任务会在恢复发送时检测。
Bot 中的常用操作
/image
/draw
/imagegen/image 用于查看预设和任务操作；/draw 按预设启动生成；/imagegen 管理群组图片生成权限。AI 也可能通过 create_image 工具创建任务，但具体工具是否可见取决于当前聊天和治理策略。
角色与提示词资产
在 Bot 的「生成素材库」保存角色设定和常用画风等提示词资产，并通过人物档案绑定默认代表形象。记录按 Bot 隔离，自动注入与 NSFW 默认关闭。
明确要求某个虚构或作品角色时，Bot 不应自动绑定请求者本人及其默认代表形象。personTelegramId 只用于本次明确要求画本人或某位群友；“帮我画”“给我画”不表示画本人。
完整步骤、聊天示例、权限和排错见角色与提示词资产库教程。
图片回执和审计
面板可以配置生成回执文案，并在 Generations 页面查看任务来源、状态、图片数量、错误及相关上下文。图片任务持久化原消息/tool call、generation ID、供应商 operation、投递目标和 Telegram 消息回执；重启恢复沿用原供应商幂等 key。同一消息重复提交相同的实际生成输入会复用已有任务；省略默认预设或显式选择该预设视为同一请求，改变提示词、预设、负面提示词或 seed 则可以创建新任务。普通任务状态查询仅返回有权限的任务和必要的脱敏字段，不包含提示词、供应商原始响应或本地文件路径。相册的附加详情通知失败不会把已收到回执的图片判为未交付。调试图片提示词时，只分享经过脱敏的 prompt；图片 URL、任务 ID、模型配置和用户消息仍可能暴露敏感信息。
贴纸、视频和其他媒体
Bot 可以理解收到的图片和贴纸，并在启用对应流程时使用贴纸表达回应。动画或视频类贴纸可能只提取元数据或有限的首尾帧，不能假设它会被完整理解。媒体下载和缓存受大小、超时、保留期与 Telegram 限制影响。
如果媒体处理异常：
- 用普通静态图片或文字消息做对照。
- 查看 Bot 是否仍在运行，文件缓存是否已被清理。
- 检查生成任务与 Telegram 投递是否是两个不同的失败阶段。
- 避免在公开渠道上传原始用户图片；用错误时间和任务状态协助管理员定位。
更多隐私边界见隐私、历史与记忆。