Skip to content
API
hCAPTCHA
Imagem

Imagem hCAPTCHA

Visão Geral

hCaptcha Image é um tipo de captcha que exige que os usuários identifiquem e selecionem imagens de acordo com os requisitos, cliquem em pontos ou arrastem imagens.

🖼️

hCaptcha Token é amplamente utilizado em muitos sites como Cloudflare, Discord, OpenSea e muitos outros serviços para proteção contra bots.

hCaptcha Token BBox

1. Criar Tarefa

Solicitação

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

Parâmetros

Nome do ParâmetroTipo de DadosObrigatório?Descrição
clientKeystringsimChave da API (Api key)
task.typestringsimHCaptchaImageTask
task.subTypestringsimValor igual a 0
task.imagestringsimLista de imagens base64 separadas por `
task.otherstringsimPergunta

Exemplo de Solicitação

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

Resposta

Em caso de sucesso, o servidor retorna errorId = 0 e taskId

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

Exemplos de Imagens para Enviar ao Servidor de Resolução de Captcha

Dica: Para obter a melhor qualidade de reconhecimento de captcha, recorte sua imagem conforme mostrado nas caixas vermelha e roxa nos exemplos abaixo.
Certifique-se de que a imagem recortada tenha pelo menos 500–600 pixels de largura/altura para garantir melhores resultados.

Exemplo de Solicitação Multi clique

2. Obter Resultado

Solicitação

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

Parâmetros

Nome do ParâmetroTipo de DadosObrigatório?Descrição
clientKeystringsimChave da API (Api key)
taskIdstringsimTaskId obtido em (1)

Exemplo de Solicitação

POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

Resposta

{
  "errorId": 0,
  "status": "ready",
  "solution": "20,30,40,50"
}

Nota: solution contém coordenadas dos pontos a serem clicados (x1,y1,x2,y2,...)

Explicação do Status

  • errorId = 0 e status = ready: Resolvido com sucesso, leia o resultado em solution.gRecaptchaResponse
  • errorId = 0 e status = processing: Resolvendo captcha, aguarde 2 segundos e tente novamente
  • errorId > 0: Erro do sistema, retorna código de erro e descrição

Exemplos de Integração

import requests
import time
import base64
 
 
def image_url_to_base64(url):
    """Converter URL da imagem para 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'):
    # Passo 1: Criar tarefa
    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']
    
    # Passo 2: Obter resultado
    get_result_url = 'https://api.achicaptcha.com/getTaskResult'
    
    while True:
        time.sleep(2)  # Aguarde 2 segundos
        
        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']
        
        # Se status == 'processing', continue o loop
 
# Uso
# Converter URLs de imagem para base64
image_urls = [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg',
    # ... outras imagens
    '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'  # ou 'bbox'
 
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'YOUR_API_KEY')
print('hCaptcha token:', token)

Códigos de Erro Comuns

Código de ErroDescriçãoNotas
0successSucesso
1processingProcessando
2missing required fieldsCampos obrigatórios ausentes, verifique os parâmetros novamente
3task not supportedTipo de tarefa não suportado
4task creation failedFalha na criação da tarefa
5client key does not existChave de API não existe, verifique a chave de API novamente
6insufficient account balanceSaldo da conta insuficiente, adicione mais créditos
7task failed, please create a new taskTarefa falhou, por favor crie uma nova tarefa
8task ID does not existID da tarefa não existe

Melhores Práticas

Para obter os melhores resultados ao usar a API Achicaptcha, siga estes princípios:

1. Validar Dados de Entrada

  • Verifique a lista de imagens antes de enviar a solicitação
  • As imagens devem ser codificadas em base64 antes de enviar
  • Garanta o formato correto: base64_image1|base64_image2|...|base64_image9 ou com imagens de exemplo adicionais
  • Verifique se a pergunta e o tipo de captcha (grid/bbox/drag) estão corretos
  • A contagem de imagens deve corresponder ao número real de imagens na grade

2. Gerenciar Múltiplas Rodadas

  • hCaptcha pode exigir a resolução de múltiplas rodadas consecutivas
  • A API Achicaptcha lida automaticamente com essas rodadas
  • O tempo de resolução pode ser maior do que o captcha de texto (15-30 segundos)

3. Intervalo de Polling

  • Aguarde pelo menos 2 segundos entre as verificações de resultado
  • Não sobrecarregue a API com muitas solicitações consecutivas
  • Defina um timeout para evitar loops infinitos (recomendado 120 segundos)

4. Lógica de Tentativa (Retry)

  • Implemente novas tentativas para erros temporários como ERROR_NO_SLOT_AVAILABLE
  • Use backoff exponencial ao tentar novamente
  • Limite o número máximo de tentativas de repetição

5. Segurança da Chave de API

  • Não incorpore a chave de API diretamente no código (hardcode)
  • Use variáveis de ambiente
  • Não exponha a chave de API no lado do cliente (client-side)

Links Úteis: