# คำขอและการตอบกลับ

> ข้อกำหนดทั่วไปของ YesCaptcha API ได้แก่ POST JSON, การยืนยันตัวตนด้วย ClientKey, รูปแบบการตอบกลับด้วย errorId, งานแบบซิงโครนัสและแบบอะซิงโครนัส, polling ทุก 5 วินาที, timeout 110 วินาที, ผลลัพธ์เก็บไว้ประมาณ 10 นาที และภาษาของข้อความตาม Accept-Language

Source: https://docs.yescaptcha.com/th/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/

ทุกเมธอดรับ HTTPS `POST` พร้อม JSON (มีเพียง `/useragent` ที่เป็น `GET`) ยืนยันตัวตนด้วย `clientKey` ใน request body และตอบกลับเป็น JSON โดย `errorId` เป็น 0 หมายถึงสำเร็จ และเป็น 1 หมายถึงล้มเหลวพร้อม `errorCode` การแก้ CAPTCHA หนึ่งครั้งมีสองขั้นตอน: `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"}}'
```

-   Endpoint: `https://api.yescaptcha.com` (ทั่วโลก) หรือ `https://cn.yescaptcha.com` (จีน) ดูที่ [ที่อยู่สำหรับเชื่อมต่อ](https://docs.yescaptcha.com/th/getting-started/endpoints.md)
-   request body เป็น 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/th/api/errors.md) |
| `errorDescription` | คำอธิบายสาเหตุที่ล้มเหลวเป็นข้อความ |
| `taskId` | ID งาน |
| `status` | `processing` (กำลังประมวลผล) หรือ `ready` (เสร็จแล้ว) |
| `solution` | ผลลัพธ์การแก้ ฟิลด์ต่างกันตามประเภทงาน ดูในหน้าของแต่ละประเภทงาน |

ให้ตัดสินผลจาก `errorId` และ `errorCode` ไม่ควรแยกวิเคราะห์ข้อความใน `errorDescription` เพราะอาจมีการปรับเปลี่ยน

## แบบซิงโครนัสและแบบอะซิงโครนัส

|  | แบบอะซิงโครนัส | แบบซิงโครนัส |
| --- | --- | --- |
| ประเภทที่เกี่ยวข้อง | ประเภทที่คืนค่า token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), หน้าตรวจสอบของ Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | การจดจำภาพ (ชื่อลงท้ายด้วย `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` คืนค่า | `taskId` | `status: "ready"` และ `solution` |
| วิธีรับผลลัพธ์ | เรียก `getTaskResult` ทุก 5 วินาที | ไม่ต้องตรวจซ้ำ |

แต่ละประเภทเป็นแบบใด ดูที่คอลัมน์ “วิธีคืนผลลัพธ์” ใน [ประเภทงานและราคา](https://docs.yescaptcha.com/th/tasks.md)

## Polling

1.  หลังจาก `createTask` คืน `taskId` ให้รอ 5 วินาทีแล้วจึงเรียก `getTaskResult`
2.  ถ้าได้ `status: "processing"` ให้รออีก 5 วินาทีแล้วลองใหม่ ถ้าได้ `status: "ready"` ผลลัพธ์จะอยู่ใน `solution`
3.  ถ้าได้ `errorId: 1` ให้หยุด polling งานนี้ แล้วจัดการตาม `errorCode`

-   การตรวจซ้ำสำหรับ `taskId` เดียวกันภายใน 5 วินาทีจะได้ `processing` ทันที การตรวจถี่ขึ้นไม่ได้ทำให้ได้ผลลัพธ์เร็วขึ้น
-   โดยทั่วไปงานประมวลผลนานสุด 110 วินาที (บางประเภท 180 ถึง 220 วินาที) หากเกินเวลาจะคืน `ERROR_TASK_TIMEOUT` และคืนพอยต์อัตโนมัติ
-   ผลลัพธ์ถูกเก็บไว้ที่ฝั่งเซิร์ฟเวอร์ประมาณ 10 นาที หลังจากนั้น `taskId` จะหมดอายุ และการตรวจจะคืน `ERROR_TASKID_INVALID`
-   การตรวจผลลัพธ์ไม่หักพอยต์ จะหักเฉพาะตอนสร้างงาน

## ภาษาของข้อความ

สำหรับข้อความเกี่ยวกับการหยุดชั่วคราวอัตโนมัติ, แคชพารามิเตอร์ที่ไม่ถูกต้อง และการให้หยุด polling `errorDescription` จะเลือกภาษาตามส่วนหัว `Accept-Language` ของคำขอ ถ้าขึ้นต้นด้วย `zh` จะคืนเป็นภาษาจีน ภาษาอื่นคืนเป็นภาษาอังกฤษ และถ้าไม่มีส่วนหัวนี้จะคืนทั้งภาษาจีนและภาษาอังกฤษ คำอธิบายของรหัสข้อผิดพลาดอื่นไม่ได้รับผลกระทบ

## ขั้นตอนถัดไป

-   [createTask สร้างงาน](https://docs.yescaptcha.com/th/api/create-task.md)
-   [getTaskResult รับผลลัพธ์](https://docs.yescaptcha.com/th/api/get-task-result.md)
-   [ขีดจำกัดงานพร้อมกันและการหยุดชั่วคราวอัตโนมัติ](https://docs.yescaptcha.com/th/api/rate-limits.md): หากเกิดข้อผิดพลาดมากเกินไป จะถูกหยุดชั่วคราวไม่กี่นาที