自研圖形驗證碼

自研圖形驗證碼（字符圖片 / 算術），Pillow 本地繪製、無第三方依賴，答案一次性校驗。

/api/captcha_self/

服務說明

自研圖形驗證碼不依賴任何第三方服務，由平臺用 Pillow 在本地繪製字符圖片或算術題，適合對數據外發敏感、或希望零成本自建驗證碼的場景。

接入為兩步：先調用生成接口拿到 captcha_id 與 base64 圖片（帶有效期），用戶作答後調用校驗接口提交答案。答案是「一次性」的——無論校驗成功還是失敗都會立即失效，失敗後需重新生成再試。服務端只保存答案的 HMAC-SHA256 摘要，不落明文。

該線路為開放接口，無需項目簽名；服務端已按客戶端 IP 限流（生成 60 次/分、校驗 120 次/分），並在響應上禁用緩存，避免圖片被瀏覽器 / 代理復用。

同一服務下另有「滑塊驗證」與「漢字點選」線路：前者拖動拼圖塊對齊缺口，後者按提示依次點擊 2-4 個漢字；兩者的答案坐標都不下發，只存服務端用於校驗。

三條線路怎麼選：表單防刷優先字符 / 算術（生成快、體積小）；想要拖動體驗用滑塊；面向中文用戶、希望更直觀可以用漢字點選。

響應格式

所有接口返回同一個 JSON 信封，業務數據都在 data 裡：

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}

code：業務狀態碼，10000 表示成功；其餘為各類錯誤，完整清單見「錯誤碼」頁。
msg：給人看的提示文案，可直接展示給終端用戶，但不要用它做邏輯判斷。
data：業務數據；出錯時通常為 null。各接口 data 的具體字段見該接口的「響應說明」。

判斷成功與否請看 code，不要依賴 HTTP 狀態碼。查看完整錯誤碼

維護中該服務當前處於「維護中」狀態，接口可能臨時不可用。以下文檔與調試僅供了解。

自研驗證碼

SpiderServices/Captcha 自研生成引擎（Pillow 繪製）開放 · 免簽名

兩步接入：先 generate 拿 captcha_id 與圖片（base64），用戶作答後 POST verify 校驗；答案一次性，校驗後無論對錯立即失效，需配合前端換新圖。

GET /api/captcha_self/generate 累計調用 0 次

生成驗證碼

生成一張驗證碼，返回 captcha_id、base64 圖片與有效期。

驗證碼類型 kind

選填：char=字符圖片（數字+大寫字母）；arithmetic=算術加減法

字符個數 length

選填：僅 kind=char 生效，取值 4-6（默認 4）

請求方式 GET，參數放 query string；公開接口，無需項目簽名。
captcha_id 必須與答案一起回傳給 verify；image 可直接用作 <img src>。
響應頭帶 Cache-Control: no-store，圖片不會被瀏覽器 / 代理緩存復用。
同一 IP 每分鐘最多生成 60 張，超出返回 20040。

響應說明外層統一格式

字段	類型	說明
captcha_id	string	驗證碼ID，校驗時回傳
kind	string	類型：char/arithmetic
image	string	base64 圖片（data URI）
expire_in	int	有效期（秒）

返回示例

{"captcha_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "kind": "char", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "expire_in": 300}

POST /api/captcha_self/verify 累計調用 0 次

校驗驗證碼

提交用戶答案校驗，一次性消費（校驗後立即失效）。

驗證碼ID captcha_id *

必填：生成接口返回的 captcha_id（UUID）

用戶答案 answer *

必填：用戶填寫的答案（字符不區分大小寫；算術填計算結果）

請求體為 application/x-www-form-urlencoded 表單；開放接口，無需項目簽名。
校驗通過：code=10000 且 data.passed=true；
未通過（答案錯誤 / 已過期 / 已使用 / 不存在）：code=20003 且 data.passed=false，原因見 msg；
captcha_id 非 UUID 時返回 code=20002，參數缺失時返回 code=20001。
答案一次性：同一條驗證碼重複提交只會成功一次，失敗後需重新調用 generate。
同一 IP 每分鐘最多校驗 120 次，超出返回 20040；答案用恆定時間比較，庫中只存摘要。

響應說明外層統一格式

字段	類型	說明
passed	bool	是否校驗通過

返回示例

{"passed": true}

滑塊驗證

Pillow 本地合成（背景圖 + 拼圖塊）開放 · 免簽名

拖動拼圖塊對齊缺口；缺口橫坐標不下發，服務端按 ±8px 容差比對摘要，並校驗拖動軌跡（點數 / 時長 / 時間單調 / 終點一致）。

GET /api/captcha_self/slider/generate 累計調用 0 次

生成滑塊

生成背景圖與拼圖塊，返回 slider_id、縱坐標與畫布尺寸。

拖動體驗

請求方式 GET，公開接口，無需項目簽名。
background 為 JPEG、piece 為 PNG（均為 data URI）；缺口橫坐標不在響應裡，必須由用戶拖動拼圖塊對齊。
同一 IP 每分鐘最多生成 30 張，超出返回 20040；響應禁止緩存。

響應說明外層統一格式

字段	類型	說明
slider_id	string	滑塊ID，校驗時回傳
background	string	背景圖（JPEG data URI）
piece	string	拼圖塊（PNG data URI，透明背景）
piece_y	int	拼圖塊縱向位置（像素）
piece_size	int	拼圖塊邊長（像素）
width	int	畫布寬度（像素，320）
height	int	畫布高度（像素，160）
expire_in	int	有效期（秒）

返回示例

{"slider_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "background": "data:image/jpeg;base64,/9j/4AAQ…", "piece": "data:image/png;base64,iVBORw0KGgo…", "piece_y": 42, "piece_size": 52, "width": 320, "height": 160, "expire_in": 180}

POST /api/captcha_self/slider/verify 累計調用 0 次

校驗滑塊

提交拼圖塊位置與拖動軌跡，一次性校驗。

滑塊ID slider_id *

必填：生成接口返回的 slider_id（UUID）

橫向位置 x *

必填：拼圖塊左邊緣的畫布橫坐標（可帶小數）

拖動軌跡 track *

必填：JSON 數組，元素為 {"x": 畫布坐標, "t": 相對毫秒}；至少 5 個點，總時長 200ms-60s，終點須與 x 一致

請求體為 application/x-www-form-urlencoded 表單；公開接口，無需項目簽名。
位置誤差 ±8px 內視為對齊；缺口橫坐標不下發，庫中只存摘要。
軌跡點數不足 / 用時過短 / 時間倒退 / 終點與 x 不一致都會被拒絕。
一次性：無論成功失敗，同一 slider_id 只能校驗一次。
同一 IP 每分鐘最多校驗 60 次；連續失敗 10 次冷卻 10 分鐘，兩種攔截都返回 20040。

響應說明外層統一格式

字段	類型	說明
passed	bool	是否校驗通過

返回示例

{"passed": true}

漢字點選

Pillow + 內置中文字體（8 個候選漢字，點選 2-4 個）開放 · 免簽名

按提示依次點擊目標漢字；目標坐標不下發，服務端校驗點擊順序、命中位置與總用時。

GET /api/captcha_self/click/generate 累計調用 1 次

生成點選驗證碼

生成一張含 8 個候選漢字的圖片，返回挑戰ID、圖片與目標字順序。

點選體驗

請求方式 GET，公開接口，無需項目簽名。
chars 是按順序需要點擊的目標字（2-4 個）；每個字的坐標不在響應裡，服務端只落庫用於命中判斷。
同一 IP 每分鐘最多生成 30 張，超出返回 20040；響應禁止緩存。

響應說明外層統一格式

字段	類型	說明
challenge_id	string	挑戰ID，校驗時回傳
image	string	驗證碼圖片（PNG data URI）
chars	array	按順序需要點擊的目標漢字
count	int	目標字個數（2-4）
width	int	畫布寬度（像素，360）
height	int	畫布高度（像素，200）
expire_in	int	有效期（秒）

返回示例

{"challenge_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "image": "data:image/png;base64,iVBORw0KGgo…", "chars": ["山", "河", "云"], "count": 3, "width": 360, "height": 200, "expire_in": 180}

POST /api/captcha_self/click/verify 累計調用 0 次

校驗點選

提交按順序的點擊點，校驗順序、命中位置與總用時。

挑戰ID challenge_id *

必填：生成接口返回的 challenge_id（UUID）

點擊點 points *

必填：JSON 數組，元素為 {"x": 畫布橫坐標, "y": 畫布縱坐標, "t": 相對毫秒}；點數須等於 count，總時長不少於 300ms

請求體為 application/x-www-form-urlencoded 表單；公開接口，無需項目簽名。
點擊順序必須與 chars 一致；每個點需落在對應目標字半徑 26px 內。
點數不符 / 順序錯 / 點偏 / 總用時不足 300ms 都會被拒絕。
一次性：無論成功失敗，同一 challenge_id 只能校驗一次。
同一 IP 每分鐘最多校驗 60 次；連續失敗 10 次冷卻 10 分鐘，兩種攔截都返回 20040。

響應說明外層統一格式

字段	類型	說明
passed	bool	是否校驗通過

返回示例

{"passed": true}

接口目錄 6

自研驗證碼

GET 生成驗證碼 /api/captcha_self/generate POST 校驗驗證碼 /api/captcha_self/verify

滑塊驗證

GET 生成滑塊 /api/captcha_self/slider/generate POST 校驗滑塊 /api/captcha_self/slider/verify

漢字點選

GET 生成點選驗證碼 /api/captcha_self/click/generate POST 校驗點選 /api/captcha_self/click/verify

鑑權設置

僅本機保存