
Aloísio Vítor
Image Processing Expert
Publicado Nov 19, 2026
Actualizado Nov 19, 2026 · min de lectura

ImageToTextTask; esa tarea devuelve su resultado de reconocimiento directamente desde createTask.errorId de la API y valida solution.text antes de usarlo.Un solucionador de CAPTCHA proporciona a una aplicación Laravel un paso del lado del servidor para manejar un desafío admitido dentro de un flujo de trabajo autorizado. Laravel es un framework de aplicaciones web en PHP: puede ejecutar código de aplicación, comandos de consola y trabajo en segundo plano. Su cliente HTTP envía solicitudes a APIs; no renderiza páginas de navegador ni opera un widget de CAPTCHA.
Por ejemplo, una herramienta interna de operaciones puede recibir un desafío de imagen durante una tarea aprobada de recuperación de documentos. La aplicación envía la imagen al solucionador, comprueba el texto devuelto y pasa esa respuesta al paso correspondiente en su flujo de trabajo existente. La aplicación sigue siendo responsable del manejo de sesión, la validación de resultados y la decisión de continuar.
Esta guía utiliza CapSolver con el cliente HTTP nativo de Laravel. El ejemplo se limita a reconocer una imagen de prueba local propia, lo que hace que la solicitud y el resultado sean fáciles de inspeccionar antes de conectarlos a una aplicación más grande. No es una guía para instalar protección CAPTCHA en tus propios formularios.
Comienza con una aplicación Laravel funcionando, una cuenta de CapSolver con saldo disponible y una imagen PNG o JPEG local de la que seas propietario o estés autorizado a procesar. Coloca la imagen en storage/app/fixture.png para el comando siguiente. Elige una imagen de texto simple cuya respuesta esperada puedas comprobar tú mismo.
Ejecuta los comandos desde la raíz de tu proyecto Laravel. La integración usa el cliente HTTP del framework, por lo que no se requiere un SDK de solucionador independiente. PHP debe poder establecer una conexión HTTPS verificada con la API.
La tarea usada aquí es ImageToTextTask. Su body contiene los datos Base64 de la imagen, sin un prefijo data-URI. El módulo common devuelve texto reconocido. A diferencia de los flujos de tareas asíncronas, esta tarea de reconocimiento devuelve su resultado en la respuesta de createTask; el ejemplo no consulta getTaskResult.
Almacena la clave de API en el entorno de la aplicación y exponla mediante un archivo de configuración. Añade esta entrada al .env de tu servidor, reemplazando el marcador localmente:
CAPSOLVER_API_KEY=YOUR_CAPSOLVER_API_KEY
Crea config/capsolver.php:
<?php
return ['api_key' => env('CAPSOLVER_API_KEY')];
El comando leerá config('capsolver.api_key'). La guía de configuración de Laravel explica por qué los valores de entorno deben residir en archivos de configuración, especialmente cuando la configuración se almacena en caché. Si tu despliegue usa caché de configuración, vuelve a generarla mediante tu proceso de despliegue habitual después de cambiar la clave.
Mantén .env fuera del control de versiones y no pases la clave a JavaScript del frontend. Evita registrar el cuerpo de la solicitud saliente: su campo clientKey es una credencial, y su campo de imagen puede contener datos que no deseas en los registros generales de la aplicación.
Añade el siguiente comando de clausura a routes/console.php, conservando cualquier otro comando que ya esté en ese archivo. Laravel admite comandos Artisan basados en clausuras; esto mantiene la primera integración lo bastante pequeña para ejecutarla e inspeccionarla directamente.
El comando valida la entrada local, envía una solicitud y muestra un resultado de texto no vacío solo después de que las comprobaciones de respuesta se superan. Su restricción a PNG/JPEG y los valores de timeout son decisiones de ejemplo de la aplicación, no una lista completa de límites del proveedor.
<?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');
La comprobación del estado HTTP es importante porque Laravel no lanza excepciones automáticamente para cada respuesta HTTP de error. La comprobación a nivel de API es independiente: una respuesta HTTP exitosa aún debe contener el errorId esperado, el estado de la tarea y el campo de resultado.
El comando evita deliberadamente los reintentos automáticos de creación de tareas. Un timeout de conexión puede dejarte sin saber si el servicio recibió la solicitud original. Inspecciona el fallo antes de reenviar, especialmente al mover la operación a una cola con su propia política de reintentos.
Canjea tu código de bono de CapSolver
Aumenta tu presupuesto de automatización al instante.
Usa el código de bono CAP26 al recargar tu cuenta de CapSolver para obtener un 5% de bono extra en cada recarga, sin límites.
Canjéalo ahora en tu Panel de CapSolver
Ejecuta el comando una vez contra tu fixture local:
php artisan captcha:read storage/app/fixture.png
Para una imagen que contenga 583729, la salida esperada es:
583729
Compara el texto devuelto con la imagen real, incluyendo mayúsculas y minúsculas y caracteres ambiguos. Una cadena no vacía demuestra que la solicitud produjo un resultado; no establece precisión para cada imagen futura. Usa la respuesta de aceptación del destino como comprobación aparte cuando conectes este paso a un flujo de trabajo de aplicación permitido.
Si PHP informa un error de archivo de certificado o almacén de confianza, corrige el paquete de CA configurado para ese runtime antes de reintentar. Mantén activada la verificación de certificados TLS. El mensaje de error de conexión del comando es intencionadamente breve; investiga los diagnósticos de infraestructura por separado sin volcar credenciales ni el cuerpo de la solicitud.
Mantén como resultados diferentes los fallos de entrada, los fallos de transporte, los errores de API y el rechazo aguas abajo. Esta distinción evita que un archivo faltante se convierta en un reintento de API de pago y evita que un error de validación de la aplicación se cuente como una caída del solucionador.
| Resultado | Acción siguiente |
|---|---|
| Falta la clave de API | Corrige la configuración del servidor antes de hacer una solicitud |
| Falta el archivo o no es compatible con este ejemplo | Arregla la entrada; no se necesita solicitud al solucionador |
| La conexión falla o expira | Inspecciona la red y la configuración TLS; revisa antes de reenviar |
| Error HTTP o de API | Registra el estado o el código de error y sigue la guía de API correspondiente |
| Se devuelve texto | Compáralo con la imagen y valida el siguiente paso de la aplicación |
Al adaptar el comando a un trabajo en cola, mantén los secretos fuera de las cargas de trabajos serializadas y léelos mediante la configuración en tiempo de ejecución. Define explícitamente el comportamiento de reintentos del trabajo. Devuelve un resultado no resuelto al flujo de trabajo que llama cuando no puedas establecer que un resultado fue aceptado.
Para una resolución de problemas operativa más amplia, nuestra explicación de errores de proxy DNS dinámico explica un fallo diferente relacionado con sesiones. Ese ejemplo se refiere a la consistencia del proxy, no al reconocimiento de imágenes; no apliques sus parámetros de tarea a este comando.
Elige una tarea en función del desafío que realmente tengas, en lugar de enviar cada CAPTCHA a un endpoint de reconocimiento de imágenes. Un resultado de imagen a texto es una cadena. No puede sustituir al token esperado por una integración de reCAPTCHA o Turnstile.
Usa los tipos de tarea de API admitidos para identificar el contrato pertinente. La ejecución en navegador, los parámetros del widget y el envío al destino siguen siendo responsabilidades separadas. Completa primero el pequeño flujo de trabajo de imagen y luego construye y prueba la tarea específica admitida que tu aplicación necesite.
El cliente HTTP nativo de Laravel es suficiente para una integración pequeña y fácil de inspeccionar con el solucionador. Mantén la solicitud en el servidor, usa el esquema de tareas documentado y valida tanto el resultado como el siguiente paso de la aplicación. CapSolver puede entonces situarse en el paso de CAPTCHA de un flujo de trabajo autorizado sin hacerse cargo del resto de la aplicación.
P: ¿Necesito un paquete de solucionador de CAPTCHA para Laravel?
No. Este ejemplo usa el cliente HTTP integrado de Laravel para llamar a la API directamente. Un wrapper independiente es opcional y debe comprobarse frente al contrato de tarea actual antes de usarlo.
P: ¿Esto agrega protección CAPTCHA a mi formulario de inicio de sesión de Laravel?
No. Este comando reconoce un desafío de imagen autorizado mediante una API de solucionador. Agregar protección CAPTCHA a tu propio formulario es una integración diferente con el servicio de validación del proveedor de CAPTCHA.
P: ¿Necesito consultar getTaskResult para este ejemplo?
No. ImageToTextTask devuelve su resultado de reconocimiento directamente desde createTask. Otros tipos de tarea pueden usar un flujo de resultados diferente, así que sigue la documentación del tipo de tarea seleccionado.
P: ¿Puede este código resolver reCAPTCHA o Turnstile tal cual está?
No. Este código envía una ImageToTextTask y espera texto. reCAPTCHA y Turnstile usan parámetros de tarea y resultados de token diferentes; cambiar solo el nombre de la tarea es insuficiente.
P: ¿Debo reintentar automáticamente después de un timeout?
No crees ciegamente la misma tarea de nuevo. Un timeout puede ocurrir después de que la solicitud haya llegado al servicio, así que inspecciona el fallo y define una política de reintentos acotada antes de añadir reintentos automatizados.

Aloísio Vítor
Image Processing Expert
Interpreting the visual signals behind web workflows.
SOBRE EL AUTOR
Compara los flujos de trabajo de CAPTCHA sin interfaz gráfica y con interfaz gráfica mediante una prueba controlada de imágenes, resultados reales de la API y comprobaciones de aceptación de formularios. Descubre lo que demuestran los resultados.

Agrega un solucionador de CAPTCHA a Cypress con una tarea de Node, mantén las claves de API fuera del código del navegador y verifica un formulario propio de imagen-CAPTCHA con un ejemplo de JavaScript probado.
