POST /captcha/tasks. Cuando llamas a cualquier interfaz de captcha (serie de token o serie de reconocimiento) y pasas async: true, la interfaz devolverá inmediatamente un task_id, el servidor tomará el control y continuará procesando; puedes usar ese task_id para consultar el resultado final, pero la consulta no es un requisito para que la tarea continúe ejecutándose. Es adecuado para escenarios como la rotación de múltiples solucionadores (multi-solver rotation): después de enviar la tarea, obtienes inmediatamente el task_id, primero puedes programar otros solucionadores y luego volver más tarde para leer el resultado.
📘 Documentación interactiva completa (incluida la depuración en línea): API de consulta de tareas de captcha →
Proceso de solicitud
Para usar esta interfaz, primero ve a la consola de Ace Data Cloud para obtener tu API Token, que debes guardar como respaldo. Un API Token es suficiente para llamar a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio.Uso básico
Paso 1: Crear una tarea de forma asíncrona
En el cuerpo de la solicitud de cualquier interfaz de captcha, pasaasync: true, la interfaz devolverá inmediatamente un task_id (HTTP 201), sin bloquear la espera:
Paso 2 (opcional): Consultar resultados con task_id
Si deseas ver el progreso de manera proactiva, puedes usar eltask_id devuelto en el paso anterior para consultar POST /captcha/tasks (se recomienda cada 3 a 5 segundos). Esta interfaz no activará ni avanzará el procesamiento de la tarea; al leer los resultados listos, se mantiene el comportamiento de liquidación única existente:
status: processing:
status: ready y el campo de resultado correspondiente; la estructura del campo es completamente consistente con el modo sincrónico:
- Serie de token (hcaptcha, recaptcha2, recaptcha3) devuelve
token:
- Clasificación de reconocimiento (recognition/recaptcha2, recognition/hcaptcha) devuelve
solution; recognition/image2text devuelvetext.
/captcha/tasks es común para todas las interfaces de captcha (serie de token y reconocimiento), se puede hacer polling con el mismo task_id.
El servidor continuará procesando desde el momento de la creación, durante un máximo de 120 segundos. Si en la última consulta antes de la fecha límite aún no se obtiene un resultado, se persistirá un HTTP 504. Este estado es terminal, el cliente debe detener el polling; consultar repetidamente el mismo task_id devolverá de manera estable el mismo resultado de fallo:
status: ready y HTTP 504 incluirán campos de temporización.
started_at, hora de inicio del procesamiento de la tarea, marca de tiempo Unix (segundos, flotante).finished_at, hora de producción del resultado de la tarea, marca de tiempo Unix (segundos, flotante). Este campo no se devuelve mientras se esté procesando.elapsed, tiempo de procesamiento de la tarea, en segundos (flotante, con 3 decimales). Este campo no se devuelve mientras se esté procesando.
Instrucciones de facturación
En modo asíncrono, la creación de tareas y la lectura del estado “en procesamiento” no se facturan; se factura una vez al cliente cuando lee el resultado exitoso por primera vez (consistente con el comportamiento existente y el precio del modo sincrónico). El servidor avanzará la tarea de forma autónoma, pero no cobrará anticipadamente porque el backend complete antes. Las tareas que no se completen dentro de los 120 segundos de la fecha límite se terminan con HTTP 504 y no se facturan.Manejo de errores
Al llamar a esta interfaz, si se encuentra con un error, se devolverá el código de error y la información correspondiente. Por ejemplo:400 invalid_request: falta el parámetrotask_iden la solicitud.401 invalid_token: no autorizado, el token de autorización es inválido o está ausente.404 not_found:task_idno existe o no pertenece a la cuenta actual.504 timeout: la tarea ha sido terminada y no ha producido resultados; por favor, detén el polling de esetask_id. Este fallo no generará cargos.