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 disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Que l'interface l'appelle « Account Key » ou « clé API », il s'agit du même identifiant : le secret qui authentifie votre compte auprès de CaptchaAI et rattache chaque résolution de CAPTCHA à votre solde. La vraie question n'est pas laquelle choisir, mais comment la configurer, où la stocker et comment la tracer pour garder l'extension stable sans surveillance.
Account Key ou clé API : quelle différence en pratique ?
Les deux étiquettes désignent un secret à traiter de la même façon : jamais codé en dur, jamais commité, jamais exposé dans un journal. Le piège classique n'est pas le choix de l'étiquette, mais la clé copiée avec un espace parasite ou issue d'un mauvais compte, qui déclenche un ERROR_WRONG_USER_KEY difficile à diagnostiquer sans traçage.
Extension ou appel API : quel contexte ?
L'extension et l'API s'authentifient avec la clé de votre compte ; le choix dépend du contexte d'exécution, pas d'un identifiant différent.
| Contexte | Extension de navigateur | Appel API direct |
|---|---|---|
| Usage typique | Tests manuels et interactifs | Jobs planifiés, workers |
| Configuration | Clé collée dans l'extension | Clé en variable d'environnement |
Où stocker la clé, côté RGPD
La clé CaptchaAI vit dans un coffre — HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault — ou dans un secret de CI, jamais dans le dépôt. Côté RGPD, consignez qui accède à la clé et minimisez les données personnelles qui transitent par vos formulaires de test ; un hébergeur européen comme OVHcloud ou Scaleway garde ces journaux dans la juridiction attendue.
Instrumenter et observer chaque résolution
Votre composant appelle CaptchaAI via HTTPS et injecte le token dans la même session de navigateur que celle qui a déclenché le défi. Quatre points de mesure gardent l'intégration observable :
- Durée d'obtention du token et code retour HTTP.
- Identifiant de tâche corrélé à votre traçage distribué, par exemple OpenTelemetry.
- Taille de la file d'attente interne, pour repérer les saturations.
- Journaux séparés par environnement, pour rejouer un scénario complet depuis un identifiant unique.
Exemple : lire le solde depuis vos tests
Extrait côté client, tiré de vos tests, pour vérifier le solde avant de lancer un lot :
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))
Liste de contrôle avant la mise en production
- Le périmètre reste limité à vos applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret de CI ou un coffre, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés.
- Une stratégie de retry idempotent couvre les erreurs transitoires.
Dépannage
La plupart des tickets sur cette intégration se ramènent à quatre causes.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace ou issue d'un mauvais compte. | Recopiez la clé depuis le tableau de bord, en secret de CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez avant de réessayer et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL de la page et le sitekey face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente du défi. | Résolvez et soumettez dans le même contexte de navigateur. |
FAQ
« Account Key » et « clé API » désignent-ils le même identifiant ?
En pratique, oui : quelle que soit l'étiquette, il s'agit du secret qui authentifie votre compte. Configurez-le une fois dans l'extension et lisez la même valeur depuis une variable d'environnement dans vos scripts, pour éviter deux sources de vérité qui divergent.
La clé a-t-elle un coût par résolution ?
Non. CaptchaAI facture par thread simultané, avec un nombre illimité de résolutions par thread sur le mois. La plus petite offre, BASIC ($15/mois, 5 threads), traite déjà plusieurs défis en parallèle : le coût dépend du nombre de threads, pas du volume de tokens.
Puis-je réutiliser la même clé sur plusieurs environnements ?
Oui : la clé authentifie le compte, pas un environnement. Séparez toutefois les secrets par environnement — un secret de CI distinct pour la préproduction et la production — pour tracer les accès et révoquer sans tout interrompre.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Configurez votre clé API et mesurez vos temps de résolution avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
