Skip to content
API
hCAPTCHA
Larawan

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.

hCaptcha Token BBox

1. Lumikha ng Gawain

Request

POST https://api.achicaptcha.com/createTask

Mga Parameter

Pangalan ng ParameterUri ng DataKailangan?Paglalarawan
clientKeystringooApi key
task.typestringooHCaptchaImageTask
task.subTypestringooValue ay katumbas ng 0
task.imagestringooListahan ng mga base64 image na pinaghihiwalay ng |
base64_question1|base64_question2|...|base64_question9|base64_sample1|base64_sample2|...|base64_sampleN
Tandaan: Ang mga sample image ay maaaring naroon o wala. Ang mga imahe ay dapat na naka-encode sa base64
task.otherstringooTanong|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.

Halimbawa ng Request Multi click

2. Kunin ang Resulta

Request

POST https://api.achicaptcha.com/getTaskResult

Mga Parameter

Pangalan ng ParameterUri ng DataKailangan?Paglalarawan
clientKeystringooApi key
taskIdstringooTaskId 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 = 0 at status = ready: Matagumpay na nalutas, basahin ang resulta sa solution.gRecaptchaResponse
  • errorId = 0 at status = processing: Nilulutas ang captcha, maghintay ng 2 segundo at subukang muli
  • errorId > 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 CodePaglalarawanMga Tala
0successTagumpay
1processingPinoproseso
2missing required fieldsKulang ang mga kinakailangang field, suriin muli ang mga parameter
3task not supportedHindi suportado ang uri ng gawain
4task creation failedNabigo ang paglikha ng gawain
5client key does not existHindi umiiral ang API key, suriin muli ang API key
6insufficient account balanceHindi sapat ang balanse ng account, magdagdag ng credits
7task failed, please create a new taskNabigo ang gawain, mangyaring lumikha ng bagong gawain
8task ID does not existHindi 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_image9 o 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: