เอกสารอ้างอิง API

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

หน้านี้แปลด้วยเครื่องจากเวอร์ชันภาษาจีน อาจมีข้อผิดพลาด โปรดยึดเวอร์ชันภาษาจีนเป็นหลัก

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

Endpoint: https://api.yescaptcha.com (ทั่วโลก) หรือ https://cn.yescaptcha.com (จีน) ดูที่ ที่อยู่สำหรับเชื่อมต่อ
request body เป็น JSON ส่งพร้อมส่วนหัว Content-Type: application/json และต้องไม่เกิน 6 MB ใน JSON เขียนคอมเมนต์ไม่ได้
ทุกคำขอต้องมี clientKey ให้คัดลอกค่าที่แสดงในแดชบอร์ดมาให้ครบ

การตอบกลับ

สำเร็จ:

{
  "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, `ImageToTextTask`, `ImageToTextTaskM1`	การจดจำภาพ (ชื่อลงท้ายด้วย `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle`
`createTask` คืนค่า	`taskId`	`status: "ready"` และ `solution`
วิธีรับผลลัพธ์	เรียก `getTaskResult` ทุก 5 วินาที	ไม่ต้องตรวจซ้ำ

แต่ละประเภทเป็นแบบใด ดูที่คอลัมน์ “วิธีคืนผลลัพธ์” ใน ประเภทงานและราคา

Polling

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

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

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

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

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

createTask สร้างงาน
getTaskResult รับผลลัพธ์
ขีดจำกัดงานพร้อมกันและการหยุดชั่วคราวอัตโนมัติ: หากเกิดข้อผิดพลาดมากเกินไป จะถูกหยุดชั่วคราวไม่กี่นาที