Documentation API
Trois endpoints, des exemples de code complets dans six langages. Intégrez en moins de 60 secondes le cluster de solveurs hautes performances de Capzy.
Démarrage rapide
POST /createTaskEnvoyez le type de captcha + les paramètres du site. Vous recevez instantanément un taskId.
POST /getTaskResultInterrogez toutes les ~1 s jusqu’à ce que le statut soit ready. Le jeton arrive dans l’objet solution.
POST /getBalanceVérifiez les crédits restants. Les résolutions échouées y sont remboursées automatiquement.
https://api.capzy.aiauthentification via clientKey dans le corps de la requêteEndpoints
/createTaskCréer une nouvelle tâche de résolution de captcha{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultInterroger le résultat d’une tâche{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceConsulter le solde du compte{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/reportScoreFacultatif : renvoyez le score vérifié par Google pour les tâches V3. Alimente la vue qualité V3 de votre tableau de bord. Un rapport par tâche ; les rapports doivent arriver dans les 24 heures suivant la fin de la résolution.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/reportCorrectCaptchaFacultatif : indiquez-nous que la résolution a été ACCEPTÉE par le site cible. Particulièrement utile pour les types renvoyant des coordonnées (ex. slider Shopee), pour lesquels nous renvoyons une position et votre propre navigateur effectue le glissement. Ce rapport est notre seul signal de précision en conditions réelles. Un rapport par tâche, dans les 24 heures ; n’affecte jamais la tarification.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptchaFacultatif : indiquez-nous que la résolution a été REFUSÉE par le site cible. Alimente le même suivi de précision en conditions réelles que /reportCorrectCaptcha. Un rapport par tâche, dans les 24 heures ; n’affecte jamais la tarification.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }Types de tâches pris en charge
Chargement…Liste en direct des types de tâches actuellement activés, regroupés par fournisseur de captcha. Les prix et temps de résolution moyens se mettent à jour automatiquement à partir de la télémétrie du cluster.
Limites de débit
Les limites s’appliquent par compte, cumulées sur toutes les clés API que vous possédez. Dépasser la limite renvoie un code d’erreur sans consommer de crédits.
Tous les nouveaux comptes démarrent ici
Ouvrez un ticket de support en indiquant votre volume prévu (pas de palier tarifaire distinct, même tarif par résolution)
tâches simultanéesLe nombre de tâches que vous pouvez avoir en même temps dans la file de résolution. Une tâche compte dans votre limite depuis createTask jusqu’à sa fin (réussite, échec ou timeout).
limite de débitLe nombre d’appels createTask que vous pouvez effectuer par seconde. Fenêtre glissante, appliquée par compte. Dépasser la limite renvoie ERROR_RATE_LIMITED sans débit de crédits.
Codes d’erreur
Toutes les erreurs renvoyées par /createTask / /getTaskResult, avec leur correctif. Les résolutions échouées sont remboursées automatiquement : les crédits reviennent immédiatement sur votre solde.
Authentification
Problèmes liés à votre clé API ou à votre IP.- #
ERROR_KEY_DOES_NOT_EXISTVotre clé API n’a pas été reconnue.
correctifVérifiez la valeur dans Tableau de bord → Clés API. Les clés commencent par `capzy_`. Les clés renouvelées sont invalidées immédiatement.
- #
ERROR_IP_NOT_ALLOWEDL’IP de votre requête ne figure pas dans la liste d’autorisation de la clé API.
correctifAjoutez votre IP à la liste d’autorisation de la clé dans Tableau de bord → Clés API, ou supprimez entièrement la liste si vous n’avez pas besoin de restreindre par IP.
- #
ERROR_IP_BLOCKEDVotre IP est temporairement bannie pour avoir envoyé trop de requêtes invalides.
correctifNous bannissons les IP qui envoient plus de 100 requêtes invalides en 10 minutes (de façon progressive). Corrigez le bug à l’origine des requêtes invalides, puis patientez. Les bannissements expirent automatiquement au bout de 1 minute à 24 heures selon le niveau.
Validation
Paramètres de tâche incorrects ou mauvais type pour la sitekey.- #
ERROR_INVALID_PARAMSLe corps de la requête est mal formé ou des champs obligatoires sont manquants.
correctifVérifiez que `clientKey` est au premier niveau et que `task` contient `type` ainsi que l’identifiant requis (websiteURL/websiteKey/captchaId/etc). Consultez la section Types de tâches pour les paramètres requis par type.
- #
ERROR_BAD_SITEKEYLa `websiteKey` n’est enregistrée auprès d’aucun fournisseur de captcha que nous puissions identifier.
correctifAssurez-vous de copier la sitekey complète depuis la page cible (cherchez `data-sitekey`, `sitekey:` ou le paramètre dans `grecaptcha.render` / `hcaptcha.render`).
- #
ERROR_TASK_NOT_SUPPORTEDLe `type` de tâche soumis n’est pas un type de captcha actuellement pris en charge par Capzy.
correctifConsultez la section Types de tâches ci-dessous pour la liste complète des types activés. Si vous avez besoin d’un captcha non listé, ouvrez un ticket et nous le traiterons en priorité.
- #
ERROR_WRONG_TASK_TYPELe type de tâche ne correspond pas au fournisseur réel de la sitekey.
correctifNous vérifions en amont les sitekeys auprès de leur fournisseur réel. La réponse d’erreur inclut un champ `recommended` : passez à ce type de tâche. (Aucun crédit débité.)
- #
ERROR_PROXY_REQUIREDCe captcha est lié à l’IP : ses jetons sont liés à l’IP qui les a résolus.
correctifPassez à la variante `*Task` (au lieu de `*TaskProxyLess`) et indiquez un `proxyAddress` correspondant à l’IP que vous utiliserez pour soumettre le jeton. Concerne : Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.
- #
ERROR_NO_PROXYLes champs proxy sont obligatoires pour ce type de tâche, mais ils sont absents.
correctifIncluez `proxyType`, `proxyAddress`, `proxyPort` (et éventuellement `proxyLogin`/`proxyPassword`/`userAgent`) dans le corps de votre tâche.
- #
ERROR_PROXY_CONNECT_REFUSEDLe proxy fourni a refusé la connexion.
correctifVérifiez les identifiants du proxy, l’accessibilité de l’hôte et que l’IP est active. Testez d’abord le même proxy depuis votre propre machine pour isoler les problèmes du fournisseur.
Limites de débit
Limites de concurrence / par seconde / de taux de remboursement.- #
ERROR_MAX_TASKS_REACHEDVous avez atteint la limite de tâches simultanées de votre niveau de compte.
correctifAttendez la fin des tâches en cours avant d’en soumettre d’autres. Le niveau Standard par défaut autorise 30 tâches simultanées ; contactez le support pour passer à un niveau supérieur.
- #
ERROR_RATE_LIMITEDVous soumettez des /createTask plus vite que votre limite de débit.
correctifRalentissez et réessayez. Le niveau Standard par défaut est de 30 req/sec en fenêtre glissante. Dépasser la limite ne consomme pas de crédits.
- #
ERROR_NO_SLOT_AVAILABLELa capacité du cluster est temporairement saturée.
correctifRéessayez au bout de quelques secondes (c’est passager). Si cela persiste pendant plusieurs minutes, consultez status.capzy.ai.
- #
ERROR_SYSTEM_MAINTENANCECapzy est en maintenance programmée.
correctifRéessayez après la fenêtre de maintenance. Nous publions des avis à l’avance sur la page de statut.
Résultats de résolution
Ce que le solveur a renvoyé. Les résolutions échouées sont remboursées automatiquement.- #
ERROR_TIMEOUTLa tâche ne s’est pas terminée dans le délai maximal prévu pour son type.
correctifRemboursé automatiquement, sans frais. La plupart des timeouts sont passagers. Si un captcha précis expire systématiquement, ouvrez un ticket avec l’UUID de la tâche.
- #
ERROR_CAPTCHA_UNSOLVABLELe solveur a épuisé son budget de tentatives sur ce défi.
correctifRemboursé automatiquement, sans frais. Causes fréquentes : sitekey périmée, websiteURL ne correspondant pas au domaine d’intégration, captcha désactivé par le site cible.
- #
ERROR_NULL_RESULTLe solveur a terminé mais n’a renvoyé aucun jeton.
correctifRemboursé automatiquement. Indique généralement que le site cible a retiré le captcha en cours de résolution. Réessayez ; si cela persiste, ouvrez un ticket.
- #
ERROR_INTERNALErreur inattendue dans le pipeline de résolution.
correctifRemboursé automatiquement. Réessayez (ces erreurs sont rares). Si vous les voyez en boucle, ouvrez un ticket avec l’UUID de la tâche.
- #
ERROR_ZERO_BALANCESolde du compte insuffisant pour couvrir le coût de la tâche.
correctifAjoutez des crédits depuis Tableau de bord → Facturation. Les résolutions échouées sont remboursées automatiquement : vous ne payez que les jetons réussis.
Rapports de score
Erreurs propres à /reportScore (retour qualité V3).- #
ERROR_TASK_NOT_FOUND/reportScore : le taskId n’appartient pas à votre compte ou a été purgé.
correctifLes rapports de score doivent concerner une tâche qui vous appartenait et être envoyés dans les 24 h suivant la fin de la résolution.
- #
ERROR_TASK_NOT_READY/reportScore : la tâche est toujours en cours ou a déjà échoué.
correctifSeules les tâches `ready` peuvent recevoir un score. Attendez que /getTaskResult renvoie ready avant de faire votre rapport.
- #
ERROR_REPORT_TOO_LATE/reportScore : plus de 24 h se sont écoulées depuis la fin de la résolution.
correctifEnvoyez les scores dans les minutes qui suivent votre appel siteverify. C’est à ce moment que les données sont les plus utiles pour notre tableau de bord de qualité V3.
Playground de code
Des exemples complets et fonctionnels dans tous les principaux langages. Copiez, collez votre clé API, exécutez.
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)Ressources
Intégrez en moins de 60 secondes.
$0.10 de crédits offerts à l’inscription. Aucune carte bancaire requise.
Obtenez votre clé API gratuite →