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。该失败不会扣费。

错误响应示例