Botion Grid Captcha

Overview

Botion is a grid selection captcha: the page shows a reference sample image and a 3×3 grid of tiles. The solver must return which grid cells match the reference (0-based indices, row-major: left-to-right, top-to-bottom).

1. Create Task

Image Submission Format

Sample image

Grid image

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": "GridCaptcha",
    "subType": "botion",
    "image": "BASE64_SAMPLE_IMAGE|BASE64_GRID_IMAGE",
    "other": "3|3"
  }
}

Response

{
  "errorId": 0,
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "click": "0,2,5"
  }
}

Status Explanation

• errorId = 0 and status = ready: Successfully solved, read cell indices in solution.click
• errorId = 0 and status = processing: Still solving, wait 2 seconds and poll again
• errorId > 0: System error, check errorCode and errorDescription

Integration Examples

import requests
import base64
import time
 
def solve_botion(sample_path, grid_path, api_key='YOUR_API_KEY', other='3|3'):
    with open(sample_path, 'rb') as f:
        sample_b64 = base64.b64encode(f.read()).decode()
    with open(grid_path, 'rb') as f:
        grid_b64 = base64.b64encode(f.read()).decode()
 
    # Step 1: Create task
    create_resp = requests.post(
        'https://api.achicaptcha.com/createTask',
        json={
            'clientKey': api_key,
            'task': {
                'type': 'GridCaptcha',
                'subType': 'botion',
                'image': f'{sample_b64}|{grid_b64}',
                'other': other
            }
        }
    )
    result = create_resp.json()
 
    if result['errorId'] != 0:
        raise Exception(result['errorDescription'])
 
    task_id = result['taskId']
 
    # Step 2: Poll for result
    while True:
        time.sleep(2)
        poll_resp = requests.post(
            'https://api.achicaptcha.com/getTaskResult',
            json={'clientKey': api_key, 'taskId': task_id}
        )
        result = poll_resp.json()
 
        if result['errorId'] != 0:
            raise Exception(result['errorDescription'])
 
        if result['status'] == 'ready':
            return result['solution']['click']  # e.g. "0,2,5"
 
# Usage
indices = solve_botion('sample.png', 'grid.png', 'YOUR_API_KEY')
print('Cells to click:', indices)

Common Error Codes

Best Practices

1. Image Order

• Always send the sample (reference) image first, then |, then the grid image
• Do not include the data:image/...;base64, prefix — raw Base64 only
• Ensure both images are fully loaded and encoded before sending

2. task.other Parameter

• Format is topk|grid_size (e.g. 3|3)
• Omitting it defaults to 3|3, but always set it explicitly to avoid unexpected behaviour
• Wrong grid_size will break the 0-based index mapping in solution.click

3. Polling Interval

• Wait at least 2 seconds between result checks
• Do not spam the API with consecutive requests
• Set a timeout to avoid infinite loops (recommended: 60 seconds)

4. Result Processing

• solution.click is a comma-separated string of 0-based cell indices (row-major, left-to-right, top-to-bottom)
• Split by , and convert to integers before clicking the corresponding grid cells

5. Retry Logic

• Implement retry for temporary errors like ERROR_NO_SLOT_AVAILABLE
• Use exponential backoff when retrying
• Limit the maximum number of retry attempts

6. API Key Security

• Do not hardcode your API key in source code
• Use environment variables or a secrets manager
• Never expose the API key on the client side

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)