小影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 聚合服務