hCaptcha API de Reconhecimento de Imagens

Este documento apresentará uma explicação sobre a integraçã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 fazer login. 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; quando o crédito acabar, você pode recarregar o saldo geral no painel de controle.

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

Uso Básico

Primeiro, entenda a forma básica de uso, que é inserir a imagem do captcha hCaptcha que precisa ser processada para obter o resultado. Primeiro, você precisa passar um campo queries, que é a imagem do captcha hCaptcha. Precisamos capturar essa imagem do captcha em um site que utilize hCaptcha, um exemplo de site é: https://democaptcha.com/demo-form-eng/hcaptcha.html, clicando na caixa de seleção para exibir 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 pela seta amarela na imagem da página 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:

Podemos ver que configuramos os Cabeçalhos da Solicitação, incluindo:

accept: o formato de resposta desejado, aqui 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 também foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e assim obtemos 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.

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 informações de localização de box do resultado. 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 de integração correspondente, 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 uma 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 obter 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
}'

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

Em seguida, use o task_id para fazer polling em POST /captcha/tasks (recomendado a cada 3~5 segundos) para obter o resultado:

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, será retornado status: processing:

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

Quando o processamento estiver concluído, será retornado 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 o polling “em processamento” não geram cobrança; apenas quando o resultado da identificação for obtido com sucesso será cobrado uma vez (o mesmo preço do modo síncrono). Portanto, cancelar tarefas que ainda não foram concluídas durante a rotação não gerará custos. /captcha/tasks é comum a todas as interfaces de captcha (token e série de reconhecimento), basta usar o mesmo task_id para polling.

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 ao buscar"
  },
  "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 possa ajudá-lo 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

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