Skip to main content
Este documento presentará una guía sobre la integración de la API de reconocimiento de imágenes hCaptcha, que puede identificar el contenido ingresado por el usuario y la imagen del captcha hCaptcha, y finalmente devolver las coordenadas de la pequeña imagen que necesita ser clicada para completar la verificación.

​
Proceso de solicitud

Para utilizar la API de reconocimiento de imágenes hCaptcha, primero dirígete a la consola de Ace Data Cloud para obtener tu token de API, que debes guardar para uso futuro. Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, serás redirigido de nuevo a la página actual. Un token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio. La primera solicitud te otorgará un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en la consola.
📘 Documentación completa: API de reconocimiento de imágenes hCaptcha →

​
Uso básico

Primero, debes entender la forma básica de uso, que consiste en ingresar la imagen del captcha hCaptcha que necesitas procesar para obtener el resultado procesado. Primero, necesitas pasar un campo queries, que es la imagen del captcha hCaptcha específica. Debes capturar esta imagen del captcha en un sitio web que tenga hCaptcha; el enlace del sitio de ejemplo es: https://democaptcha.com/demo-form-eng/hcaptcha.html, haz clic en la casilla de verificación para mostrar la imagen completa del captcha, como se muestra en la siguiente imagen:

El campo queries es la captura de pantalla de la imagen del captcha mencionada anteriormente; se recomienda que el tamaño de la imagen no supere los 100 kb. También necesitas capturar la región señalada por la flecha roja en la imagen anterior, y deberás comprimir el tamaño de la imagen y convertirla a codificación Base64, como se muestra en la siguiente imagen:

Además, necesitas ingresar el parámetro de contenido de reconocimiento relacionado con la imagen del captcha question, que admite traducción en chino e inglés. Puedes ingresar directamente el contenido relacionado; de la imagen del sitio web anterior, se puede ver que el question debe ser Please click on the UNIQUE object among the others.. El contenido específico es el siguiente:

Aquí hemos configurado los encabezados de la solicitud, que incluyen:
  • accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, formato JSON.
  • authorization: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.
También se ha configurado el cuerpo de la solicitud, que incluye:
  • queries: lista de imágenes del captcha codificadas en Base64.
  • question: parámetro de contenido de reconocimiento relacionado con la imagen del captcha, que admite la entrada directa en chino e inglés.
Después de seleccionar, puedes ver que también se ha generado el código correspondiente a la derecha, como se muestra en la imagen:

Haz clic en el botón “Try” para realizar la prueba, como se muestra en la imagen anterior, y obtendremos el siguiente resultado:
El resultado devuelto tiene varios campos, que se describen a continuación:
  • solution, el resultado de la verificación después de procesar la imagen del captcha hCaptcha.
    • label, el contenido identificado de la imagen del captcha hCaptcha.
    • box, la información de ubicación del resultado de reconocimiento de la imagen del captcha hCaptcha, que está compuesta por la información de coordenadas de la imagen.
    • confidences, la confianza del reconocimiento de la imagen del captcha hCaptcha que cumple con el contenido de reconocimiento.
  • started_at, finished_at: el tiempo de inicio del procesamiento de esta solicitud y el tiempo de producción del resultado, en marca de tiempo Unix (segundos, punto flotante).
  • elapsed: el tiempo total de procesamiento de esta solicitud (segundos).
Como puedes ver, hemos obtenido el resultado de verificación del procesamiento de la imagen del captcha hCaptcha; solo necesitamos simular un clic en el área correspondiente de la imagen del captcha según la información de coordenadas de box para pasar la verificación. A continuación, se explicará cómo hacer clic en función de la información de ubicación de box. Primero, se establece un sistema de coordenadas rectangulares para la imagen del captcha cargada, donde el origen central está en la esquina inferior izquierda de la imagen; 360 es la coordenada horizontal correspondiente y 276 es la coordenada vertical correspondiente. Solo necesitamos simular un clic en las coordenadas correspondientes del captcha, como se muestra en la siguiente imagen:

Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código CURL es el siguiente:
El código de integración en Python es el siguiente:

​
Modo asíncrono (async)

Por defecto, la API es sincrónica y bloqueante: una solicitud esperará hasta que se complete el procesamiento del resultado de reconocimiento antes de devolverlo. Si estás haciendo rotación de múltiples solucionadores (multi-solver rotation) y deseas “enviar la tarea y obtener inmediatamente el task_id, luego programar otros solucionadores y volver más tarde para leer el resultado”, puedes pasar async: true en el cuerpo de la solicitud. Al pasar async: true, la interfaz devolverá inmediatamente un task_id, sin bloquear la espera:
Si desea consultar el progreso de manera proactiva, puede usar el task_id para consultar POST /captcha/tasks (se recomienda cada 3~5 segundos). Esta interfaz no activará ni avanzará el procesamiento de la tarea; incluso si no consulta, se pierde la conexión o sale del cliente, el servidor seguirá procesando:
Durante el procesamiento, se devolverá status: processing:
Al completar el procesamiento, se devolverá status: ready y el resultado de la identificación solution (la estructura de los campos es completamente consistente con el modo de sincronización):
Descripción de facturación: en modo asíncrono, la creación de tareas y la lectura del estado “procesando” no se facturan; el cliente se factura una vez al leer el resultado exitoso por primera vez (consistente con el comportamiento actual y el precio del modo de sincronización). El servidor avanzará la tarea por sí mismo, pero no cobrará anticipadamente porque el fondo se complete primero. Si la tarea no se completa con éxito en 120 segundos, se terminará con un HTTP 504 timeout, sin costo. /captcha/tasks no es responsable de avanzar la tarea.

​
Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:
  • 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 401 invalid_token: No autorizado, token de autorización inválido o faltante.
  • 429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
  • 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​
Ejemplo de respuesta de error

​
Conclusión

A través de este documento, ha aprendido cómo usar la API de reconocimiento de imágenes hCaptcha para que los usuarios ingresen el contenido reconocido y la imagen del captcha de hCaptcha, y finalmente devuelvan las coordenadas de la pequeña imagen que necesita ser clicada para completar la verificación. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.