Gambar hCAPTCHA
Ikhtisar
Gambar hCAPTCHA (hCaptcha Image) adalah jenis captcha yang mengharuskan pengguna untuk mengidentifikasi dan memilih gambar sesuai dengan persyaratan, mengklik titik, atau menyeret gambar.
Token hCaptcha banyak digunakan di berbagai situs web seperti Cloudflare, Discord, OpenSea, dan banyak layanan lainnya untuk melindungi dari bot.

1. Buat Tugas
Permintaan
POST https://api.achicaptcha.com/createTask
Parameter
| Nama Parameter | Tipe Data | Wajib? | Deskripsi |
|---|---|---|---|
clientKey | string | ya | Kunci API |
task.type | string | ya | HCaptchaImageTask |
task.subType | string | ya | Nilai sama dengan 0 |
task.image | string | ya | Daftar gambar base64 yang dipisahkan oleh ` |
task.other | string | ya | Pertanyaan |
Contoh Permintaan
POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "KUNCI_API_ANDA",
"task": {
"type": "HCaptchaImageTask",
"subType": "0",
"image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|...(9 gambar base64 digabung dengan |)",
"other": "Please identify and click on all pictures featuring a bird|9|grid"
}
}Respons
Jika berhasil, server mengembalikan errorId = 0 dan taskId
{
"errorId": 0,
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Contoh Gambar untuk Dikirim ke Server Penyelesaian Captcha
Tip: Untuk kualitas pengenalan captcha terbaik, crop gambar Anda seperti yang ditunjukkan pada kotak merah dan ungu di gambar contoh di bawah ini.
Pastikan resolusi gambar hasil crop minimal 500–600 piksel lebar/tinggi agar mendapatkan hasil terbaik.

2. Dapatkan Hasil
Permintaan
POST https://api.achicaptcha.com/getTaskResult
Parameter
| Nama Parameter | Tipe Data | Wajib? | Deskripsi |
|---|---|---|---|
clientKey | string | ya | Kunci API |
taskId | string | ya | TaskId yang diperoleh dari (1) |
Contoh Permintaan
POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "KUNCI_API_ANDA",
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Respons
{
"errorId": 0,
"status": "ready",
// solution: koordinat titik yang akan diklik (x1,y1,x2,y2,...)
"solution": "20,30,40,50"
}Contoh Integrasi
import requests
import time
import base64
def image_url_to_base64(url):
"""Konversi URL gambar ke base64"""
response = requests.get(url)
return base64.b64encode(response.content).decode('utf-8')
def solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, api_key='YOUR_API_KEY'):
# Langkah 1: Buat tugas
create_task_url = 'https://api.achicaptcha.com/createTask'
create_task_payload = {
'clientKey': api_key,
'task': {
'type': 'HCaptchaImageTask',
'subType': '0',
'image': image_base64_list,
'other': f'{question}|{image_count}|{captcha_type}'
}
}
response = requests.post(create_task_url, json=create_task_payload)
result = response.json()
if result['errorId'] != 0:
raise Exception(result['errorDescription'])
task_id = result['taskId']
# Langkah 2: Dapatkan hasil
get_result_url = 'https://api.achicaptcha.com/getTaskResult'
while True:
time.sleep(2) # Tunggu 2 detik
get_result_payload = {
'clientKey': api_key,
'taskId': task_id
}
response = requests.post(get_result_url, json=get_result_payload)
result = response.json()
if result['errorId'] != 0:
raise Exception(result['errorDescription'])
if result['status'] == 'ready':
return result['solution']['gRecaptchaResponse']
# Jika status == 'processing', lanjutkan loop
# Penggunaan
# Konversi URL gambar ke base64
image_urls = [
'https://example.com/image1.jpg',
'https://example.com/image2.jpg',
# ... gambar lainnya
'https://example.com/image9.jpg'
]
base64_images = [image_url_to_base64(url) for url in image_urls]
image_base64_list = '|'.join(base64_images)
question = 'Please identify and click on all pictures featuring a bird'
image_count = 9
captcha_type = 'grid' # atau 'bbox'
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'YOUR_API_KEY')
print('hCaptcha token:', token)Kode Kesalahan Umum
| Kode Kesalahan | Deskripsi | Catatan |
|---|---|---|
| 0 | sukses | Sukses |
| 1 | sedang memproses | Sedang memproses |
| 2 | bidang wajib hilang | Bidang wajib hilang, periksa parameter lagi |
| 3 | tugas tidak didukung | Jenis tugas tidak didukung |
| 4 | pembuatan tugas gagal | Pembuatan tugas gagal |
| 5 | kunci klien tidak ada | Kunci API tidak ada, periksa kunci API lagi |
| 6 | saldo akun tidak cukup | Saldo akun tidak cukup, tambahkan kredit lagi |
| 7 | tugas gagal, harap buat tugas baru | Tugas gagal, harap buat tugas baru |
| 8 | ID tugas tidak ada | ID tugas tidak ada |
Praktik Terbaik
Untuk hasil terbaik saat menggunakan API Achicaptcha, ikuti prinsip-prinsip ini:
1. Validasi Data Masukan
- Periksa daftar gambar sebelum mengirim permintaan
- Gambar harus dienkode ke base64 sebelum dikirim
- Pastikan format yang benar:
base64_image1|base64_image2|...|base64_image9atau dengan gambar sampel tambahan - Verifikasi pertanyaan dan jenis captcha (grid/bbox) akurat
- Jumlah gambar harus sesuai dengan jumlah sebenarnya gambar dalam grid
2. Tangani Beberapa Putaran
- hCaptcha mungkin memerlukan penyelesaian beberapa putaran berturut-turut
- API Achicaptcha secara otomatis menangani putaran ini
- Waktu penyelesaian mungkin lebih lama daripada captcha teks (15-30 detik)
3. Interval Polling
- Tunggu setidaknya 2 detik di antara pemeriksaan hasil
- Jangan spam API dengan terlalu banyak permintaan berturut-turut
- Tetapkan batas waktu untuk menghindari loop tak terbatas (disarankan 120 detik)
4. Logika Percobaan Ulang
- Terapkan percobaan ulang untuk kesalahan sementara seperti
ERROR_NO_SLOT_AVAILABLE - Gunakan backoff eksponensial saat mencoba ulang
- Batasi upaya percobaan ulang maksimum
5. Keamanan Kunci API
- Jangan lakukan hardcode kunci API dalam kode
- Gunakan variabel lingkungan
- Jangan mengekspos kunci API di sisi klien
Tautan berguna: