Périmètre sûr : ce guide s'applique uniquement à vos propres applications — environnements de développement, de préproduction ou de production — ou à des systèmes pour lesquels vous détenez une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni l'évasion d'anti-bot, ni la neutralisation de protections que vous ne contrôlez pas.
Résoudre un CAPTCHA dans une application FastAPI + HTMX revient à insérer un appel serveur entre le moment où le défi apparaît et celui où votre route valide le formulaire : votre backend demande un token à CaptchaAI, puis l'injecte dans la requête HTMX qui poursuit le flux. Le vrai enjeu n'est pas de faire fonctionner ce flux une fois, mais de le rendre assez stable pour tourner sans surveillance en CI, dans un cron ou derrière une file d'attente. Ce guide couvre l'architecture, les secrets, l'observabilité et les contrôles de production.
Comment le flux s'articule
FastAPI reçoit la soumission partielle envoyée par HTMX, déclenche la résolution côté serveur, puis renvoie le fragment HTML mis à jour. Le token n'est jamais généré côté client : c'est votre service interne qui appelle CaptchaAI, récupère la réponse et la rattache à la session en cours. Trois principes gouvernent cette intégration :
- Un seul point d'appel. Centralisez la logique de résolution dans un module serveur unique, pour tracer et tester chaque appel au même endroit.
- La même session du début à la fin. Le token doit être appliqué dans le contexte HTTP qui a déclenché le défi — mêmes cookies, même client. Une session dépareillée est la première cause de rejet après résolution.
- Des étapes traçables. Journalisez chaque appel pour repérer les régressions lors des montées de version.
Stocker la clé API sans l'exposer
La clé CaptchaAI ne vit jamais dans le code source ni dans un dépôt Git. Placez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de votre pipeline CI, puis montez-la en variable d'environnement au démarrage du conteneur. FastAPI la lit alors via os.environ, sans jamais l'imprimer dans les logs. Cette discipline vaut aussi pour la conformité : côté RGPD, minimisez les données personnelles qui transitent par vos journaux et vérifiez vos obligations avant de tracer des payloads complets.
Exemple : créer une tâche Turnstile côté serveur
L'appel ci-dessous, extrait d'un service Node.js interne, soumet une tâche Cloudflare Turnstile et renvoie l'identifiant à interroger. La logique est identique en Python : vous pouvez la transposer dans votre module FastAPI sans changer le contrat d'appel.
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Une fois l'identifiant obtenu, interrogez le résultat à intervalle régulier — par exemple toutes les 5 secondes, après une première attente de 15 secondes — avec un plafond strict par tâche pour éviter les boucles infinies.
Observabilité et journalisation
Quel que soit le langage, instrumentez les appels 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 interne. Ces signaux alimentent vos tableaux de bord de QA et vos alertes, et distinguent deux réussites souvent confondues : le taux de réussite du solveur et le taux d'acceptation en aval.
Séparez les journaux par environnement (développement, préproduction, production) et conservez les identifiants corrélés à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet à partir d'un identifiant unique et réduire le temps de diagnostic en cas d'incident.
Déployer les workers près de vos utilisateurs
Si votre application sert un public francophone, hébergez les workers qui appellent CaptchaAI au plus près de vos utilisateurs pour maîtriser la latence. Une région comme eu-west-3 (Paris) chez AWS, ou une instance OVHcloud ou Scaleway, constitue un point de départ naturel. La facturation CaptchaAI reste en dollars US quel que soit l'hébergeur : le plan BASIC ($15/mois, 5 threads) suffit pour valider une intégration, puis vous montez en capacité — STANDARD ($30/mois, 15 threads), ADVANCE ($90/mois, 50 threads) — quand le volume concurrent augmente. La tarification étant au thread avec résolutions illimitées, le coût reste prévisible à l'échelle.
Liste de contrôle avant la mise en production
- Le périmètre reste strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais en clair dans le code.
- Chaque appel trace sa durée, son code retour et son identifiant de tâche.
- Le token est appliqué dans la session qui a déclenché le défi.
- Une stratégie de retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
- Les tests d'intégration sont rejouables depuis votre intégration continue.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou depuis le mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum requis par tâche. | Rechargez le solde et ajoutez une alerte de seuil dans le tableau de bord. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Un paramètre requis est absent ou mal formé. | Revalidez l'URL de page et le sitekey face au HTML en direct. |
CAPCHA_NOT_READY en boucle |
Le résultat n'est pas encore prêt côté solveur. | Continuez d'interroger toutes les 5 secondes, avec un plafond strict par tâche. |
| Token rejeté après résolution | Token appliqué dans une session différente de celle qui a déclenché le défi. | Gardez la résolution et la soumission du formulaire dans la même session HTTP. |
FAQ
Où placer la clé API CaptchaAI dans un projet FastAPI ?
Dans un coffre ou un secret CI, jamais dans le code. Montez-la en variable d'environnement et lisez-la via os.environ au démarrage. La clé ne transite alors ni par Git ni par vos journaux, et se fait tourner sans redéploiement.
Comment tester cette intégration en CI sans dépendre d'un vrai défi ?
Isolez le module de résolution derrière une interface et injectez un double (mock) qui renvoie un token factice pour la majorité de vos tests. Réservez un test de bout en bout, exécuté moins souvent, pour vérifier l'appel réel à l'API. Vos exécutions restent ainsi rapides et déterministes.
CaptchaAI prend-il en charge hCaptcha pour ce type d'application ?
Non — hCaptcha n'est pas encore pris en charge, pas plus que FunCaptcha (Arkose Labs). CaptchaAI résout notamment reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image (OCR) et en grille.
Le token est refusé après résolution : que vérifier en premier ?
La cohérence de session. Le token doit être appliqué dans le même contexte HTTP — mêmes cookies, même client — que celui qui a affiché le défi. Vérifiez ensuite que le sitekey et l'URL envoyés correspondent à la page en direct.
Guides connexes
- le démarrage rapide CaptchaAI
- la résolution CAPTCHA en environnements de QA autorisés
- tester l'endpoint API sur vos formulaires web
- l'intégration CAPTCHA en intégration continue
- résoudre reCAPTCHA v2 via l'API
Passez d'un prototype fragile à une intégration reproductible et mesurable. – Créez votre compte CaptchaAI.
