Solucionador de CAPTCHA de Imagen en Node.js: Guía paso a paso

TL;DR

• Un solucionador de CAPTCHA de imagen acepta bytes de imagen y devuelve caracteres reconocidos, en lugar de un token reCAPTCHA.
• En Node.js, lea la imagen en un Buffer y encodee ese Buffer como Base64 para una solicitud de ImageToTextTask.
• El flujo de reconocimiento de imagen documentado devuelve solution.text desde createTask; este ejemplo no realiza encuestas.
• Mantenga su clave de resolución en el servidor y use una imagen actual de un formulario que posea o esté autorizado a probar.
• El adaptador de Node.js a continuación fue probado con respuestas simuladas. Una resolución en vivo y la aceptación por un formulario real aún requieren validación en su entorno.

Una integración de CAPTCHA de imagen comienza con una distinción que afecta toda la implementación: la entrada es un archivo de imagen y la salida útil es texto. Cuando un ejecutor de pruebas de Node.js encuentra un formulario que contiene caracteres distorsionados, necesita esos caracteres para ese intento en particular. Un ejemplo de reCAPTCHA orientado a tokens aborda una tarea diferente.

Este guía utiliza la solicitud de reconocimiento de imagen documentada de CapSolver y un pequeño adaptador de Node.js para mostrar cómo un archivo se convierte en el cuerpo de la solicitud y dónde aparece la respuesta. El ejemplo asume un formulario de prueba propiedad propia con una imagen que puede guardar localmente. La navegación del navegador y la presentación de formularios específicos de la aplicación permanecen parte de su ejecutor de pruebas.

¿Qué devuelve un solucionador de CAPTCHA de imagen?

Un solucionador de CAPTCHA de imagen devuelve los caracteres que reconoce en la imagen enviada. La entrada del glosario de CAPTCHA proporciona el contexto más amplio; esta implementación se enfoca en una imagen de texto en lugar de un widget interactivo.

La documentación oficial de ImageToTextTask define una tarea que contiene un tipo, una imagen en Base64 en body y un módulo de reconocimiento. Una respuesta exitosa expone el texto reconocido en solution.text. Para este flujo, la respuesta inicial de createTask contiene el resultado.

Mantenga estos valores separados al conectar el ejemplo a un formulario:

Un resultado de reconocimiento es un resultado intermedio. La aplicación aún puede rechazar una respuesta si el desafío cambió, la sesión expiró o la respuesta pertenece a otra imagen.

Paso 1: Preparar Node.js y una imagen de prueba propiedad propia

Use una versión de Node.js con fetch y AbortSignal.timeout integrados; el adaptador fue probado en Node.js 24.16.0. No se requiere dependencia de npm. Guarde los dos archivos JavaScript a continuación en un directorio y coloque una imagen de prueba no sensible al lado de ellos.

El ejemplo lee ./captcha.png. Este es un camino local, no una URL de imagen o una cadena codificada. Inspeccione el archivo antes de depurar la llamada a la API: una página de error HTML guardada con una extensión PNG sigue siendo una página HTML. Use una imagen válida compatible con el servicio.

Obtenga una clave de resolución de su cuenta de CapSolver y expóngala al proceso como CAPSOLVER_API_KEY a través de su entorno o administrador de secretos. Mantenga esa credencial fuera de JavaScript del navegador y control de código fuente. Un permiso administrativo o una credencial de MCP no sustituyen la clave de resolución.

Mantenga la sesión del formulario asociada con la imagen. Guarde una nueva imagen cada vez que el formulario genere un nuevo desafío. Sobrescribir un nombre de archivo compartido mientras otra solicitud usa el formulario anterior puede producir una respuesta de reconocimiento válida para el intento equivocado. Asigne archivos separados a intentos concurrentes o mantenga sus bytes por separado.

Paso 2: Codificar los bytes de imagen como Base64

Lea la imagen como datos binarios, luego codifique el Buffer resultante. La documentación de sistema de archivos de Node describe readFile, y su documentación de Buffer define la codificación en Base64.

La expresión clave a continuación es image.toString('base64'). No lea el archivo como UTF-8 primero: los bytes de imagen no son un documento de texto. Tampoco envíe el nombre del archivo como task.body. El servicio remoto necesita el contenido codificado, no una ruta en su computadora.

Envíe Base64 sin el prefijo data:image/png;base64,. Una URL de datos tiene un papel útil en navegadores, pero difiere del cuerpo de la tarea mostrado en la documentación de reconocimiento. Generar la codificación desde un Buffer evita copiar prefijos o saltos de línea no relacionados.

Este ejemplo rechaza un archivo vacío. No valida el formato de imagen, las dimensiones o la calidad visual. Si su aplicación acepta cargas arbitrarias, valídelas antes de esta función. Una lectura exitosa solo establece que los bytes estaban disponibles.

Paso 3: Enviar la solicitud ImageToTextTask

Guarde este adaptador como recognize-image.mjs. Los campos de la solicitud siguen la documentación oficial. La carga del archivo, el tiempo de espera y las verificaciones de respuesta son adiciones para este ejemplo. El adaptador se ejecutó con respuestas simuladas; usarlo contra el servicio real requiere su clave de resolución y sigue siendo un paso de validación en vivo.

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

// Los campos de solicitud siguen la documentación oficial de ImageToTextTask.
export async function recognizeImage(path, apiKey, request = fetch) {
  if (!apiKey) throw new Error('Establezca CAPSOLVER_API_KEY primero.');
  const image = await readFile(path);
  if (!image.length) throw new Error('El archivo de imagen está vacío.');

  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('Estado HTTP ' + response.status);
  const result = await response.json();
  if (result.errorId !== 0) {
    throw new Error(result.errorCode || 'Falló el reconocimiento de imagen.');
  }
  if (result.status !== 'ready' ||
      typeof result.solution?.text !== 'string' ||
      !result.solution.text.length) {
    throw new Error('La API no devolvió texto reconocido.');
  }
  return result.solution.text;
}

La función acepta una ruta y una clave de API y devuelve texto reconocido. Su tercer argumento permite a una prueba reemplazar fetch; los llamadores normales lo omiten. El tiempo de espera de 60 segundos es una configuración local, no un tiempo prometido de reconocimiento o límite de servicio.

Las verificaciones de respuesta siguen las etapas de la solicitud. Un estado HTTP no exitoso falla antes de analizar. Un JSON inválido produce un error de análisis. Un error del proveedor se maneja a través de errorId. Un sobre que parece exitoso aún debe contener un resultado listo con texto no vacío, evitando que una respuesta faltante se convierta silenciosamente en un valor vacío del formulario.

No hay solicitud automática repetida. Después de un fallo de transporte, el cliente puede no saber si el servicio recibió la tarea original. Decida cómo manejar esa incertidumbre antes de agregar reintentos.

Canjear su código de bonificación de CapSolver

¡Aumente su presupuesto de automatización de inmediato!
Use el código de bonificación CAP26 al recargar su cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Canjéalo ahora en su Panel de CapSolver

Paso 4: Ejecutar el adaptador y usar el texto

Guarde el siguiente punto de entrada como run.mjs junto con el adaptador. Su solicitud en vivo requiere su propia clave de resolución; las pruebas del adaptador local no establecen una resolución en vivo completada:

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 solo una imagen de prueba propiedad propia no sensible aquí.
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

Con la clave de resolución disponible en su entorno, ejecute el siguiente comando. Una invocación en vivo no se realizó para esta guía:

node run.mjs ./captcha.png

Una invocación exitosa imprime el texto devuelto. La respuesta depende de su imagen; no hay valor esperado fijo para una llamada en vivo. Use un fixture no sensible propiedad propia para este ejemplo de terminal y evite imprimir respuestas de desafío en registros de aplicación compartidos.

En un ejecutor de pruebas, llame a recognizeImage y envíe su valor de retorno al campo de respuesta asociado con la misma imagen. El selector y el método de presentación pertenecen a su aplicación, por lo que no se inventan aquí. Afirmar el resultado real del formulario después de la presentación, como el registro de prueba esperado que se acepte.

Preserve la cadena reconocida a menos que el formulario defina explícitamente la normalización. Convertir cada respuesta a mayúsculas o eliminar espacios puede cambiar su significado. Un conjunto de caracteres conocido puede ayudar a identificar un resultado inesperado, pero la validación no debe reescribir silenciosamente caracteres inciertos.

¿Cómo debe elegir el módulo de reconocimiento?

Elija el módulo según la tarea de imagen descrita por el servicio. Esta solicitud utiliza explícitamente common. Consulte las descripciones de módulo en la documentación de ImageToTextTask antes de seleccionar un modo especializado.

Un módulo no puede reparar una entrada no relacionada. Una captura de pantalla de todo el formulario, un desafío obsoleto o una imagen que contenga texto no relacionado puede producir una respuesta inadecuada independientemente de la configuración. Confirme que los bytes enviados correspondan al desafío y al intento activo primero.

Si su aplicación genera varios estilos de imagen, use muestras propiedad propias representativas para cada estilo. Mantenga la respuesta esperada de su fixture separada de la respuesta reconocida. Esto hace que un desajuste sea reproducible sin presentar una verificación de codificación sintética como evidencia de precisión de reconocimiento.

Por ejemplo, un fixture puede afirmar que los bytes del archivo exacto sobreviven a la codificación y decodificación en Base64. Una verificación de reconocimiento separada compara la respuesta del proveedor con los caracteres conocidos del fixture. Un tercer test envía esa respuesta a través del formulario. Estos tests responden a preguntas diferentes y deben informar resultados separados.

¿Qué fallas debe investigar primero?

Investigue fallas de entrada local antes de calidad de reconocimiento. Un camino no legible, archivo vacío o clave faltante significa que la solicitud no se completó exitosamente. Cambiar el módulo de reconocimiento no puede resolver esas fallas.

Para fallas remotas, conserve el código de error del proveedor en un registro de diagnóstico controlado y consulte la referencia de errores de API oficial. Evite volcar el cuerpo de la solicitud, que contiene tanto la credencial como la imagen. Registre la etapa fallida y el identificador de error en su lugar.

La documentación de API global de Node cubre las primitivas de solicitud y cancelación usadas aquí. Finalizar la espera local no establece que el procesamiento remoto se haya cancelado.

Al reportar un problema, describa qué etapa falló. "Falló la lectura del archivo" y "el servicio devolvió texto que el formulario rechazó" requieren evidencia diferente. Mantenga las credenciales y los contenidos de imagen fuera de informes compartidos a menos que un proceso de soporte controlado los necesite explícitamente.

¿Qué se probó antes de usar un CAPTCHA en vivo?

El adaptador se ejecutó con siete casos de prueba locales que cubren la construcción de la solicitud y la preservación de Base64, credenciales faltantes, entrada vacía, fallas HTTP, errores del proveedor, resultados faltantes y respuestas malformadas o fallidas. Algunos casos agrupan afirmaciones relacionadas. Las pruebas reemplazaron fetch, por lo que no contactaron al servicio pagado.

El fixture de imagen verificó la codificación, y la respuesta fue un valor de prueba proporcionado. Estas verificaciones establecen el comportamiento de JavaScript local. No miden la precisión del reconocimiento ni prueban la aceptación por un formulario real. Complete esas pruebas con su clave de resolución y un desafío propiedad propio actual antes de depender de la integración.

Para tareas de token en la misma aplicación, use la guía separada JavaScript CAPTCHA API. Mantenga el reconocimiento de imagen en su propia rama porque el tipo de resultado y el flujo de recuperación documentado difieren. Pruebe CapSolver con una imagen propiedad propia representativa para validar esa conexión final.

Preguntas frecuentes

P: ¿Necesito un paquete de npm?

El adaptador usa APIs integradas de Node.js y no requiere ningún paquete de npm. Aún necesita un entorno compatible, una imagen válida y una clave de resolución. Node.js 24.16.0 se usó para las pruebas locales.

P: ¿Debería usar getTaskResult para ImageToTextTask?

El flujo de reconocimiento documentado devuelve un resultado listo con solution.text desde createTask. Este adaptador no realiza encuestas. Un bucle de encuestas de otra tarea de CAPTCHA no debe copiarse automáticamente.

P: ¿Puedo enviar una URL de imagen en lugar de Base64?

Esta solicitud documentada usa contenido de imagen codificado en el campo body. Obtenga la imagen propiedad propia a través de su aplicación y codifique sus bytes. Un nombre de archivo o URL no es equivalente a ese valor.

P: ¿Por qué podría rechazar el formulario el texto reconocido?

Verifique que la imagen y la sesión pertenezcan al mismo intento y que la respuesta no haya cambiado. Una cadena devuelta no establece ni la corrección del reconocimiento ni la aceptación de la aplicación.

P: ¿Las pruebas locales prueban la precisión del reconocimiento?

No. Usan respuestas proporcionadas para verificar el comportamiento del adaptador. El reconocimiento y la aceptación end-to-end requieren pruebas separadas contra el servicio en vivo y su formulario propiedad propio.