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

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

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.
• 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:

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

Thất bại:

{
  "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
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á.

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ụ
• getTaskResult: lấy kết quả
• Giới hạn đồng thời và tự động tạm dừng: quá nhiều lỗi sẽ bị tạm dừng vài phút