Resolutor de CAPTCHA de Imagem em Node.js: Um Guia Passo a Passo

TL;DR

• Um solucionador de CAPTCHA de imagem aceita bytes de imagem e retorna caracteres reconhecidos, em vez de um token reCAPTCHA.
• No Node.js, leia a imagem em um Buffer e encode esse Buffer como Base64 para uma solicitação ImageToTextTask.
• O fluxo de reconhecimento de imagem documentado retorna solution.text de createTask; este exemplo não faz polling.
• Mantenha sua chave de solução na server e use uma imagem atual de um formulário que você possui ou está autorizado a testar.
• O adaptador Node.js abaixo foi testado com respostas simuladas. Uma solução real e aceitação por um formulário real ainda requer validação no seu ambiente.

Uma integração de CAPTCHA de imagem começa com uma distinção que afeta toda a implementação: a entrada é um arquivo de imagem e a saída útil é texto. Quando um runner de testes Node.js encontra um formulário com caracteres distorcidos, ele precisa desses caracteres para essa tentativa específica. Um exemplo de reCAPTCHA orientado a token aborda uma tarefa diferente.

Este guia usa a solicitação de reconhecimento de imagem documentada CapSolver e um pequeno adaptador Node.js para mostrar como um arquivo se torna o corpo da solicitação e onde a resposta aparece. O exemplo assume um formulário de teste próprio com uma imagem que você pode salvar localmente. Navegação do navegador e submissão de formulário específica da aplicação permanecem parte do seu runner de testes.

O que um solucionador de CAPTCHA de imagem retorna?

Um solucionador de CAPTCHA de imagem retorna os caracteres que ele reconhece na imagem enviada. A entrada glossário CAPTCHA fornece o contexto mais amplo; esta implementação se refere a uma imagem de texto, em vez de um widget interativo.

A documentação oficial do ImageToTextTask define uma tarefa contendo um tipo, uma imagem em Base64 em body e um módulo de reconhecimento. Uma resposta bem-sucedida expõe o texto reconhecido em solution.text. Para este fluxo, a resposta inicial createTask contém o resultado.

Mantenha esses valores separados ao conectar o exemplo a um formulário:

Um resultado de reconhecimento é um resultado intermediário. A aplicação ainda pode rejeitar uma resposta se o desafio mudou, a sessão expirou ou a resposta pertence a outra imagem.

Etapa 1: Prepare o Node.js e uma imagem de teste própria

Use uma versão do Node.js com fetch e AbortSignal.timeout integrados; o adaptador foi testado no Node.js 24.16.0. Nenhuma dependência do npm é necessária. Salve os dois arquivos JavaScript abaixo em um diretório e coloque uma imagem de teste não sensível ao lado deles.

O exemplo lê ./captcha.png. Este é um caminho local, não uma URL de imagem ou uma string codificada. Inspeccione o arquivo antes de depurar a chamada da API: uma página HTML salva com a extensão PNG ainda é uma página HTML. Use uma imagem válida suportada pelo serviço.

Obtenha uma chave de solução da sua conta CapSolver e a expor ao processo como CAPSOLVER_API_KEY por meio do seu ambiente ou gerenciador de segredos. Mantenha essa credencial fora do JavaScript do navegador e do controle de versão. Uma credencial de publicação administrativa ou MCP não substitui a chave de solução.

Mantenha a sessão do formulário associada à imagem. Salve uma nova imagem sempre que o formulário gerar um novo desafio. Sobrescrever um nome de arquivo compartilhado enquanto outra solicitação usa a versão anterior pode produzir uma resposta de reconhecimento válida para a tentativa errada. Dê arquivos separados para tentativas concorrentes ou mantenha seus bytes separadamente.

Etapa 2: Codifique os bytes da imagem como Base64

Leia a imagem como dados binários, depois codifique o Buffer resultante. A documentação do sistema de arquivos do Node https://nodejs.org/api/fs.html descreve readFile, e sua documentação de Buffer https://nodejs.org/api/buffer.html define a codificação Base64.

A expressão-chave abaixo é image.toString('base64'). Não leia o arquivo como UTF-8 primeiro: os bytes da imagem não são um documento de texto. Nem envie o nome do arquivo como task.body, também. O serviço remoto precisa do conteúdo codificado, não um caminho no seu computador.

Envie o Base64 sem o prefixo data:image/png;base64,. Uma URL de dados tem um papel útil nos navegadores, mas difere do corpo da tarefa mostrado na documentação de reconhecimento. Gerar a codificação a partir de um Buffer evita copiar prefixos ou quebras de linha não relacionados.

Este exemplo rejeita um arquivo vazio. Ele não valida formato da imagem, dimensões ou qualidade visual. Se seu aplicativo aceitar uploads arbitrários, valide-os antes desta função. Uma leitura bem-sucedida apenas estabelece que os bytes estavam disponíveis.

Etapa 3: Envie a solicitação ImageToTextTask

Salve este adaptador como recognize-image.mjs. Os campos da solicitação seguem a documentação oficial. Carregamento de arquivo, o tempo limite e verificações de resposta são adições para este exemplo. O adaptador foi executado com respostas simuladas; usá-lo contra o serviço real requer sua chave de solução e permanece como etapa de validação em tempo real.

import { readFile } from 'node:fs/promises';

// Os campos da solicitação seguem a documentação oficial do ImageToTextTask.
export async function recognizeImage(path, apiKey, request = fetch) {
  if (!apiKey) throw new Error('Defina CAPSOLVER_API_KEY primeiro.');
  const image = await readFile(path);
  if (!image.length) throw new Error('O arquivo de imagem está vazio.');

  const response = await request('https://api.capsolver.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    signal: AbortSignal.timeout(60000),
    body: JSON.stringify({
      clientKey: apiKey,
      task: {
        type: 'ImageToTextTask',
        module: 'common',
        body: image.toString('base64')
      }
    })
  });
  if (!response.ok) throw new Error('Status HTTP ' + response.status);
  const result = await response.json();
  if (result.errorId !== 0) {
    throw new Error(result.errorCode || 'Falha no reconhecimento da imagem.');
  }
  if (result.status !== 'ready' ||
      typeof result.solution?.text !== 'string' ||
      !result.solution.text.length) {
    throw new Error('A API não retornou texto reconhecido.');
  }
  return result.solution.text;
}

A função aceita um caminho e uma chave de API e retorna o texto reconhecido. Seu terceiro argumento permite que um teste substitua fetch; chamadores normais omitam-no. O tempo limite de 60 segundos é uma configuração local, não um tempo prometido de reconhecimento ou limite de serviço.

As verificações de resposta seguem as etapas da solicitação. Um status HTTP não bem-sucedido falha antes da análise. Um JSON inválido produz um erro de análise. Um erro do provedor é tratado por errorId. Um envelope aparentemente bem-sucedido ainda deve conter um resultado pronto com texto não vazio, evitando que uma resposta ausente se torne um valor vazio no formulário.

Não há repetição automática. Após uma falha de transporte, o cliente pode não saber se o serviço recebeu a tarefa original. Decida como lidar com essa incerteza antes de adicionar repetições.

Resgate seu código promocional da CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta da CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora no seu Painel da CapSolver

Etapa 4: Execute o adaptador e use o texto

Salve o seguinte ponto de entrada como run.mjs ao lado do adaptador. Sua solicitação em tempo real requer sua própria chave de solução; os testes do adaptador local não estabelecem uma solução em tempo real concluída:

import { recognizeImage } from './recognize-image.mjs';

try {
  const path = process.argv[2];
  if (!path) throw new Error('Uso: node run.mjs ./captcha.png');
  const text = await recognizeImage(path, process.env.CAPSOLVER_API_KEY);
  console.log(text); // Use apenas uma imagem de teste própria não sensível aqui.
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

Com a chave de solução disponível no seu ambiente, execute o comando abaixo. Uma invocação em tempo real não foi realizada para este guia:

node run.mjs ./captcha.png

Uma invocação bem-sucedida imprime o texto retornado. A resposta depende da sua imagem; não há valor esperado fixo para uma chamada em tempo real. Use um fixture de teste próprio não sensível para este exemplo de terminal e evite imprimir respostas de desafio em logs de aplicação compartilhados.

Em um runner de testes, chame recognizeImage e envie seu valor de retorno para o campo de resposta associado à mesma imagem. O seletor e o método de submissão pertencem à sua aplicação, então eles não são inventados aqui. Afirme o resultado real do formulário após a submissão, como o registro de teste esperado sendo aceito.

Preserve a string reconhecida, a menos que o formulário defina explicitamente normalização. Converter cada resposta para maiúsculas ou remover espaços pode mudar seu significado. Um conjunto conhecido de caracteres pode ajudar a identificar um resultado inesperado, mas a validação não deve reescrever silenciosamente caracteres incertos.

Como escolher o módulo de reconhecimento?

Escolha o módulo de acordo com a tarefa de imagem descrita pelo serviço. Esta solicitação usa explicitamente common. Consulte as descrições dos módulos na documentação do ImageToTextTask antes de selecionar um modo especializado.

Um módulo não pode reparar uma entrada não relacionada. Uma captura de tela da tela inteira, um desafio desatualizado ou uma imagem contendo texto não relacionado pode produzir uma resposta inadequada, independentemente da configuração. Confirme que os bytes enviados correspondam ao desafio e tentativa ativa primeiro.

Se seu aplicativo gerar vários estilos de imagem, use amostras próprias representativas para cada estilo. Mantenha a resposta esperada do seu fixture separada da resposta reconhecida. Isso torna um desalinhamento reproduzível sem apresentar uma verificação de codificação sintética como evidência de precisão de reconhecimento.

Por exemplo, um fixture pode afirmar que os bytes do arquivo exato sobrevivem à codificação e decodificação Base64. Uma verificação de reconhecimento separada compara a resposta do provedor com os caracteres conhecidos do fixture. Um terceiro teste submete essa resposta através do formulário. Esses testes respondem a perguntas diferentes e devem relatar resultados separados.

Quais falhas você deve investigar primeiro?

Investigue falhas de entrada local antes da qualidade de reconhecimento. Um caminho ilegível, arquivo vazio ou chave ausente significa que a solicitação não foi concluída com sucesso. Alterar o módulo de reconhecimento não pode resolver essas falhas.

Para falhas remotas, mantenha o código de erro do provedor em um registro de diagnóstico controlado e consulte a referência oficial de erros da API. Evite descarregar o corpo da solicitação, que contém tanto a credencial quanto a imagem. Registre a etapa falha e o identificador de erro em vez disso.

A documentação da API global do Node cobre os primitivos de solicitação e aborto usados aqui. Encerrar a espera local não estabelece que o processamento remoto foi cancelado.

Ao relatar um problema, descreva qual etapa falhou. "A leitura do arquivo falhou" e "o serviço retornou texto que o formulário rejeitou" exigem evidências diferentes. Mantenha credenciais e conteúdos de imagem fora de relatos compartilhados, a menos que um processo de suporte controlado exija explicitamente.

O que foi testado antes de usar um CAPTCHA real?

O adaptador foi executado com sete casos de teste locais cobrindo construção de solicitação e preservação de Base64, credenciais ausentes, entrada vazia, falhas HTTP, erros do provedor, resultados ausentes e respostas malformadas ou falhas. Alguns casos agrupam afirmações relacionadas. Os testes substituíram fetch, então eles não contactaram o serviço pago.

O fixture da imagem verificou a codificação, e a resposta foi um valor de teste fornecido. Essas verificações estabelecem o comportamento do JavaScript local. Elas não medem a precisão do reconhecimento ou provam a aceitação por um formulário real. Conclua essas verificações com sua chave de solução e um desafio próprio atual antes de confiar na integração.

Para tarefas de token na mesma aplicação, use o guia separado JavaScript CAPTCHA API. Mantenha o reconhecimento de imagem em sua própria branch, pois o tipo de resultado e o fluxo de recuperação documentado diferem. Experimente o CapSolver com uma imagem própria representativa para validar essa conexão final.

Perguntas frequentes

Q: Preciso de um pacote npm?

O adaptador usa APIs integradas do Node.js e não requer nenhum pacote npm. Você ainda precisa de um runtime compatível, uma imagem válida e uma chave de solução. O Node.js 24.16.0 foi usado para os testes locais.

Q: O ImageToTextTask deve usar getTaskResult?

O fluxo de reconhecimento documentado retorna um resultado pronto com solution.text de createTask. Este adaptador não faz polling. Um loop de polling de outra tarefa CAPTCHA não deve ser copiado automaticamente.

Q: Posso enviar uma URL de imagem em vez de Base64?

Esta solicitação documentada usa conteúdo de imagem codificado no campo body. Obtenha a imagem própria através da sua aplicação e encode seus bytes. Um nome de arquivo ou URL não é equivalente a esse valor.

Q: Por que o formulário pode rejeitar o texto reconhecido?

Verifique se a imagem e a sessão pertencem à mesma tentativa e que a resposta não foi alterada. Uma string retornada estabelece nem o correto reconhecimento nem a aceitação da aplicação.

Q: Os testes locais provam a precisão do reconhecimento?

Não. Eles usam respostas fornecidas para verificar o comportamento do adaptador. O reconhecimento e a aceitação end-to-end exigem testes separados contra o serviço em tempo real e seu formulário próprio.