小影API 小影API

消息推送服务

把消息推送到手机、邮箱或 QQ 的通知服务。当前接入 Server酱（微信推送）、邮件与 QQBot 3 条线路，后续可继续扩展更多推送平台/线路。

/api/push/

服务说明

消息推送服务把「服务器 / 脚本 / 设备上发生的事」发送到手机、邮箱或 QQ，适合告警、任务完成通知、定时任务结果汇总等场景。当前有 3 条线路：Server酱（微信推送）、邮件 与 QQBot。

消息实际推送到哪个通道（微信服务号、企业微信应用消息、企业微信/钉钉/飞书群机器人、Bark、PushDeer 或自定义 Webhook）由 Server酱 后台的通道配置决定 —— 换通道不用改调用代码。

SendKey 由服务端托管：在超管控制台「账号管理」里新增一个平台为「Server酱」的账号，把 SendKey 填进「登录凭据」字段即可（凭据加密落库、页面不回显）。调用方无需、也不应传递 SendKey。

邮件线路由原「邮箱服务」的发送邮件并入：POST /api/push/email/send 与原 /api/email/v1/send 是同一实现、同一参数与响应，老路由继续可用。

QQBot 线路通过 NapCat（OneBot 11 HTTP）把消息发到 QQ 群 / 好友；NapCat 的 HTTP 地址与 token 在超管控制台「QQBot」页维护，调用方只传目标与内容。

本服务接口需项目签名调用；每次推送都会在控制台「推送日志」留痕（成功与失败都记）。

响应格式

所有接口返回同一个 JSON 信封，业务数据都在 data 里： 

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}
  • code：业务状态码，10000 表示成功；其余为各类错误，完整清单见「错误码」页。
  • msg：给人看的提示文案，可直接展示给终端用户，但不要用它做逻辑判断。
  • data：业务数据；出错时通常为 null。各接口 data 的具体字段见该接口的「响应说明」。

判断成功与否请看 code，不要依赖 HTTP 状态码。 查看完整错误码

Server酱

Server酱（sct.ftqq.com）微信推送 需签名

通过 Server酱 的 SendKey 推送消息；SendKey 由服务端托管（控制台「账号管理」）。需项目签名调用。

POST /api/push/serverchan/send 累计调用 0 次

发送消息

发送一条消息，经由 Server酱 推送到微信（或你在 Server酱 后台配置的其它通道）。

必填：消息标题，最长 32 个字符，不能包含换行

选填：消息正文，支持 Markdown（订阅会员的卡片可显示全文）

选填：本次推送使用的消息通道；不选则用 Server酱 后台「通道配置」页设置的默认通道。需要同时推送到两个通道时，可直接传组合值用 | 分隔（如 9|66）。通道值：方糖服务号=9、企业微信应用消息=66、企业微信群机器人=1、钉钉群机器人=2、飞书群机器人=3、Bark iOS=8、PushDeer=18、官方 Android 版=98、测试号=0、自定义=88。

选填：卡片消息的短链标题

选填：消息标签，多个用 | 分隔

选填：企业微信通道抄送的成员 openid，多个用 | 分隔

选填：是否隐藏本次调用的来源 IP；选「隐藏」后 Server酱 不记录调用方 IP。

选填：填了即对 desp 做端对端加密后再推送，消息在 Server酱 / 微信 侧都是密文；收件人需在消息详情页输入同一密码才能查看内容。密码请另行告知收件人，平台不保存。

  • title 最长 32 个字符且不能含换行；desp 支持 Markdown。
  • SendKey 由服务端托管（控制台「账号管理」→ 平台选「Server酱」、凭据填 SendKey），调用方不传。
  • Server酱 免费账号限制每日 5 条、每分钟 50 条，超限时上游会返回错误码（本接口按外部服务错误返回）。
  • 上游返回非 0 时，本接口返回 40001，msg 即上游给的原因。
  • 发送是异步入队：返回成功只代表已入队，实际是否送达请用「查询推送状态」接口看 wxstatus。
  • 传了 encrypt_password 即为端对端加密：推送日志里记录的是密文，不是明文正文。
响应说明 外层统一格式
字段 类型 说明
pushid string 本次推送的消息标识，用于「查询推送状态」
readkey string 阅读密钥，用于「查询推送状态」与阅读页地址
encrypted bool 本次是否为端对端加密推送（传了 encrypt_password 为 true）
返回示例 
{"pushid": "11223344", "readkey": "abcdef123456", "encrypted": false}
GET /api/push/serverchan/status 累计调用 0 次

查询推送状态

用「发送消息」返回的 pushid + readkey，查询这条消息的实际送达结果（wxstatus）。

必填：发送消息返回的 pushid

必填：发送消息返回的 readkey

  • Server酱 的发送是异步入队，发送接口返回成功只代表「已入队」；实际是否送达微信要看本接口的 wxstatus。
  • wxstatus 为空表示该任务可能还没执行，稍后重试即可。
响应说明 外层统一格式

data 为上游的推送详情 JSON，其中 wxstatus 即微信接口返回的内容（为空表示可能还未执行），以实际返回为准。

小影API · 通用 API 聚合服务