hCAPTCHA Image
Pangkalahatang-ideya
Ang hCaptcha Image ay isang uri ng captcha na nangangailangan ng mga user na tukuyin at piliin ang mga imahe ayon sa mga kinakailangan, mag-click ng mga punto, o mag-drag ng mga imahe.
Ang hCaptcha Token ay malawakang ginagamit sa maraming website tulad ng Cloudflare, Discord, OpenSea at marami pang ibang serbisyo upang protektahan laban sa mga bot.

1. Lumikha ng Gawain
Request
POST https://api.achicaptcha.com/createTask
Mga Parameter
| Pangalan ng Parameter | Uri ng Data | Kailangan? | Paglalarawan |
|---|---|---|---|
clientKey | string | oo | Api key |
task.type | string | oo | HCaptchaImageTask |
task.subType | string | oo | Value ay katumbas ng 0 |
task.image | string | oo | Listahan ng mga base64 image na pinaghihiwalay ng |base64_question1|base64_question2|...|base64_question9|base64_sample1|base64_sample2|...|base64_sampleNTandaan: Ang mga sample image ay maaaring naroon o wala. Ang mga imahe ay dapat na naka-encode sa base64 |
task.other | string | oo | Tanong|Bilang ng imahe|Uri ng Captcha Halimbawa: "Please identify and click on all pictures featuring a bird|9|grid"- Tanong: "Please identify and click on all pictures featuring a bird" - Bilang ng imahe: 9 (Bilangin lang ang mga imahe sa question grid, hindi ang sample images)- Uri ng Captcha: grid (pumili ng mga cell sa 9 na cell na nakakatugon sa kondisyon) o bbox (mag-click ng isa/maraming punto o mag-drag upang markahan ang isang bagay na nakakatugon sa kondisyon) o drag (mag-drag ng isa/maraming piraso ng puzzle upang lumikha ng kumpletong imahe) |
Halimbawa ng Request
POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "HCaptchaImageTask",
"subType": "0",
"image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|...(9 base64 images joined by |)",
"other": "Please identify and click on all pictures featuring a bird|9|grid"
}
}Response
Kapag matagumpay, ibabalik ng server ang errorId = 0 at taskId
{
"errorId": 0,
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Mga Sample ng Larawan na Ipasa sa Captcha Solving Server
Tip: Para sa pinakamahusay na kalidad ng pagkilala ng captcha, i-crop ang iyong larawan tulad ng ipinapakita sa mga pulang at lilang kahon sa mga sample na larawan sa ibaba.
Siguraduhing ang naka-crop na larawan ay may resolution na hindi bababa sa 500–600 pixels ang lapad/taas upang makakuha ng pinakamagandang resulta.

2. Kunin ang Resulta
Request
POST https://api.achicaptcha.com/getTaskResult
Mga Parameter
| Pangalan ng Parameter | Uri ng Data | Kailangan? | Paglalarawan |
|---|---|---|---|
clientKey | string | oo | Api key |
taskId | string | oo | TaskId na nakuha mula sa (1) |
Halimbawa ng Request
POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "YOUR_API_KEY",
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Response
{
"errorId": 0,
"status": "ready",
// solution: coordinates of points to click (x1,y1,x2,y2,...)
"solution": "20,30,40,50"
}Paliwanag sa Status
errorId = 0atstatus = ready: Matagumpay na nalutas, basahin ang resulta sasolution.gRecaptchaResponseerrorId = 0atstatus = processing: Nilulutas ang captcha, maghintay ng 2 segundo at subukang mulierrorId > 0: Error sa system, nagbabalik ng error code at paglalarawan
Mga Halimbawa ng Integrasyon
import requests
import time
import base64
def image_url_to_base64(url):
"""Convert image URL to 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'):
# Hakbang 1: Lumikha ng gawain
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']
# Hakbang 2: Kunin ang resulta
get_result_url = 'https://api.achicaptcha.com/getTaskResult'
while True:
time.sleep(2) # Maghintay ng 2 segundo
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']
# Kung status == 'processing', ipagpatuloy ang loop
# Paggamit
# Convert image URLs to base64
image_urls = [
'https://example.com/image1.jpg',
'https://example.com/image2.jpg',
# ... other images
'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' # o 'bbox'
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'YOUR_API_KEY')
print('hCaptcha token:', token)Karaniwang Error Codes
| Error Code | Paglalarawan | Mga Tala |
|---|---|---|
| 0 | success | Tagumpay |
| 1 | processing | Pinoproseso |
| 2 | missing required fields | Kulang ang mga kinakailangang field, suriin muli ang mga parameter |
| 3 | task not supported | Hindi suportado ang uri ng gawain |
| 4 | task creation failed | Nabigo ang paglikha ng gawain |
| 5 | client key does not exist | Hindi umiiral ang API key, suriin muli ang API key |
| 6 | insufficient account balance | Hindi sapat ang balanse ng account, magdagdag ng credits |
| 7 | task failed, please create a new task | Nabigo ang gawain, mangyaring lumikha ng bagong gawain |
| 8 | task ID does not exist | Hindi umiiral ang Task ID |
Pinakamahuhusay na Kasanayan
Para sa pinakamahusay na mga resulta kapag gumagamit ng Achicaptcha API, sundin ang mga prinsipyong ito:
1. I-validate ang Input Data
- Suriin ang listahan ng imahe bago magpadala ng request
- Ang mga imahe ay dapat na naka-encode sa base64 bago ipadala
- Tiyaking tama ang format:
base64_image1|base64_image2|...|base64_image9o may karagdagang sample images - I-verify na ang tanong at uri ng captcha (grid/bbox) ay tumpak
- Ang bilang ng imahe ay dapat tumugma sa aktwal na bilang ng mga imahe sa grid
2. Hawakan ang Maraming Rounds
- Ang hCaptcha ay maaaring mangailangan ng paglutas ng maraming magkakasunod na round
- Awtomatikong hinahawakan ng Achicaptcha API ang mga round na ito
- Ang oras ng paglutas ay maaaring mas mahaba kaysa sa text captcha (15-30 segundo)
3. Interval ng Polling
- Maghintay ng hindi bababa sa 2 segundo sa pagitan ng mga pagsusuri ng resulta
- Huwag i-spam ang API ng masyadong maraming magkakasunod na kahilingan
- Magtakda ng timeout upang maiwasan ang mga infinite loop (inirerekomenda ang 120 segundo)
4. Logic ng Pag-retry
- Ipatupad ang retry para sa mga pansamantalang error tulad ng
ERROR_NO_SLOT_AVAILABLE - Gumamit ng exponential backoff kapag nagre-retry
- Limitahan ang maximum na mga pagsubok sa pag-retry
5. Seguridad ng API Key
- Huwag i-hardcode ang API key sa code
- Gumamit ng mga environment variable
- Huwag ilantad ang API key sa client-side
Mga Kapaki-pakinabang na link: