Saltar al contenido

Documentación de la API

Tres endpoints y ejemplos de código completos en seis lenguajes. Intégralo en menos de 60 segundos con el clúster de solvers de alto rendimiento de Capzy.

Inicio rápido

paso 1
POST /createTask

Envía el tipo de captcha + los parámetros del sitio. Recibes un taskId al instante.

paso 2
POST /getTaskResult

Consulta cada ~1 s hasta que el estado sea ready. El token llega en el objeto solution.

paso 3
POST /getBalance

Comprueba los créditos restantes. Las resoluciones fallidas se reembolsan aquí automáticamente.

url basehttps://api.capzy.aiautenticación mediante clientKey en el cuerpo de la solicitud

Endpoints

POST/createTaskCrea una nueva tarea de resolución de captcha
solicitud
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
respuesta
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultConsulta el resultado de la tarea
solicitud
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
respuesta
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceComprueba el saldo de la cuenta
solicitud
{ "clientKey": "capzy_..." }
respuesta
{ "errorId": 0, "balance": 9.50 }
POST/reportScoreOpcional: devuelve la puntuación verificada de Google para tareas V3. Alimenta la vista de calidad de V3 de tu panel. Un informe por tarea; los informes deben llegar en las 24 horas siguientes a completar la resolución.
solicitud
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
respuesta
{ "errorId": 0 }
POST/reportCorrectCaptchaOpcional: indícanos que el sitio de destino ACEPTÓ la resolución. Especialmente útil para tipos que devuelven coordenadas (p. ej. el slider de Shopee), en los que devolvemos una posición y tu propio navegador realiza el arrastre. Este informe es nuestra única señal de precisión en el mundo real. Un informe por tarea, en un plazo de 24 horas; nunca afecta al precio.
solicitud
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
respuesta
{ "errorId": 0 }
POST/reportIncorrectCaptchaOpcional: indícanos que el sitio de destino RECHAZÓ la resolución. Alimenta el mismo seguimiento de precisión en el mundo real que /reportCorrectCaptcha. Un informe por tarea, en un plazo de 24 horas; nunca afecta al precio.
solicitud
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
respuesta
{ "errorId": 0 }

Tipos de tarea compatibles

Cargando…

Lista en vivo de los tipos de tarea activos actualmente, agrupados por proveedor de captcha. Los precios y el tiempo medio de resolución se actualizan automáticamente con la telemetría del clúster.

Cargando tipos de tarea…

Límites de tasa

Los límites se aplican por cuenta, sumando todas las API keys que posees. Superar el límite devuelve un código de error sin consumir créditos.

Predeterminado
30 simultáneas · 30 req/s

Todas las cuentas nuevas empiezan aquí

Mayor concurrencia
300+ simultáneas · 100+ req/s

Abre un ticket de soporte con tu volumen previsto (sin nivel de precio aparte, misma tarifa por resolución)

tareas simultáneas

Cuántas tareas puedes tener en la cola de resolución a la vez. Una tarea cuenta para tu límite desde createTask hasta que termina (éxito, fallo o timeout).

límite de tasa

Cuántas llamadas a createTask puedes hacer por segundo. Ventana deslizante, aplicada por cuenta. Superar la tasa devuelve ERROR_RATE_LIMITED sin descontar créditos.

Códigos de error

Todos los errores que devuelven /createTask / /getTaskResult con su solución. Las resoluciones fallidas se reembolsan automáticamente: los créditos vuelven a tu saldo de inmediato.

Autenticación

Problemas con tu API key o tu IP.
  • ERROR_KEY_DOES_NOT_EXIST

    No se reconoció tu API key.

    soluciónRevisa el valor en Panel → API Keys. Las keys empiezan por `capzy_`. Las keys rotadas se invalidan de inmediato.

    #
  • ERROR_IP_NOT_ALLOWED

    La IP de tu solicitud no está en la lista de permitidas de la API key.

    soluciónAñade tu IP a la lista de permitidas de la key en Panel → API Keys, o elimina la lista por completo si no necesitas fijar IPs.

    #
  • ERROR_IP_BLOCKED

    Tu IP está bloqueada temporalmente por enviar demasiadas solicitudes no válidas.

    soluciónBloqueamos las IPs que envían más de 100 solicitudes no válidas en 10 minutos (de forma escalonada). Corrige el fallo que provoca las solicitudes no válidas y espera. Los bloqueos caducan solos, desde 1 minuto hasta 24 horas según el nivel.

    #

Validación

Parámetros de tarea incorrectos o tipo equivocado para la sitekey.
  • ERROR_INVALID_PARAMS

    El cuerpo de la solicitud estaba mal formado o le faltaban campos obligatorios.

    soluciónComprueba que `clientKey` está en el nivel superior y que `task` contiene `type` más el identificador obligatorio (websiteURL/websiteKey/captchaId/etc). Consulta la sección Tipos de tarea para ver los parámetros obligatorios de cada tipo.

    #
  • ERROR_BAD_SITEKEY

    El `websiteKey` no está registrado en ningún proveedor de captcha que podamos identificar.

    soluciónAsegúrate de copiar la sitekey completa de la página de destino (busca `data-sitekey`, `sitekey:` o el parámetro en `grecaptcha.render` / `hcaptcha.render`).

    #
  • ERROR_TASK_NOT_SUPPORTED

    El `type` de tarea que enviaste no es un tipo de captcha que Capzy admita actualmente.

    soluciónConsulta la sección Tipos de tarea más abajo para ver la lista completa de activos. Si necesitas un captcha que no aparece, abre un ticket y lo priorizaremos.

    #
  • ERROR_WRONG_TASK_TYPE

    El tipo de tarea no coincide con el proveedor real de la sitekey.

    soluciónVerificamos previamente las sitekeys contra su proveedor real. La respuesta de error incluye un campo `recommended`: cambia a ese tipo de tarea. (No se cobra ningún crédito.)

    #
  • ERROR_PROXY_REQUIRED

    Este captcha está ligado a la IP: sus tokens quedan vinculados a la IP que los resolvió.

    soluciónCambia a la variante `*Task` (en lugar de `*TaskProxyLess`) y pasa un `proxyAddress` que coincida con la IP que usarás para enviar el token. Afecta a: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.

    #
  • ERROR_NO_PROXY

    Los campos de proxy son obligatorios para este tipo de tarea, pero faltaban.

    soluciónIncluye `proxyType`, `proxyAddress`, `proxyPort` (y opcionalmente `proxyLogin`/`proxyPassword`/`userAgent`) en el cuerpo de tu tarea.

    #
  • ERROR_PROXY_CONNECT_REFUSED

    El proxy que proporcionaste rechazó la conexión.

    soluciónRevisa las credenciales del proxy, la accesibilidad del host y que la IP esté activa. Prueba primero el mismo proxy desde tu propia máquina para aislar problemas del proveedor.

    #

Límites de tasa

Topes de simultaneidad / por segundo / de ratio de reembolsos.
  • ERROR_MAX_TASKS_REACHED

    Alcanzaste el tope de tareas simultáneas de tu nivel de cuenta.

    soluciónEspera a que terminen las tareas en curso antes de enviar más. El nivel Regular predeterminado es de 30 simultáneas; contacta con soporte para ampliarlo.

    #
  • ERROR_RATE_LIMITED

    Estás enviando /createTask más rápido de lo que permite tu límite de tasa.

    soluciónReduce el ritmo y reintenta. El nivel Regular predeterminado es de 30 req/s con ventana deslizante. Superar la tasa no consume créditos.

    #
  • ERROR_NO_SLOT_AVAILABLE

    La capacidad del clúster está saturada temporalmente.

    soluciónReintenta tras unos segundos (es algo transitorio). Si persiste durante minutos, consulta status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy está en mantenimiento programado.

    soluciónReintenta tras la ventana de mantenimiento. Publicamos avisos con antelación en la página de estado.

    #

Resultados de resolución

Lo que devolvió el solver. Las resoluciones fallidas se reembolsan automáticamente.
  • ERROR_TIMEOUT

    La tarea no se completó dentro del tiempo máximo de su tipo.

    soluciónReembolsada automáticamente, sin cargo. La mayoría de los timeouts son transitorios. Si un captcha concreto agota el tiempo de forma constante, abre un ticket con el UUID de la tarea.

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    El solver agotó sus reintentos en este desafío.

    soluciónReembolsada automáticamente, sin cargo. Causas habituales: sitekey obsoleta, websiteURL no coincide con el dominio donde está incrustado o el sitio de destino desactivó el captcha.

    #
  • ERROR_NULL_RESULT

    El solver terminó pero no devolvió ningún token.

    soluciónReembolsada automáticamente. Suele indicar que el sitio de destino quitó el captcha durante la resolución. Reintenta; si persiste, abre un ticket.

    #
  • ERROR_INTERNAL

    Error inesperado dentro del pipeline de resolución.

    soluciónReembolsada automáticamente. Reintenta (son poco frecuentes). Si los ves en un bucle constante, abre un ticket con el UUID de la tarea.

    #
  • ERROR_ZERO_BALANCE

    El saldo de la cuenta es demasiado bajo para cubrir el coste de la tarea.

    soluciónAgrega créditos desde Panel → Facturación. Las resoluciones fallidas se reembolsan automáticamente, así que solo pagas por los tokens exitosos.

    #

Informes de puntuación

Errores específicos de /reportScore (feedback de calidad de V3).
  • ERROR_TASK_NOT_FOUND

    /reportScore: el taskId no pertenece a tu cuenta o se purgó.

    soluciónLos informes de puntuación deben hacer referencia a una tarea tuya y enviarse en las 24 h siguientes a completar la resolución.

    #
  • ERROR_TASK_NOT_READY

    /reportScore: la tarea sigue en proceso o ya falló.

    soluciónSolo se pueden puntuar las tareas `ready`. Espera a que /getTaskResult devuelva ready antes de informar.

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore: pasaron más de 24 h desde que se completó la resolución.

    soluciónInforma las puntuaciones a los pocos minutos de tu llamada a siteverify. Es cuando los datos resultan más útiles para nuestro panel de calidad de V3.

    #
06

Playground de código

Ejemplos completos y funcionales en los principales lenguajes. Copia, pega tu API key y ejecuta.

solve.py
import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": "https://example.com",
        "websiteKey": "0x4AAA..."
    }
}).json()

task_id = task["taskId"]

# Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break

    time.sleep(1)
Vista previa de la salidaÉxito (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Intégralo en menos de 60 segundos.

$0.10 en créditos gratis al registrarte. No se requiere tarjeta de crédito.

Obtén tu API key gratis →