Geetest Image Captcha

Overview

Geetest is a popular captcha system in China and Asian countries, using interactive challenges such as puzzle dragging and image recognition. We provide services to solve all types of Geetest Image (Geetest v3, Geetest v4, ...) on browsers, simulators, and phone farms.

1. Create Task

Image Submission Format

Request

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

Parameters

Request Example

POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "GeetestImageCaptchaTask",
    "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsKCwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT...|/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsKCwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT...|/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsKCwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT...",
    "subType": 7
  }
}

Response

{
  "errorId": 0,
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

2. Get Result

Request

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

Parameters

Request Example

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": "x1,y1,x2,y2,x3,y3"
}

Status Explanation

• errorId = 0 and status = ready: Successfully solved, read result in solution
• errorId = 1 and status = processing: Solving captcha, wait 1-2 seconds and try again
• errorId other than 0 and 1: System error, returns error code and description

Result Meaning

• solution: Return value depends on subType:
  • subType 3 (Grid Image): Cell indices to select, format i1,i2,... (e.g. 1,3,5) — index starts at 1, left-to-right, top-to-bottom
  • subType 7 (Object Selection): Pixel coordinates x1,y1,x2,y2,... — click in the order corresponding to displayed icons
  • subType "icon_crush" (Icon Crush): Pixel coordinates of all matching icons to crush — click each regardless of order
  • subType "slider" (Drag Slider): X offset in pixels to drag the slider piece

Integration Examples

import requests
import time
 
def solve_geetest_image(base64_images, sub_type=7, api_key='YOUR_API_KEY'):
    # base64_images: "icon1|icon2|icon3|background" - base64 string separated by |
    
    # Step 1: Create task
    create_task_url = 'https://api.achicaptcha.com/createTask'
    create_task_payload = {
        'clientKey': api_key,
        'task': {
            'type': 'GeetestImageCaptchaTask',
            'image': base64_images,
            'subType': sub_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']
    
    # Step 2: Get result
    get_result_url = 'https://api.achicaptcha.com/getTaskResult'
    
    while True:
        time.sleep(2)  # Wait 2 seconds
        
        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'] not in [0, 1]:
            raise Exception(result['errorDescription'])
        
        if result['status'] == 'ready':
            return result['solution']  # "x1,y1,x2,y2,x3,y3"
        
        # If status == 'processing', continue loop
 
# Usage
# Assume you have base64 images
icon1_base64 = '/9j/4AAQSkZJRgABAQEASABIAAD...'
icon2_base64 = '/9j/4AAQSkZJRgABAQEASABIAAD...'
icon3_base64 = '/9j/4AAQSkZJRgABAQEASABIAAD...'
background_base64 = '/9j/4AAQSkZJRgABAQEASABIAAD...'
 
base64_images = f'{icon1_base64}|{icon2_base64}|{icon3_base64}|{background_base64}'
solution = solve_geetest_image(base64_images, 7, 'YOUR_API_KEY')
print('Geetest coordinates:', solution)  # "x1,y1,x2,y2,x3,y3"
 
# Parse coordinates and use
coords = [int(c) for c in solution.split(',')]
for i in range(0, len(coords), 2):
    x, y = coords[i], coords[i + 1]
    print(f'Click at ({x}, {y})')
    # Perform click at coordinates (x, y)

Common Error Codes

Best Practices

1. Prepare Images in Correct Format

• All images must be encoded to base64
• Image order: icon_1|icon_2|...|icon_n|background
• Base64 images are separated by | character
• Ensure background image is the last in the string
• For subType 3 (Grid Image): send icon image + grid background, format icon|background
• For subType 7 (Object Selection): send icons + background, format icon_1|icon_2|...|background
• For subType "icon_crush": send reference icon + grid background, format icon|background
• For subType "slider": send background image only as a single base64 string

2. Use Results Correctly

• Result returned is a coordinate string: x1,y1,x2,y2,x3,y3,...
• Each pair (x, y) is pixel coordinates on the background image
• For subType 3 (Grid Image): result is cell indices (1-based) — tap the grid cells at those positions
• For subType 7 (Object Selection): click coordinates in the order corresponding to displayed icons
• For subType "icon_crush": click all returned coordinates — order does not matter
• For subType "slider": drag the slider piece by the returned x offset in pixels
• Click precisely at coordinates to complete captcha

3. Polling Interval

• Wait at least 1-2 seconds between result checks
• Don't spam API with too many consecutive requests
• Set timeout to avoid infinite loops (recommended 60 seconds)

4. Error Handling

• Check errorId = 1 for processing status
• Retry for temporary errors (errorId = 6, 7)
• Create new task if current task fails
• Limit maximum retry attempts

5. API Key Security

• Don't hardcode API key in code
• Use environment variables
• Don't expose API key on client-side
• Make API calls from backend/server

Useful links:

• Achicaptcha Homepage (opens in a new tab)
• Introduction to Achicaptcha
• Install for Firefox (opens in a new tab)
• Install for Chrome (opens in a new tab)