Formatos de respuesta API CaptchaAI explicados

CaptchaAI utiliza respuestas simples basadas en texto. Esta referencia cubre todos los formatos de respuesta que encontrará, con ejemplos de análisis.

Enviar punto final (en.php)

Respuesta exitosa

OK|TASK_ID

Ejemplo: OK|73548291

Respuesta de error

ERROR_CODE

Ejemplo: ERROR_WRONG_USER_KEY

Analizando

resp = requests.get("https://ocr.captchaai.com/in.php", params={...})

if resp.text.startswith("OK|"):
    task_id = resp.text.split("|")[1]
else:
    error = resp.text
    raise Exception(f"Submit failed: {error}")

const resp = await axios.get("https://ocr.captchaai.com/in.php", { params });

if (resp.data.startsWith("OK|")) {
  const taskId = resp.data.split("|")[1];
} else {
  throw new Error(`Submit failed: ${resp.data}`);
}

Punto final de la consulta (res.php)

Respuesta no lista

CAPCHA_NOT_READY

La tarea aún se está procesando. Espere 5 segundos y vuelva a sondear.

Éxito: CAPTCHA basados en tokens

Para reCAPTCHA, Turnstile, hCaptcha y similares:

OK|03AGdBq24PBCbw...long_token_string

Éxito — Image/OCR CAPTCHA

OK|abc123

El texto después de OK| es el texto reconocido de la imagen.

Éxito - GeeTest

OK|challenge:abc123,validate:def456,seccode:ghi789

Analiza cada campo:

if result.text.startswith("OK|"):
    data = result.text.split("|")[1]
    parts = dict(item.split(":") for item in data.split(","))
    challenge = parts["challenge"]
    validate = parts["validate"]
    seccode = parts["seccode"]

Éxito — Cloudflare Challenge

Devuelve el valor de la cookie qa_validation_cookie y el agente de usuario:

OK|qa_validation_cookie=abc123;user_agent=Mozilla/5.0...

Respuesta de error

ERROR_CODE

Plantilla de análisis

def parse_result(response_text):
    if response_text == "CAPCHA_NOT_READY":
        return {"status": "pending"}

    if response_text.startswith("OK|"):
        return {"status": "solved", "result": response_text.split("|", 1)[1]}

    return {"status": "error", "error": response_text}

Endpoint de balance

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=getbalance

Respuesta:

1.234

Un número decimal que representa su saldo en USD.

balance = float(requests.get("https://ocr.captchaai.com/res.php", params={
    "key": API_KEY, "action": "getbalance"
}).text)
print(f"Balance: ${balance:.2f}")

Endpoints de reporte

Reportar como correcto

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=reportgood&id=TASK_ID

Respuesta: OK_REPORT_RECORDED

Reportar como incorrecto

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=reportbad&id=TASK_ID

Respuesta: OK_REPORT_RECORDED

Informar malas soluciones ayuda a mejorar la precisión y puede acreditar su saldo.

Códigos de error comunes

Ejemplo de consulta completo

import requests
import time

API_KEY = "YOUR_API_KEY"

def solve_captcha(submit_params, timeout=300):
    """Generic solver with proper response handling."""
    submit_params["key"] = API_KEY

    # Submit
    resp = requests.get("https://ocr.captchaai.com/in.php", params=submit_params)
    if not resp.text.startswith("OK|"):
        raise Exception(f"Submit error: {resp.text}")

    task_id = resp.text.split("|")[1]

    # Poll
    deadline = time.time() + timeout
    while time.time() < deadline:
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY,
            "action": "get",
            "id": task_id
        })

        parsed = parse_result(result.text)

        if parsed["status"] == "pending":
            continue
        elif parsed["status"] == "solved":
            return parsed["result"]
        else:
            raise Exception(f"Solve error: {parsed['error']}")

    raise TimeoutError(f"Task {task_id} timed out after {timeout}s")

Preguntas frecuentes

¿Por qué la respuesta utiliza delimitadores de canalización (|) en lugar de JSON?

El formato de CaptchaAI está optimizado para simplificar. Las respuestas delimitadas por barras verticales son más pequeñas y más rápidas de analizar que JSON. Para datos estructurados (resultados de GeeTest), los datos después de OK| contienen pares clave-valor.

¿Cómo manejo los errores de red?

Los errores de red son independientes de los errores de API; envée la llamada en un bloque try/except y reintenta en ConnectionError o Timeout.

¿Cuál es la longitud máxima del token?

Los tokens reCAPTCHA pueden tener hasta ~500 caracteres. Utilice siempre split("|", 1) (división máxima de 1) para evitar dividir el token.

Guías relacionadas

• Configuración y autenticación de API key
• Referencia de códigos de error CaptchaAI
• Inicio rápido de CaptchaAI

Configuración recomendada para su pipeline

Use exactamente la misma configuración de navegador en todos sus entornos de QA, staging y CI. Esto evita que un test funcione en local y falle en CI sin razón aparente.

from selenium import webdriver

def make_driver(headless: bool = True) -> webdriver.Chrome:
    options = webdriver.ChromeOptions()
    if headless:
        options.add_argument('--headless=new')
    options.add_argument('--window-size=1280,800')
    options.add_argument('--lang=es-ES')
    return webdriver.Chrome(options=options)

Mantener viewport, idioma y user-agent por defecto idénticos en todos los runners reduce la varianza y facilita comparar resultados entre ejecuciones de su propio QA.

Cómo se integra CaptchaAI en su pipeline propio

El patrón de integración con CaptchaAI siempre es el mismo, independientemente del lenguaje o framework de pruebas que use:

1. Su test detecta el widget de CAPTCHA en la página de su propia aplicación (formulario de QA, landing de staging, endpoint de preproducción).
2. Su test envía a CaptchaAI los datos públicos del widget (sitekey, URL de la página, tipo de CAPTCHA).
3. CaptchaAI devuelve un token válido para esa página.
4. Su test inyecta ese token en el campo correspondiente y envía el formulario.
5. Su backend verifica el token con el proveedor de CAPTCHA, exactamente igual que con un usuario real.

Este flujo se aplica únicamente a integraciones que usted controla. No se utiliza para sortear protecciones de sitios de terceros.

Métricas y observabilidad

Incluya métricas específicas para los pasos relacionados con CAPTCHA en sus pipelines de QA. Esto le permite detectar regresiones en su propia integración antes de que lleguen a producción:

• Tiempo de resolución por intento — desde la solicitud a CaptchaAI hasta la entrega del token.
• Tasa de éxito por endpoint propio — cuántas verificaciones backend pasan respecto al total de intentos.
• Distribución de errores — agrupados por código (ERROR_*, timeouts internos, fallos de red).
• Latencia extremo a extremo — incluyendo render de la página, resolución de CAPTCHA y respuesta de su backend.

Conserve trazas (logs, capturas, HAR) durante un período razonable para poder reproducir incidentes en su entorno QA cuando un test falle de forma intermitente.

Buenas prácticas en su entorno QA

• Pruebe siempre sobre su propia aplicación o sobre entornos explícitamente autorizados.
• Mantenga una API key de CaptchaAI separada para QA, distinta de la de producción, para no mezclar métricas.
• Defina timeouts y reintentos razonables (backoff exponencial) para no acumular trabajos pendientes en CaptchaAI durante caídas.
• Versione sus snapshots de configuración (sitekey, action, umbrales) junto al código de los tests.
• Revise periódicamente el changelog de su proveedor de CAPTCHA para anticipar cambios que afecten a su propia integración.

Solución de problemas

Valide sus integraciones CAPTCHA en entornos propios con CaptchaAI.