Skip to content
API
网格验证码
Botion

Botion Grid Captcha

概述

Botion 是一种网格选择验证码：页面显示一张参考样本图片和一个 3×3 网格。解题器需返回与参考图片匹配的网格单元格（0-based 索引，行优先：从左到右，从上到下）。

🔲

task.image 字段编码两个 Base64 载荷，以 | 连接——样本图片在前，网格图片在后。

Botion captcha UI example

1. 创建任务

图片提交格式

样本图片 Botion request payload (sample | grid)

网格图片 Botion request payload (sample | grid)

请求

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

参数

参数名称数据类型是否必需描述
clientKeystring是API 密钥
task.typestring是GridCaptcha
task.subTypestring是botion
task.imagestring是BASE64_SAMPLE_IMAGE|BASE64_GRID_IMAGE — 样本图片在前，然后 |，再接 3×3 网格图片（均为 Base64，无 data: 前缀）
task.otherstring否topk|grid_size。省略时默认为 3|3

请求示例

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"
  }
}

响应

成功时，服务器返回 errorId = 0 和 taskId

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

2. 获取结果

请求

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

参数

参数名称数据类型是否必需描述
clientKeystring是API 密钥
taskIdstring是从步骤 (1) 获取的 TaskId

请求示例

POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

响应

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

solution.click 是以逗号分隔的 0-based 单元格索引字符串（行优先），表示需要点击的 3×3 网格单元格。

状态说明

  • errorId = 0 且 status = ready：解决成功，在 solution.click 中读取单元格索引
  • errorId = 0 且 status = processing：仍在解决中，等待 2 秒后再次轮询
  • errorId > 0：系统错误，检查 errorCode 和 errorDescription

集成示例

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()
 
    # 步骤1：创建任务
    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']
 
    # 步骤2：轮询结果
    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']  # 例如："0,2,5"
 
# 使用方法
indices = solve_botion('sample.png', 'grid.png', 'YOUR_API_KEY')
print('需要点击的单元格：', indices)

常见错误代码

错误代码描述备注
0success成功
1processing处理中
2missing required fields缺少必填字段，请再次检查参数
3task not supported不支持的任务类型
4task creation failed任务创建失败
5client key does not existAPI 密钥不存在，请再次检查
6insufficient account balance账户余额不足，请充值
7task failed, please create a new task任务失败，请创建新任务
8task ID does not exist任务 ID 不存在

最佳实践

为了在使用 Achicaptcha API 处理 Botion Grid Captcha 时获得最佳效果，请遵循以下原则：

1. 图片顺序

  • 始终将样本（参考）图片放在前面，然后是 |，再接网格图片
  • 不要包含 data:image/...;base64, 前缀——仅使用纯 Base64
  • 确保两张图片在发送前都已完全加载并编码

2. task.other 参数

  • 格式为 topk|grid_size（例如 3|3）
  • 省略时默认为 3|3，但始终显式设置以避免意外行为
  • 错误的 grid_size 将破坏 solution.click 中的 0-based 索引映射

3. 轮询间隔

  • 每次结果检查之间至少等待 2 秒
  • 不要用连续请求轰炸 API
  • 设置超时以避免无限循环（建议：60 秒）

4. 结果处理

  • solution.click 是以逗号分隔的 0-based 单元格索引字符串（行优先，从左到右，从上到下）
  • 按 , 分割并转换为整数，然后点击对应的网格单元格

5. 重试逻辑

  • 对临时错误（如 ERROR_NO_SLOT_AVAILABLE）实施重试
  • 重试时使用指数退避
  • 限制最大重试次数

6. API 密钥安全

  • 不要在源代码中硬编码 API 密钥
  • 使用环境变量或密钥管理器
  • 切勿在客户端暴露 API 密钥

有用的链接：

AmazonTencent