Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous détenez une autorisation écrite. Il ne porte ni sur l'automatisation de sites tiers, ni sur des techniques d'anti-détection.
Le screencast de l'extension CaptchaAI se suit sans accroc quand vous traitez l'extension comme un workflow navigateur reproductible, et non comme un bouton à activer une fois. Quatre points font la stabilité : l'état du compte, le profil du navigateur, le choix du gestionnaire de CAPTCHA et le comportement après la résolution sur la page cible. C'est là que naissent la plupart des confusions côté extension.
Ce que fait vraiment l'extension CaptchaAI
Votre composant interne appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. L'extension expose une seule API pour toutes les familles prises en charge : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, image/OCR et grilles d'images.
Le workflow de l'extension, étape par étape
- Capturez ce que le solveur attend. Inspectez la page ou l'appel réseau et ne conservez que les paramètres de la famille de CAPTCHA : sitekey, URL de la page, action, proxy optionnel.
- Envoyez la tâche à
in.phpavecjson=1. Tout statut différent de1est une erreur : journalisez la réponse complète. - Interrogez le résultat sur
res.php. Attendez 15 s avant la première interrogation, puis interrogez toutes les 5 s, avec un plafond strict de 120 s par tâche. - Appliquez le token dans la même session que celle qui a déclenché le défi : même contexte de navigateur, même client HTTP, même cookie jar. Une session dépareillée est la première cause de rejet après résolution.
- Mesurez la latence, les retries et l'acceptation en aval. Réussite de la résolution et réussite du workflow sont deux métriques distinctes.
Configuration des secrets et de la clé API
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI. Le déploiement la monte en variable d'environnement au runtime, jamais en clair dans le code source. Une stratégie de retry idempotent avec backoff exponentiel borné (trois tentatives, plafond à 30 s) absorbe les erreurs transitoires.
Exemple de code
Exemple côté client de votre propre suite de tests :
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
def get_balance() -> float:
resp = requests.post(
'https://api.captchaai.com/getBalance',
json={'clientKey': API_KEY},
timeout=15,
)
resp.raise_for_status()
return float(resp.json().get('balance', 0))
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry) pour rejouer un scénario complet à partir d'un identifiant unique. Si vous déployez vos workers sur Scaleway ou OVHcloud en région Paris (eu-west-3), suivez la latence réseau, et minimisez les données personnelles dans les logs, dans l'esprit du RGPD.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord, stockez-la en secret CI. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre manquant ou malformé. | Revalidez l'URL et le sitekey contre le HTML live. |
| Token refusé après résolution | Token appliqué dans une autre session. | Gardez résolution et soumission dans le même contexte. |
FAQ
L'extension fonctionne-t-elle en mode serveur, sans interface ?
Oui. Le déroulé reste identique : capturez les paramètres, interrogez le résultat, puis injectez le token dans la session qui a déclenché le défi. La même logique se pilote depuis un worker headless en CI ou un cron, tant que le contexte de session reste cohérent.
Pourquoi mon token est-il refusé après la résolution ?
Presque toujours parce qu'il est appliqué dans une session différente de celle du défi. Conservez le même contexte de navigateur, le même client HTTP et le même cookie jar entre résolution et soumission.
Combien cela coûte-t-il à mesure que le volume augmente ?
La facturation se fait par thread simultané, pas par résolution : le plan BASIC ($15/mois, 5 threads) inclut des résolutions illimitées par thread. Les vrais postes de coût sont les mauvais paramètres et les tempêtes de retries.
Quelles familles de CAPTCHA sont prises en charge ?
reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles d'images. CaptchaFox, Friendly Captcha et Lemin sont en bêta. hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir.
Guides connexes
- Démarrage rapide : votre première résolution
- Tests QA du CAPTCHA en environnements autorisés
- Tester l'endpoint de l'API sur vos formulaires
- Intégrer la résolution de CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Passez du premier essai à un workflow reproductible en production. – Créez votre compte CaptchaAI.
