hCaptcha API de Reconhecimento de Imagens

Este documento apresentará uma descrição da API de reconhecimento de imagens hCaptcha, que pode identificar o conteúdo inserido pelo usuário e a imagem do captcha hCaptcha, retornando as coordenadas da pequena imagem que precisa ser clicada para completar a verificação.

Processo de Solicitação

Para usar a API de reconhecimento de imagens hCaptcha, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar. Após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; se o crédito acabar, você pode recarregar o saldo geral no painel de controle.

📘 Documentação Completa: API de Reconhecimento hCaptcha →

Uso Básico

Primeiro, entenda a forma básica de uso, que é inserir a imagem do captcha hCaptcha a ser processada para obter o resultado processado. Primeiro, você precisa passar um campo queries, que é a imagem do captcha hCaptcha. Precisamos capturar essa imagem do captcha em um site que tenha o captcha hCaptcha, o link do site de exemplo é: https://democaptcha.com/demo-form-eng/hcaptcha.html, clicando na caixa de seleção você poderá visualizar a imagem completa do captcha, conforme mostrado na imagem abaixo:

O campo queries é a captura da imagem do captcha mencionada acima, o tamanho da imagem não deve exceder 100kb. Você também precisa capturar a área indicada pela seta vermelha na imagem acima, além de compactar o tamanho da imagem e convertê-la para codificação Base64, conforme mostrado na imagem abaixo:

Além disso, você precisa inserir o parâmetro de conteúdo de reconhecimento relacionado à imagem do captcha question, que suporta tradução em chinês e inglês. Você pode inserir diretamente o conteúdo relacionado ao reconhecimento. A partir do conteúdo executado na imagem da página da web acima, podemos ver que a entrada para question deve ser Please click on the UNIQUE object among the others.. O conteúdo específico é o seguinte:

Aqui, configuramos os Cabeçalhos da Solicitação, incluindo:

accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.

Além disso, configuramos o Corpo da Solicitação, incluindo:

queries: lista de imagens do captcha codificadas em Base64.
question: parâmetro de conteúdo de reconhecimento relacionado à imagem do captcha, que suporta entrada direta em chinês e inglês.

Após a seleção, você pode notar que o código correspondente foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e você obterá o seguinte resultado:

{
  "solution": {
    "label": "Please click on the UNIQUE object among the others",
    "box": [
      "360",
      "276"
    ],
    "confidences": 0.6354503631591797
  }
}

O resultado retornado contém vários campos, descritos a seguir:

solution, resultado da verificação após o processamento da imagem do captcha hCaptcha.
- label, conteúdo reconhecido da imagem do captcha hCaptcha.
- box, informações de localização do resultado do reconhecimento da imagem do captcha hCaptcha, que é composta pelas informações de coordenadas da imagem.
- confidences, a confiança do reconhecimento da imagem do captcha hCaptcha em relação ao conteúdo reconhecido.
started_at, finished_at: tempos de início e término do processamento e geração do resultado desta solicitação, em timestamp Unix (segundos, ponto flutuante).
elapsed: tempo total gasto para este processamento (segundos).

Podemos ver que obtivemos o resultado da verificação da imagem do captcha hCaptcha, e precisamos apenas simular um clique na área correspondente às coordenadas de box para passar na verificação. A seguir, será apresentado como clicar nas coordenadas de localização do resultado box. Primeiro, estabelecemos um sistema de coordenadas retangulares para a imagem do captcha carregada, onde a origem central está no canto inferior esquerdo da imagem, 360 corresponde à coordenada horizontal e 276 à coordenada vertical. Precisamos apenas simular um clique nas coordenadas correspondentes do captcha, conforme mostrado na imagem abaixo:

Além disso, se você quiser gerar o código correspondente para a integração, pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte:

curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'

O código de integração em Python é o seguinte:

import requests

url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "question": "Please click on the UNIQUE object among the others.",
    "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Modo Assíncrono (async)

Por padrão, a API é síncrona e bloqueante: uma solicitação aguardará até que o resultado do reconhecimento seja processado antes de retornar. Se você estiver fazendo rotação de múltiplos solucionadores (multi-solver rotation) e desejar “submeter a tarefa e imediatamente obter o task_id, para depois agendar outros solucionadores e retornar mais tarde para ler o resultado”, você pode passar async: true no corpo da solicitação. Ao passar async: true, a interface retornará imediatamente um task_id, sem bloquear a espera:

curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"],
  "async": true
}'

{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}

Se você deseja verificar o progresso ativamente, pode usar o task_id para consultar POST /captcha/tasks (recomendado a cada 3~5 segundos). Esta interface não acionará ou avançará o processamento da tarefa; mesmo que não consulte, perca a conexão ou saia do cliente, o servidor continuará processando:

curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'

Durante o processamento, retornará status: processing:

{ "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" }

Quando o processamento estiver concluído, retornará status: ready e o resultado da identificação solution (a estrutura do campo é idêntica à do modo síncrono):

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "solution": {
    "label": "Por favor, clique no objeto ÚNICO entre os outros",
    "box": [
      "360",
      "276"
    ],
    "confidences": 0.6354503631591797
  }
}

Descrição da cobrança: no modo assíncrono, a criação de tarefas e a leitura do estado “processando” não são cobradas; o cliente será cobrado uma vez ao ler o resultado com sucesso pela primeira vez (consistente com o comportamento atual e o preço do modo síncrono). O servidor avançará a tarefa por conta própria, mas não cobrará antecipadamente porque o backend foi concluído primeiro. Se a tarefa não for bem-sucedida em 120 segundos, será encerrada com HTTP 504 timeout, sem cobrança. /captcha/tasks não é responsável por avançar a tarefa.

Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o código de erro e a mensagem correspondente. Por exemplo:

400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha na busca"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Através deste documento, você já entendeu como usar a API de reconhecimento de imagem hCaptcha para permitir que os usuários insiram o conteúdo reconhecido e a imagem do captcha hCaptcha, retornando finalmente as coordenadas da pequena imagem que precisa ser clicada para completar a verificação. Esperamos que este documento ajude você a integrar e usar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

hCaptcha API de Reconhecimento de Imagens

Processo de Solicitação

Uso Básico

Modo Assíncrono (async)

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão

​Processo de Solicitação

​Uso Básico

​Modo Assíncrono (async)

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Processo de Solicitação

Uso Básico

Modo Assíncrono (async)

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão