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
POST /createTaskEnvía el tipo de captcha + los parámetros del sitio. Recibes un taskId al instante.
POST /getTaskResultConsulta cada ~1 s hasta que el estado sea ready. El token llega en el objeto solution.
POST /getBalanceComprueba los créditos restantes. Las resoluciones fallidas se reembolsan aquí automáticamente.
https://api.capzy.aiautenticación mediante clientKey en el cuerpo de la solicitudEndpoints
/createTaskCrea una nueva tarea de resolución de captcha{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultConsulta el resultado de la tarea{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceComprueba el saldo de la cuenta{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/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.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/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.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/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.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "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.
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.
Todas las cuentas nuevas empiezan aquí
Abre un ticket de soporte con tu volumen previsto (sin nivel de precio aparte, misma tarifa por resolución)
tareas simultáneasCuá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 tasaCuá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_EXISTNo 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_ALLOWEDLa 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_BLOCKEDTu 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_PARAMSEl 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_SITEKEYEl `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_SUPPORTEDEl `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_TYPEEl 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_REQUIREDEste 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_PROXYLos 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_REFUSEDEl 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_REACHEDAlcanzaste 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_LIMITEDEstá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_AVAILABLELa 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_MAINTENANCECapzy 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_TIMEOUTLa 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_UNSOLVABLEEl 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_RESULTEl 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_INTERNALError 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_BALANCEEl 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.
Playground de código
Ejemplos completos y funcionales en los principales lenguajes. Copia, pega tu API key y ejecuta.
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)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 →