Reconhecimento de imagem do hCaptcha

HCaptchaClassification reconhece os desafios de imagem exibidos pelo hCaptcha: você envia a pergunta e as imagens, e recebe quais imagens selecionar, qual posição clicar ou de onde para onde arrastar; seu programa executa a ação no navegador. Ele não retorna token. A resposta é síncrona, cada requisição custa 8 pontos (≈ US$1.20 / 1k), e não há cobrança de pontos quando nenhum alvo é encontrado (resultado vazio).

Dica

Se não quiser escrever a lógica de cliques, use a extensão do navegador, que oferece suporte a todos esses tipos de desafio. Se precisa de um token em vez de posições de clique, use hCaptcha.

POSThttps://api.yescaptcha.com/createTaskEndpoint globalCopiar

POSThttps://cn.yescaptcha.com/createTaskEndpoint ChinaCopiar

Tipos de tarefa e preços

Tipo de tarefa	Preço	Modo	Observações
HCaptchaClassification	US$1.20 / 1k; 8 pontos/tarefa · ¥8 / 1k	Síncrono	Não há cobrança de pontos quando nenhum alvo é encontrado

Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de tarefa; veja "Tipos de tarefa e preços" nesta página
queries	array	Sim	Lista de imagens da pergunta codificadas em Base64, na ordem da página (9 imagens pequenas para uma grade 3×3)
question	string	Não	A pergunta completa, como aparece na página (recomendado chinês simplificado ou inglês), por exemplo Please click each image containing a bicycle. Envie pelo menos um entre question e anchors; recomendamos enviar os dois
anchors	array	Não	Lista de imagens de exemplo (exibidas ao lado da pergunta) codificadas em Base64; obrigatória para perguntas que as tenham

• Envie em question a frase completa exatamente como aparece na página; não é necessário traduzi-la, mas recomendamos mudar o idioma do hCaptcha para chinês simplificado ou inglês. Novas perguntas costumam ser suportadas rapidamente; categorias totalmente novas, em até 3 dias úteis.

Cuidado

Se a pergunta tiver uma imagem de exemplo pequena no canto superior direito, envie-a em anchors. Desafios que só podem ser resolvidos olhando a imagem de exemplo não são reconhecidos sem anchors.

Seleção em grade 3×3

A pergunta é do tipo “Please click each image containing …” e há 9 imagens pequenas abaixo. Em queries, envie as 9 imagens em Base64, na ordem em que aparecem:

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaClassification",
    "question": "Please click each image containing a bicycle",
    "queries": ["BASE64_IMAGE_1", "BASE64_IMAGE_2"]
  }
}

Resposta:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "objects": [true, false, false, true, true, false, true, true, false],
    "top_k": [0, 3, 4, 6, 7],
    "confidences": [1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0]
  }
}

objects e top_k trazem a mesma informação: o primeiro indica, para cada imagem, se ela é um alvo; o segundo lista os índices das imagens-alvo (a partir de 0). Basta clicar nessas imagens.

Clique em posição indicada

A pergunta é do tipo “Please click on …” e abaixo há uma imagem grande, na qual você deve clicar em uma ou mais posições.

1. Use em question a pergunta exibida na página; se houver imagens de exemplo, envie-as em anchors.
2. Em queries, envie uma imagem: o ideal é a imagem original exportada diretamente do canvas (recomendamos converter para JPG). Se só for possível fazer captura de tela, capture a área da imagem grande marcada em vermelho abaixo, sem sobrar nem faltar.
3. O box retornado contém as coordenadas a clicar, na ordem x1, y1, x2, y2…, com origem no canto superior esquerdo da imagem enviada.
4. Se o tamanho da imagem enviada for diferente do tamanho exibido na página, faça a conversão: x na página = x retornado × largura exibida ÷ largura da imagem enviada (y segue a mesma lógica). Por exemplo, se o x retornado é 769, a largura exibida do canvas é 350 e a largura da imagem enviada é 1000, deve-se clicar em 769 × 350 ÷ 1000 ≈ 269 na página.

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaClassification",
    "question": "Please click on the entity present in the sample image.",
    "anchors": ["BASE64_ANCHOR_1", "BASE64_ANCHOR_2", "BASE64_ANCHOR_3"],
    "queries": ["BASE64_OF_THE_BIG_IMAGE"]
  }
}

Resposta:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "box": ["221", "213"]
  }
}

Quando há vários alvos para clicar, box traz vários pares de coordenadas em sequência: ["221", "213", "340", "118", ...].

Arrastar até a posição indicada

A pergunta é do tipo “Drag … to …”: você deve arrastar as peças da direita até o local correspondente na imagem.

1. Use em question a pergunta exibida na página.
2. Envie em queries uma captura de tela que mostre ao mesmo tempo as peças a arrastar e as posições de destino, com cada lado da imagem de no mínimo 260 pixels.
3. Cada item de box na resposta é um arrasto: start é a posição da peça e end é a posição para onde arrastá-la. Havendo várias peças, arraste uma de cada vez.

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "type": "drag",
    "box": [
      {
        "start": [644, 218],
        "end": [239, 315]
      }
    ]
  }
}

Se você obteve dados do protocolo (imagens das peças, coordenadas das peças e a imagem de fundo) em vez de uma captura de tela, primeiro cole as peças na imagem de fundo conforme as coordenadas, montando uma imagem com o mesmo aspecto da captura de tela da página, e só então envie.

Perguntas com animação

Quando a imagem do desafio é uma animação, envie em queries a animação (GIF ou formato similar) em Base64. Recomendamos uma animação de pelo menos 3 segundos, de preferência 5 a 6 segundos, a cerca de 12 FPS.

Reportar e reembolso de pontos

Se a validação falhar após os cliques, você pode reportar a tarefa com report em até 1 hora; o reembolso de pontos é liquidado após cerca de 24 horas. Veja as regras em Cobrança e reembolso de pontos.

Tutoriais relacionados

• Reconhecimento de imagem do hCaptcha com cliques simulados (Selenium)