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.

1. Criar Tarefa
Solicitação
POST https://api.achicaptcha.com/createTask
Parâmetros
| Nome do Parâmetro | Tipo de Dados | Obrigatório? | Descrição |
|---|---|---|---|
clientKey | string | sim | Chave da API (Api key) |
task.type | string | sim | HCaptchaImageTask |
task.subType | string | sim | Valor igual a 0 |
task.image | string | sim | Lista de imagens base64 separadas por ` |
task.other | string | sim | Pergunta |
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.

2. Obter Resultado
Solicitação
POST https://api.achicaptcha.com/getTaskResult
Parâmetros
| Nome do Parâmetro | Tipo de Dados | Obrigatório? | Descrição |
|---|---|---|---|
clientKey | string | sim | Chave da API (Api key) |
taskId | string | sim | TaskId 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 = 0estatus = ready: Resolvido com sucesso, leia o resultado emsolution.gRecaptchaResponseerrorId = 0estatus = processing: Resolvendo captcha, aguarde 2 segundos e tente novamenteerrorId > 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 Erro | Descrição | Notas |
|---|---|---|
| 0 | success | Sucesso |
| 1 | processing | Processando |
| 2 | missing required fields | Campos obrigatórios ausentes, verifique os parâmetros novamente |
| 3 | task not supported | Tipo de tarefa não suportado |
| 4 | task creation failed | Falha na criação da tarefa |
| 5 | client key does not exist | Chave de API não existe, verifique a chave de API novamente |
| 6 | insufficient account balance | Saldo da conta insuficiente, adicione mais créditos |
| 7 | task failed, please create a new task | Tarefa falhou, por favor crie uma nova tarefa |
| 8 | task ID does not exist | ID 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_image9ou 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: