# Yêu cầu và phản hồi

> Quy ước chung của YesCaptcha API: POST JSON, xác thực bằng clientKey, định dạng phản hồi errorId, tác vụ đồng bộ và bất đồng bộ, polling mỗi 5 giây, timeout 110 giây, kết quả được lưu khoảng 10 phút, ngôn ngữ thông báo theo Accept-Language.

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

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/overview/

Mọi phương thức đều gửi JSON bằng HTTPS `POST` (chỉ `/useragent` dùng `GET`), xác thực bằng `clientKey` trong nội dung yêu cầu, và phản hồi đều là JSON: `errorId` bằng 0 là thành công, bằng 1 là thất bại và kèm `errorCode`. Giải một captcha gồm hai bước: `createTask` tạo tác vụ, `getTaskResult` kiểm tra kết quả mỗi 5 giây; các loại đồng bộ trả kết quả ngay trong `createTask`.

## Yêu cầu

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

-   Endpoint: `https://api.yescaptcha.com` (quốc tế) hoặc `https://cn.yescaptcha.com` (Trung Quốc), xem [Địa chỉ truy cập](https://docs.yescaptcha.com/vi/getting-started/endpoints.md).
-   Nội dung yêu cầu là JSON, kèm header `Content-Type: application/json`, không quá 6 MB. JSON không được chứa chú thích.
-   Mỗi yêu cầu đều phải có `clientKey`, sao chép đầy đủ giá trị hiển thị trong bảng điều khiển.

> **Chú ý:** Với requests của Python, hãy dùng `json=data`, không dùng `data=data`. Cách sau gửi dạng form và sẽ trả về `ERROR_TASK_ABSENT` hoặc `ERROR_REQUIRED_FIELDS`.

## Phản hồi

Thành công:

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

Thất bại:

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

| Trường | Mô tả |
| --- | --- |
| `errorId` | 0 là thành công, 1 là thất bại |
| `errorCode` | Mã lỗi khi thất bại; ý nghĩa và cách xử lý xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md) |
| `errorDescription` | Mô tả bằng văn bản về nguyên nhân thất bại |
| `taskId` | ID tác vụ |
| `status` | `processing` (đang xử lý) hoặc `ready` (hoàn tất) |
| `solution` | Kết quả nhận dạng; các trường khác nhau tùy loại tác vụ, xem trang của từng loại tác vụ |

Hãy dựa vào `errorId` và `errorCode` để xử lý kết quả, đừng phân tích nội dung văn bản của `errorDescription` vì nội dung này có thể thay đổi.

## Đồng bộ và bất đồng bộ

|  | Bất đồng bộ | Đồng bộ |
| --- | --- | --- |
| Những loại nào | Các loại trả về token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), trang thử thách Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Nhận dạng hình ảnh (tên kết thúc bằng `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` trả về | `taskId` | `status: "ready"` và `solution` |
| Cách lấy kết quả | Gọi `getTaskResult` mỗi 5 giây | Không cần kiểm tra thêm |

Mỗi loại thuộc nhóm nào, xem cột “Cách trả kết quả” trong [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).

## Polling

1.  Sau khi `createTask` trả về `taskId`, chờ 5 giây rồi gọi `getTaskResult`.
2.  Nếu trả về `status: "processing"` thì chờ thêm 5 giây rồi thử lại; nếu trả về `status: "ready"` thì kết quả nằm trong `solution`.
3.  Nếu trả về `errorId: 1` thì dừng polling tác vụ này và xử lý theo `errorCode`.

-   Các truy vấn lặp lại cho cùng một `taskId` trong vòng 5 giây sẽ trả về ngay `processing`; truy vấn dày hơn cũng không nhận được kết quả nhanh hơn.
-   Một tác vụ thường được xử lý tối đa 110 giây (một số ít loại là 180 đến 220 giây); quá thời gian sẽ trả về `ERROR_TASK_TIMEOUT` và tự động hoàn điểm.
-   Kết quả được lưu trên máy chủ khoảng 10 phút, sau đó `taskId` hết hiệu lực và truy vấn sẽ trả về `ERROR_TASKID_INVALID`.
-   Truy vấn kết quả không trừ điểm, chỉ trừ điểm khi tạo tác vụ.

## Ngôn ngữ của thông báo

Với các thông báo về tự động tạm dừng, bộ nhớ đệm tham số không hợp lệ và dừng polling, `errorDescription` chọn ngôn ngữ theo header `Accept-Language` của yêu cầu: bắt đầu bằng `zh` thì trả về tiếng Trung, các ngôn ngữ khác trả về tiếng Anh, nếu không có header này thì trả về cả tiếng Trung và tiếng Anh. Mô tả của các mã lỗi khác không bị ảnh hưởng.

## Bước tiếp theo

-   [createTask: tạo tác vụ](https://docs.yescaptcha.com/vi/api/create-task.md)
-   [getTaskResult: lấy kết quả](https://docs.yescaptcha.com/vi/api/get-task-result.md)
-   [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md): quá nhiều lỗi sẽ bị tạm dừng vài phút