请求与响应

所有接口都用 HTTPS POST 发送 JSON（只有 /useragent 是 GET），用请求体里的 clientKey 鉴权，响应都是 JSON：errorId 为 0 表示成功，为 1 表示失败并带 errorCode。识别一个验证码分两步：createTask 创建任务，getTaskResult 每 5 秒查一次结果；同步类型在 createTask 里直接返回结果。

请求

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'

• 节点：https://api.yescaptcha.com（国际）或 https://cn.yescaptcha.com（国内），见 接入地址。
• 请求体是 JSON，带请求头 Content-Type: application/json，不超过 6 MB。JSON 里不能写注释。
• 每个请求都要带 clientKey，完整复制后台显示的值。
• Python 的 requests 用 json=data，不要用 data=data（后者发的是表单，会返回 ERROR_TASK_ABSENT 或 ERROR_REQUIRED_FIELDS）。

响应

成功：

{ "errorId": 0, "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006" }

失败：

{ "errorId": 1, "errorCode": "ERROR_ZERO_BALANCE", "errorDescription": "帐户余额不足" }

字段	说明
errorId	0 成功，1 失败
errorCode	失败时的错误码，含义和处理办法见 错误码
errorDescription	失败原因的文字说明
taskId	任务 ID
status	processing（处理中）或 ready（完成）
solution	识别结果，字段因任务类型而异，见各任务类型页

判断结果时以 errorId 和 errorCode 为准，不要解析 errorDescription 的文字，它可能调整。

同步和异步

	异步	同步
哪些类型	返回 token 的类型（reCAPTCHA、hCaptcha、Turnstile、FunCaptcha）、Cloudflare 5 秒盾、ImageToTextTask、ImageToTextTaskM1	图像识别（名字以 Classification 结尾）、ImageToTextTaskOcrBase、ImageToTextTaskMuggle
createTask 返回	taskId	status: "ready" 和 solution
怎么拿结果	每 5 秒调用一次 getTaskResult	不需要再查

各类型属于哪一种，见 任务类型与价格 的“返回方式”列。

轮询

1. createTask 返回 taskId 后，等 5 秒再调用 getTaskResult。
2. 返回 status: "processing" 就再等 5 秒重试；返回 status: "ready" 时结果在 solution 里。
3. 返回 errorId: 1 就停止轮询这个任务，按 errorCode 处理。

• 同一个 taskId 5 秒内的重复查询会直接返回 processing，查得更勤不会更快拿到结果。
• 任务一般最长处理 110 秒（少数类型 180 到 220 秒），超时返回 ERROR_TASK_TIMEOUT 并自动退点。
• 结果在服务端保留约 10 分钟，之后 taskId 失效，查询返回 ERROR_TASKID_INVALID。
• 查询结果不扣点，只有创建任务时扣点。

提示文字的语言

自动暂停、无效参数缓存、停止轮询这几类提示的 errorDescription 按请求头 Accept-Language 选择语言：以 zh 开头返回中文，其他语言返回英文，不带这个请求头时中英文都返回。其他错误码的说明不受影响。

下一步

• createTask 创建任务
• getTaskResult 获取结果
• 并发限制与自动暂停：出错太多会被暂停几分钟