hCaptcha API de reconocimiento de imágenes

Este documento presentará una descripció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 para 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 captcha 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 sugiere 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:

{
  "solution": {
    "label": "Please click on the UNIQUE object among the others",
    "box": [
      "360",
      "276"
    ],
    "confidences": 0.6354503631591797
  }
}

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 de que el contenido de reconocimiento se cumple después del reconocimiento de la imagen del captcha hCaptcha.

Podemos ver que 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:

Si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código CURL es el siguiente:

curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'

El código de integración en Python es el siguiente:

import requests

url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "question": "Please click on the UNIQUE object among the others.",
    "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

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 “recibir el task_id inmediatamente después de enviar la tarea, para luego programar otros solucionadores y volver más tarde a obtener 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:

curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"],
  "async": true
}'

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab",
  "status": "processing"
}

Luego, use el task_id para hacer polling en POST /captcha/tasks (se recomienda cada 3~5 segundos) para obtener resultados:

curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'

Mientras se procesa, se devolverá status: processing:

{ "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" }

Cuando se complete el procesamiento, se devolverá status: ready y el resultado de la identificación solution (la estructura del campo es completamente consistente con el modo síncrono):

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "solution": {
    "label": "Por favor, haga clic en el objeto ÚNICO entre los demás",
    "box": ["360", "276"],
    "confidences": 0.6354503631591797
  }
}

Descripción de facturación: en modo asíncrono, la creación de tareas y el polling “en procesamiento” no se facturan; solo se factura una vez al obtener con éxito el resultado de identificación (el mismo precio que en modo síncrono). Por lo tanto, cancelar tareas que aún no se han completado durante el ciclo de rotación no generará costos. /captcha/tasks es común para todas las interfaces de captcha (token y serie de reconocimiento), se puede hacer polling con el mismo task_id.

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la obtención falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusión

A través de este documento, ha aprendido cómo usar la API de reconocimiento de imágenes hCaptcha para permitir que los usuarios ingresen el contenido reconocido y la imagen del captcha de hCaptcha, y finalmente devolver 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.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

hCaptcha API de reconocimiento de imágenes

Proceso de solicitud

Uso básico

Modo asíncrono (async)

Manejo de errores

Ejemplo de respuesta de error

Conclusión

​Proceso de solicitud

​Uso básico

​Modo asíncrono (async)

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

Proceso de solicitud

Uso básico

Modo asíncrono (async)

Manejo de errores

Ejemplo de respuesta de error

Conclusión