Skip to main content
本文介紹驗證碼非同步任務查詢介面 POST /captcha/tasks。當你在調用任意驗證碼介面(token 系列或 recognition 系列)時傳入 async: true,介面會立即返回一個 task_id,伺服器會立即接管並持續處理;你可以用該 task_id 查詢最終結果,但查詢不是任務繼續執行的前提。適用於多打碼器輪換(multi-solver rotation)等場景:提交任務後立即拿到 task_id,先去調度其他打碼器,稍後再回來讀取結果。
📘 完整互動式文檔(含在線調試):驗證碼任務查詢 API →

申請流程

要使用本介面,先到 Ace Data Cloud 控制台 獲取您的 API Token,留作備用。一個 API Token 即可調用平台所有服務,無需為每個服務單獨申請。

基本使用

第一步:以非同步方式創建任務

在任意驗證碼介面的請求體中傳入 async: true,介面會立即返回 task_id(HTTP 201),而不會阻塞等待:

第二步(可選):用 task_id 查詢結果

如需主動查看進度,可使用上一步返回的 task_id 查詢 POST /captcha/tasks(建議每 3~5 秒一次)。本介面不會觸發或推進任務處理;讀取 ready 結果時沿用現有的一次性結算行為:
處理中會返回 status: processing:
處理完成會返回 status: ready 及對應結果字段——字段結構與同步模式完全一致:
  • token 系列(hcaptcha、recaptcha2、recaptcha3)返回 token:
  • recognition 分類(recognition/recaptcha2、recognition/hcaptcha)返回 solution;recognition/image2text 返回 text。
/captcha/tasks 對所有驗證碼介面(token 與 recognition 系列)通用,用同一個 task_id 輪詢即可。 伺服器從創建時開始持續處理,最長 120 秒。如果到 deadline 的最後一次查詢仍未得到結果,會持久化 HTTP 504。該狀態是終態,客戶端應停止輪詢;重複查詢同一個 task_id 會穩定返回相同的失敗結果:
status: ready 和 HTTP 504 的終態響應都會帶上計時字段。
  • started_at,任務開始處理時間,Unix 時間戳(秒,浮點)。
  • finished_at,任務產出結果時間,Unix 時間戳(秒,浮點)。仍在處理中時不返回該字段。
  • elapsed,任務處理耗時,單位為秒(浮點,保留 3 位小數)。仍在處理中時不返回該字段。

計費說明

非同步模式下,創建任務和讀取「處理中」狀態都不計費;客戶端首次讀取成功結果時計費一次(與現有行為及同步模式價格一致)。伺服器會自主推進任務,但不會因為後台先完成就提前扣費。120 秒 deadline 內未成功的任務以 HTTP 504 終止且不計費。

錯誤處理

在調用本介面時,如果遇到錯誤,會返回相應的錯誤代碼和信息。例如:
  • 400 invalid_request:請求缺少 task_id 參數。
  • 401 invalid_token:未授權,授權 Token 無效或缺失。
  • 404 not_found:task_id 不存在,或不屬於當前帳號。
  • 504 timeout:任務已終止且未產生結果;請停止輪詢該 task_id。該失敗不會扣費。

錯誤響應示例