Permintaan dan respons

Semua method menggunakan HTTPS POST dengan body JSON (hanya /useragent yang GET), diautentikasi dengan clientKey di body, dan mengembalikan JSON: errorId bernilai 0 berarti berhasil, 1 berarti gagal dan disertai errorCode. Menyelesaikan satu captcha terdiri dari dua langkah: createTask membuat tugas, lalu getTaskResult dipanggil setiap 5 detik untuk memeriksa hasil. Jenis sinkron langsung mengembalikan hasil di createTask.

Permintaan

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 (global) atau https://cn.yescaptcha.com (Tiongkok), lihat Alamat akses.
• Body berupa JSON, dikirim dengan header Content-Type: application/json, maksimal 6 MB. JSON tidak boleh berisi komentar.
• Setiap permintaan harus menyertakan clientKey, salin lengkap sesuai nilai yang tampil di Dasbor.

Perhatian

Pada Python requests gunakan json=data, bukan data=data. Yang terakhir mengirim form dan akan mengembalikan ERROR_TASK_ABSENT atau ERROR_REQUIRED_FIELDS.

Respons

Berhasil:

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

Gagal:

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

Field	Keterangan
errorId	0 berhasil, 1 gagal
errorCode	Kode error saat gagal; arti dan cara penanganannya ada di Kode error
errorDescription	Keterangan teks tentang penyebab kegagalan
taskId	ID tugas
status	processing (sedang diproses) atau ready (selesai)
solution	Hasil pengenalan; field-nya berbeda menurut jenis tugas, lihat halaman masing-masing jenis tugas

Gunakan errorId dan errorCode untuk menentukan hasil, jangan mengurai teks errorDescription karena bisa berubah.

Sinkron dan asinkron

	Asinkron	Sinkron
Jenis apa saja	Jenis yang mengembalikan token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), halaman verifikasi Cloudflare, ImageToTextTask, ImageToTextTaskM1	Pengenalan gambar (nama berakhiran Classification), ImageToTextTaskOcrBase, ImageToTextTaskMuggle
createTask mengembalikan	taskId	status: "ready" dan solution
Cara mendapat hasil	Panggil getTaskResult setiap 5 detik	Tidak perlu memeriksa lagi

Kolom “Cara pengembalian” di Jenis tugas dan harga menunjukkan mana yang berlaku untuk setiap jenis.

Polling

1. Setelah createTask mengembalikan taskId, tunggu 5 detik lalu panggil getTaskResult.
2. Jika mengembalikan status: "processing", tunggu 5 detik lagi lalu coba kembali; jika status: "ready", hasilnya ada di solution.
3. Jika mengembalikan errorId: 1, hentikan polling untuk tugas ini dan tangani sesuai errorCode.

• Permintaan berulang untuk taskId yang sama dalam 5 detik langsung mengembalikan processing; memeriksa lebih sering tidak membuat hasil lebih cepat didapat.
• Sebuah tugas umumnya diproses paling lama 110 detik (beberapa jenis 180 sampai 220 detik); jika melewati batas, mengembalikan ERROR_TASK_TIMEOUT dan poin dikembalikan otomatis.
• Hasil disimpan di server sekitar 10 menit; setelah itu taskId tidak berlaku dan pemeriksaan mengembalikan ERROR_TASKID_INVALID.
• Memeriksa hasil tidak memotong poin; pemotongan poin hanya terjadi saat membuat tugas.

Bahasa teks pesan

Untuk pesan jeda otomatis, cache parameter tidak valid, dan penghentian polling, errorDescription memilih bahasa berdasarkan header Accept-Language: jika diawali zh dikembalikan bahasa Mandarin, bahasa lain dikembalikan bahasa Inggris, dan jika header ini tidak ada, keduanya dikembalikan. Keterangan untuk kode error lain tidak terpengaruh.

Langkah berikutnya

• createTask: membuat tugas
• getTaskResult: mengambil hasil
• Batas tugas bersamaan dan jeda otomatis: terlalu banyak error akan menyebabkan jeda beberapa menit