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 traite ni de l'automatisation de sites tiers, ni du franchissement de protections anti-bot, ni de l'anti-détection.
Le module OCR de l'extension CaptchaAI détermine la façon dont les CAPTCHA image sont lus, puis renvoyés à votre page. Bien le choisir, c'est aligner le module sur la famille réellement affichée, puis traiter l'extension comme un workflow de navigateur reproductible plutôt qu'une case cochée une fois. La stabilité se joue à quatre endroits : l'état du compte, le profil de navigateur, la sélection du gestionnaire et le comportement après résolution. Ce guide en fait une référence qui tient en production, pas seulement sur une démonstration.
Choisir le module selon votre famille de CAPTCHA
Le bon module dépend d'une seule question : que voit l'utilisateur au moment du défi ? CaptchaAI expose ces familles via une seule API, mais un module mal apparié produit des lectures instables et des faux positifs difficiles à diagnostiquer.
- Texte déformé → OCR image normal (méthode
post), qui renvoie une chaîne. - Grille « sélectionnez toutes les vignettes » → module grille d'images, qui renvoie les indices des cases.
Si votre parcours combine plusieurs types, configurez chaque gestionnaire séparément et testez-le isolément.
Le workflow de résolution recommandé
L'ordre des étapes ci-dessous tient en production ; conservez-le tel quel.
- Capturez les entrées attendues. Ne conservez que les paramètres réclamés par la famille de CAPTCHA (sitekey, URL de page, action, proxy éventuel). Stocker davantage crée de fausses pistes de débogage.
- Envoyez la tâche à
https://ocr.captchaai.com/in.phpavecjson=1. Tout statut différent de1est une erreur : journalisez la réponse et remontez-la sur votre supervision. - Interrogez le résultat sur
https://ocr.captchaai.com/res.php. Attendez 15 s, 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 du défi : même contexte de navigateur, même client HTTP, même gestion de cookies. Une session dépareillée est la première cause de rejet.
- Suivez la latence, les retries et l'acceptation en aval. La réussite du solveur et celle du workflow sont deux métriques distinctes.
Côté indicateurs, visez une latence de première résolution inférieure à 8 s pour l'OCR image et un taux de réussite d'au moins 95 % par famille, tout en suivant à part l'acceptation en aval (le statut HTTP après token). Ces chiffres reposent sur des mesures observées ; ils varient selon l'environnement, le volume et le moment de la journée.
Vérifier votre solde avant de lancer un lot
Un lot démarré sans solde suffisant échoue sans raison apparente. Exposez le solde avant chaque exécution :
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))
La facturation est calculée par thread simultané, avec des résolutions illimitées : le plan BASIC ($15/mois, 5 threads) suffit pour valider un flux, et vous montez en threads quand le volume l'exige. Aucun surcoût par type de CAPTCHA.
Dépannage
Ces erreurs couvrent l'essentiel des tickets ; chaque ligne est un correctif.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopier la clé depuis le tableau de bord, la stocker en secret CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Recréditer avant de réessayer, ajouter une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Une entrée requise manque ou est mal formée. | Revalider l'URL, le sitekey et les champs du solveur face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Garder la résolution et l'envoi dans le même contexte de navigateur. |
FAQ
Quel module choisir si ma page affiche une grille d'images ?
Utilisez le module grille d'images, pas l'OCR texte. Un « sélectionnez toutes les vignettes contenant… » n'est pas un texte déformé : le module grille attend les indices des cases, alors que l'OCR normal (méthode post) renvoie une chaîne.
Ce guide concerne-t-il l'automatisation de sites tiers ?
Non. Tous les exemples portent sur vos propres applications ou des environnements de test autorisés par écrit. Pour une source externe, validez d'abord ses conditions d'utilisation et la base juridique.
Que faire en cas d'erreur transitoire de l'API ?
Mettez en place un retry avec backoff exponentiel borné (trois tentatives, doublement du délai, plafond à 30 s). Tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez le réseau (DNS, certificats) et le solde de votre clé.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- L'intégration CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
