
Adélia Cruz
MCP Integration Engineer
Publicado Nov 19, 2026
Atualizado Nov 19, 2026 · minutos de leitura

ImageToTextTask; essa tarefa retorna o resultado do reconhecimento diretamente em createTask.errorId da API e valide solution.text antes de usá-lo.Um resolvedor de CAPTCHA fornece a uma aplicação Laravel uma etapa no servidor para lidar com um desafio compatível dentro de um fluxo de trabalho autorizado. Laravel é um framework de aplicações web em PHP: ele pode executar código de aplicação, comandos de console e tarefas em segundo plano. Seu cliente HTTP envia requisições para APIs; ele não renderiza páginas de navegador nem opera widgets de CAPTCHA.
Por exemplo, uma ferramenta interna de operações pode receber um desafio de imagem durante uma tarefa aprovada de recuperação de documentos. A aplicação envia a imagem ao resolvedor, verifica o texto retornado e passa essa resposta para a etapa relevante em seu fluxo de trabalho existente. A aplicação continua responsável pelo gerenciamento de sessão, validação do resultado e decisão de prosseguir.
Este guia usa o CapSolver com o cliente HTTP nativo do Laravel. O exemplo se limita a reconhecer uma imagem de teste local de sua propriedade, tornando a requisição e o resultado fáceis de inspecionar antes de conectá-los a uma aplicação maior. Não é um guia para instalar proteção por CAPTCHA em seus próprios formulários.
Comece com uma aplicação Laravel funcionando, uma conta CapSolver com saldo disponível e uma imagem PNG ou JPEG local que você possua ou esteja autorizado a processar. Coloque a imagem em storage/app/fixture.png para o comando abaixo. Escolha uma imagem de texto simples cujo resultado esperado você consiga verificar por conta própria.
Execute os comandos a partir da raiz do seu projeto Laravel. A integração usa o cliente HTTP do framework, então nenhum SDK de resolvedor separado é necessário. O PHP precisa conseguir estabelecer uma conexão HTTPS verificada com a API.
A tarefa usada aqui é a ImageToTextTask. Seu body contém os dados Base64 da imagem, sem prefixo de data-URI. O módulo common retorna o texto reconhecido. Diferente de fluxos de tarefa assíncronos, essa tarefa de reconhecimento retorna seu resultado na própria resposta de createTask; o exemplo não faz polling em getTaskResult.
Armazene a chave de API no ambiente da aplicação e exponha-a através de um arquivo de configuração. Adicione esta entrada ao .env do servidor, substituindo o valor de exemplo localmente:
CAPSOLVER_API_KEY=YOUR_CAPSOLVER_API_KEY
Crie config/capsolver.php:
<?php
return ['api_key' => env('CAPSOLVER_API_KEY')];
O comando lerá config('capsolver.api_key'). A documentação de configuração do Laravel explica por que valores de ambiente pertencem a arquivos de configuração, especialmente quando a configuração é armazenada em cache. Se o seu deploy usa cache de configuração, reconstrua-o pelo seu processo normal de deploy depois de alterar a chave.
Mantenha o .env fora do controle de versão e não passe a chave para JavaScript no frontend. Evite registrar o corpo da requisição de saída em logs: o campo clientKey é uma credencial, e o campo da imagem pode conter dados que você não deseja em logs gerais da aplicação.
Adicione o comando de closure abaixo em routes/console.php, mantendo quaisquer outros comandos já existentes nesse arquivo. O Laravel oferece suporte a comandos Artisan baseados em closure; isso mantém a primeira integração pequena o bastante para ser executada e inspecionada diretamente.
O comando valida a entrada local, envia uma requisição e imprime um resultado de texto não vazio somente após as verificações de resposta passarem. Sua restrição a PNG/JPEG e os valores de timeout são escolhas de exemplo da aplicação, não uma lista completa de limites do fornecedor.
<?php
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\ConnectionException;
Artisan::command('captcha:read {path}', function () {
$key = config('capsolver.api_key');
$path = $this->argument('path');
if (! is_string($key) || $key === '') {
$this->error('Set CAPSOLVER_API_KEY on the server.');
return 1;
}
if (! is_file($path) || ! is_readable($path)) {
$this->error('Supply a readable local image file.');
return 1;
}
if (! in_array(mime_content_type($path), ['image/png', 'image/jpeg'], true)) {
$this->error('This example accepts PNG and JPEG files.');
return 1;
}
$image = file_get_contents($path);
if ($image === false) {
$this->error('Could not read the image.');
return 1;
}
try {
$response = Http::acceptJson()->connectTimeout(10)->timeout(60)
->post('https://api.capsolver.com/createTask', [
'clientKey' => $key,
'task' => [
'type' => 'ImageToTextTask',
'module' => 'common',
'body' => base64_encode($image),
],
]);
} catch (ConnectionException $exception) {
$this->error('Connection failed or timed out. Check before resubmitting.');
return 1;
}
if (! $response->successful()) {
$this->error('Solver HTTP error: '.$response->status());
return 1;
}
$data = $response->json();
if (! is_array($data) || ($data['errorId'] ?? null) !== 0) {
$this->error('Solver API error: '.($data['errorCode'] ?? 'INVALID_RESPONSE'));
return 1;
}
$text = $data['solution']['text'] ?? null;
if (($data['status'] ?? null) !== 'ready' || ! is_string($text) || $text === '') {
$this->error('No ready text result was returned.');
return 1;
}
$this->line($text);
return 0;
})->purpose('Read an authorized image CAPTCHA with the solver API');
A verificação do status HTTP é importante porque o Laravel não lança exceções automaticamente para toda resposta HTTP de erro. A verificação em nível de API é separada: uma resposta HTTP bem-sucedida ainda precisa conter o errorId esperado, o status da tarefa e o campo de resultado.
O comando evita deliberadamente tentativas automáticas de recriação de tarefas. Um timeout de conexão pode deixá-lo em dúvida se o serviço recebeu ou não a requisição original. Inspecione a falha antes de reenviar, especialmente ao mover a operação para uma fila com sua própria política de tentativas.
Resgate Seu Código de Bônus CapSolver
Aumente instantaneamente seu orçamento de automação!
Use o código de bônus CAP26 ao recarregar sua conta CapSolver para receber 5% de bônus extra em cada recarga — sem limites.
Resgate agora no seu Painel CapSolver
Execute o comando uma vez contra seu arquivo de teste local:
php artisan captcha:read storage/app/fixture.png
Para uma imagem contendo 583729, a saída esperada é:
583729
Compare o texto retornado com a imagem real, incluindo caixa de letras e caracteres ambíguos. Uma string não vazia prova que a requisição produziu um resultado; isso não garante precisão para todas as imagens futuras. Use a resposta de aceitação do destino como uma verificação separada quando conectar esta etapa a um fluxo de trabalho de aplicação permitido.
Se o PHP relatar um erro de arquivo de certificado ou trust-store, corrija o pacote de CAs configurado para esse runtime antes de tentar novamente. Mantenha a verificação de certificado TLS ativada. A mensagem de erro de conexão do comando é intencionalmente breve; investigue diagnósticos de infraestrutura separadamente, sem despejar credenciais ou o corpo da requisição.
Mantenha falhas de entrada, falhas de transporte, erros de API e rejeição a jusante como resultados diferentes. Essa distinção impede que um arquivo ausente se torne uma tentativa paga de API e impede que um erro de validação da aplicação seja contado como indisponibilidade do resolvedor.
| Resultado | Próxima ação |
|---|---|
| Chave de API ausente | Corrija a configuração do servidor antes de fazer uma requisição |
| Arquivo ausente ou não suportado por este exemplo | Corrija a entrada; nenhuma requisição ao resolvedor é necessária |
| Conexão falha ou expira | Inspecione a configuração de rede e TLS; verifique antes de reenviar |
| Erro HTTP ou de API | Registre o status ou código de erro e siga a documentação relevante da API |
| Texto retornado | Compare com a imagem e valide a próxima etapa da aplicação |
Ao adaptar o comando para um job em fila, mantenha segredos fora dos payloads serializados dos jobs e leia-os pela configuração em tempo de execução. Defina explicitamente o comportamento de tentativas do job. Retorne um resultado não resolvido ao fluxo de trabalho chamador quando não for possível estabelecer que um resultado foi aceito.
Para uma solução de problemas operacionais mais ampla, nossa explicação sobre erro de proxy DNS dinâmico aborda um tipo diferente de falha relacionada a sessão. Esse exemplo se refere à consistência do proxy, não ao reconhecimento de imagem; não aplique seus parâmetros de tarefa a este comando.
Escolha uma tarefa com base no desafio que você realmente tem, em vez de enviar todo CAPTCHA para um endpoint de reconhecimento de imagem. Um resultado de imagem-para-texto é uma string. Ele não pode substituir o token esperado por uma integração de reCAPTCHA ou Turnstile.
Use os tipos de tarefa de API suportados para identificar o contrato relevante. A execução em navegador, os parâmetros do widget e o envio ao destino continuam sendo responsabilidades separadas. Conclua primeiro o pequeno fluxo de imagem, depois construa e teste a tarefa específica suportada de que sua aplicação precisa.
O cliente HTTP nativo do Laravel é suficiente para uma integração pequena e inspecionável com o resolvedor. Mantenha a requisição no lado do servidor, use o schema de tarefa documentado e valide tanto o resultado quanto a próxima etapa da aplicação. O CapSolver pode então atuar na etapa de CAPTCHA de um fluxo de trabalho autorizado sem assumir o controle do restante da aplicação.
P: Preciso de um pacote de resolvedor de CAPTCHA para Laravel?
Não. Este exemplo usa o cliente HTTP nativo do Laravel para chamar a API diretamente. Um wrapper separado é opcional e deve ser verificado em relação ao contrato de tarefa atual antes do uso.
P: Isso adiciona proteção por CAPTCHA ao meu formulário de login em Laravel?
Não. Este comando reconhece um desafio de imagem autorizado por meio de uma API de resolução. Adicionar proteção por CAPTCHA ao seu próprio formulário é uma integração diferente, com o serviço de validação do provedor de CAPTCHA.
P: Preciso fazer polling em getTaskResult neste exemplo?
Não. ImageToTextTask retorna o resultado do reconhecimento diretamente em createTask. Outros tipos de tarefa podem usar um fluxo de resultado diferente, então siga a documentação do tipo de tarefa selecionado.
P: Este código consegue resolver reCAPTCHA ou Turnstile como está?
Não. Este código envia uma ImageToTextTask e espera texto. reCAPTCHA e Turnstile usam parâmetros de tarefa e resultados de token diferentes; mudar apenas o nome da tarefa é insuficiente.
P: Devo tentar novamente automaticamente após um timeout?
Não crie cegamente a mesma tarefa de novo. Um timeout pode ocorrer depois que a requisição já tiver chegado ao serviço, então inspecione a falha e defina uma política de tentativas limitada antes de adicionar retentativas automáticas.

Adélia Cruz
MCP Integration Engineer
Making CapSolver tools accessible through MCP.
SOBRE O AUTOR
Compare fluxos de CAPTCHA headless e com interface gráfica usando um teste de imagem controlado, resultados reais de API e verificações de aceitação de formulário. Saiba o que os resultados comprovam.

Adicione um solucionador de CAPTCHA ao Cypress com uma tarefa Node, mantenha as chaves de API fora do código do navegador e verifique um formulário de imagem-CAPTCHA próprio com um exemplo de JavaScript testado.
