# 请求与响应

> YesCaptcha API 的通用约定：POST JSON、clientKey 鉴权、errorId 响应格式、同步和异步任务、每 5 秒轮询、110 秒超时、结果保留约 10 分钟、提示语言跟随 Accept-Language。

Source: https://docs.yescaptcha.com/zh/api/overview/ · Last verified: 2026-10-15

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

## 请求

```bash
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`（国内），见 [接入地址](https://docs.yescaptcha.com/zh/getting-started/endpoints/)。
-   请求体是 JSON，带请求头 `Content-Type: application/json`，不超过 6 MB。JSON 里不能写注释。
-   每个请求都要带 `clientKey`，完整复制后台显示的值。
-   Python 的 requests 用 `json=data`，不要用 `data=data`（后者发的是表单，会返回 `ERROR_TASK_ABSENT` 或 `ERROR_REQUIRED_FIELDS`）。

## 响应

成功：

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

失败：

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

| 字段 | 说明 |
| --- | --- |
| `errorId` | 0 成功，1 失败 |
| `errorCode` | 失败时的错误码，含义和处理办法见 [错误码](https://docs.yescaptcha.com/zh/api/errors/) |
| `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` | 不需要再查 |

各类型属于哪一种，见 [任务类型与价格](https://docs.yescaptcha.com/zh/tasks/) 的“返回方式”列。

## 轮询

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 创建任务](https://docs.yescaptcha.com/zh/api/create-task/)
-   [getTaskResult 获取结果](https://docs.yescaptcha.com/zh/api/get-task-result/)
-   [并发限制与自动暂停](https://docs.yescaptcha.com/zh/api/rate-limits/)：出错太多会被暂停几分钟