> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # hCaptcha API de reconocimiento de imágenes > hCaptcha verification code recognition service API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) para obtener tu token de API, que debes guardar para uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [API de reconocimiento de imágenes hCaptcha →](https://platform.acedata.cloud/documents/recognition-hcaptcha-integration) ## 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: ```json theme={null} { "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: ```shell theme={null} 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: ```python theme={null} 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: ```shell theme={null} 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 }' ``` ```json theme={null} { "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: ```shell theme={null} 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`: ```json theme={null} { "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): ```json theme={null} { "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 ```json theme={null} { "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.