Périmètre sûr : ce guide s'applique exclusivement à vos propres applications et environnements (QA, préproduction, production), ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le franchissement de protections anti-bot.
La règle courte : l'extension de navigateur CaptchaAI l'emporte quand un opérateur pilote une session dans Chrome, tandis que l'approche CLI — vos scripts appelant l'API — l'emporte dès que le travail doit tourner seul, en CI ou dans un worker planifié. Les deux surfaces partagent le même compte et la même clé ; elles ne diffèrent que par l'endroit où le code s'exécute. La vraie question : un humain regarde-t-il l'écran pendant la résolution, oui ou non ?
Extension ou CLI : le tableau de décision
Cinq facteurs suffisent à trancher, résumés ci-dessous.
| Critère | Extension de navigateur | Approche CLI |
|---|---|---|
| Contexte | session pilotée par un humain | exécution autonome (CI, cron, worker) |
| Interface | fenêtre Chrome visible | terminal, conteneur ou serverless |
| Types couverts | reCAPTCHA, Turnstile, GeeTest v3, image/OCR | mêmes types, en headless |
| État de session | profil Chrome persistant | même session HTTP dans le script |
| Journalisation | limitée au navigateur | complète, corrélée au traçage |
Quand l'extension de navigateur gagne
Sessions interactives et débogage : vous voyez le défi se résoudre puis se valider en direct, le volume reste modeste, et un profil Chrome persistant conserve l'état d'une exécution à l'autre. C'est la voie la plus rapide pour mettre au point un parcours avant de l'automatiser.
Quand l'approche CLI gagne
Exécution sans surveillance : un job planifié, une étape de pipeline chez OVHcloud ou Scaleway, une fonction dans une région AWS eu-west-3 (Paris). Aucun écran, donc vos scripts envoient la tâche, appliquent le token dans la même session, puis journalisent tout — versionné et rejouable en CI. Côté budget, la facturation reste basée sur les threads : BASIC ($15/mois, 5 threads) inclut des résolutions illimitées.
Mesurez avant de trancher
Mesurez les deux options à conditions égales — même charge, même environnement — puis comparez la médiane, le P90, le P99 et le taux de réussite.
Les chiffres obtenus reposent sur des mesures observées dans votre environnement et varient selon le poste, le volume et le moment de la journée.
Exemple : vérifier le solde avant un lot
Avant de lancer un lot depuis votre suite de tests, contrôlez le solde : un compte à zéro est la cause la plus banale d'un lot qui échoue en silence :
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))
Ce garde-fou ne s'automatise que côté CLI. Instrumentez aussi chaque appel — durée d'obtention du token, code retour HTTP, identifiant de tâche — et corrélez-les à votre traçage distribué (OpenTelemetry).
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_ZERO_BALANCE |
solde du compte épuisé | rechargez, puis ajoutez une alerte de solde |
| Token refusé après résolution | token appliqué dans une autre session | gardez la résolution et l'envoi dans la même session |
| Tâches qui se marchent dessus | profil de navigateur partagé | isolez profil et cookie jar par exécution |
Liste de contrôle avant la bascule
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Un retry idempotent, avec backoff exponentiel borné, gère les erreurs transitoires.
- Le token est appliqué dans la même session que celle qui a déclenché le défi.
FAQ
L'extension convient-elle à une exécution non surveillée en CI ?
Pas idéalement : elle suppose une fenêtre Chrome vivante et, souvent, un opérateur devant l'écran. Pour un job planifié ou un runner sans interface graphique, la CLI reste plus stable.
Puis-je partager la même clé API entre l'extension et mes scripts ?
Oui. Les deux surfaces s'authentifient sur le même compte avec la même clé. Stockez-la dans un secret ou un coffre, jamais en dur : la facturation par threads est commune aux deux.
Comment éviter que deux tâches se marchent dessus dans le même profil ?
Isolez les profils : un répertoire de profil et un cookie jar par exécution, et le token appliqué dans la session exacte qui a déclenché le défi. C'est la première cause de rejet après résolution.
Guides connexes
- le guide de démarrage rapide CaptchaAI
- la QA des CAPTCHA en environnements autorisés
- tester l'endpoint API sur vos formulaires
- intégrer la résolution de CAPTCHA en CI
- résoudre reCAPTCHA v2 via l'API
Choisissez la surface qui colle à votre contexte d'exécution, puis validez-la sur un premier lot réel. – Créez votre compte CaptchaAI.
