Périmètre sûr : ce guide s'applique exclusivement à 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.
Un pipeline Mage.ai qui s'interrompt parce qu'un CAPTCHA bloque une étape planifiée n'a pas besoin d'une intervention humaine à 3 h du matin : il a besoin d'un appel d'API propre. En insérant CaptchaAI dans un bloc Mage.ai, votre job récupère un token, le réinjecte dans le formulaire ou la route protégée, puis poursuit son exécution sans supervision. L'objectif n'est pas de faire fonctionner le flux une fois dans un notebook, mais de le rendre assez stable pour tourner en production, jour après jour.
Mage.ai orchestre des blocs Python (data loaders, transformers, data exporters) reliés par des déclencheurs planifiés. L'appel à CaptchaAI se loge naturellement dans le bloc qui touche la source protégée — le plus souvent un data loader — sans contaminer le reste du graphe.
Pourquoi intégrer CaptchaAI dans un pipeline Mage.ai
Le problème surgit toujours de la même façon : la collecte fonctionne à la main, puis casse dès qu'elle tourne sans surveillance. Ce qu'il vous faut, ce sont moins d'interventions manuelles, des délais prévisibles et une responsabilité claire quand une étape échoue. CaptchaAI répond à ce besoin avec une API unique pour toutes les familles prises en charge — reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, CAPTCHA image/OCR, grilles d'images et BLS — une latence prévisible et une facturation par thread qui ne vous pénalise pas quand le volume augmente. À l'inverse, hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est annoncé comme « à venir » : concevez votre pipeline autour des types réellement disponibles.
Architecture : où placer l'appel dans vos blocs Mage.ai
Votre bloc interne appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. Isolez cet appel dans un seul bloc, exposez son résultat comme sortie du bloc, et laissez le bloc suivant consommer le token. Tracer chaque étape facilite la détection des régressions lors des montées de version de Mage.ai comme de votre application.
Pour un job planifié qui tourne sur un worker OVHcloud, Scaleway ou une région AWS eu-west-3 (Paris), gardez la logique de résolution idempotente : si le bloc est rejoué après un incident réseau, il doit pouvoir redemander un token sans laisser d'état incohérent.
Gérer la clé API et les secrets
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, jamais dans le code d'un bloc Mage.ai. Le déploiement monte la clé en variable d'environnement au runtime (CAPTCHAAI_KEY), et vos blocs la lisent depuis l'environnement. Si votre pipeline collecte des données personnelles, minimisez ce que vous stockez et vérifiez vos obligations RGPD avant d'élargir le périmètre de la collecte.
Exemple de code
Exemple d'appel HTTP côté serveur, à encapsuler dans le bloc qui touche la source protégée :
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;
}
Observabilité et journalisation
Quel que soit le langage choisi, 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 mesures trop souvent confondues : la réussite de la résolution et la réussite du workflow complet.
Séparez les journaux par environnement (développement, préproduction, production) et conservez les identifiants corrélés à votre traçage distribué, par exemple OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet en partant d'un identifiant unique. En cas d'incident, ces journaux divisent par deux le temps de diagnostic.
Tests et intégration continue
Ajoutez des tests d'intégration sur vos endpoints critiques et publiez des métriques par environnement. Vos tableaux de bord internes doivent montrer la latence, le taux de réussite et la consommation. Une stratégie de retry idempotent — trois tentatives, backoff exponentiel borné, plafond à 30 s — absorbe les erreurs transitoires sans masquer les vrais défauts. Rejouez ces tests depuis votre intégration continue pour éviter qu'une montée de version de Mage.ai ne casse silencieusement l'intégration.
Choisir un plan selon la cadence du pipeline
Un pipeline planifié qui résout quelques CAPTCHA par exécution tient largement dans le plan BASIC ($15/mois, 5 threads). Si plusieurs blocs s'exécutent en parallèle ou si la cadence se resserre, STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads) offrent davantage de threads concurrents. La facturation reste par thread, avec des résolutions illimitées : c'est le parallélisme, pas le nombre de résolutions, qui détermine le palier.
Liste de contrôle avant mise en production
- Le périmètre est strictement 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 d'un bloc.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent est en place pour les erreurs transitoires.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
- Le token est réinjecté dans la même session que celle qui a déclenché le défi.
FAQ
Dans quel bloc Mage.ai faut-il appeler CaptchaAI ?
Dans le bloc qui touche directement la source protégée, généralement un data loader. Isolez l'appel, exposez le token comme sortie du bloc, puis laissez le bloc suivant le consommer. Vous gardez ainsi un graphe lisible et un point unique à surveiller.
Comment stocker la clé API CaptchaAI dans un pipeline Mage.ai ?
Jamais en clair dans un bloc. Placez-la dans un coffre ou un secret d'intégration continue, montez-la en variable d'environnement (CAPTCHAAI_KEY) au déploiement, puis lisez-la depuis l'environnement. Faites tourner la clé régulièrement et ajoutez une alerte de solde sur votre tableau de bord.
Quel plan CaptchaAI choisir pour un pipeline planifié ?
Cela dépend du parallélisme, pas du volume. Un job séquentiel tient dans BASIC ($15/mois, 5 threads) ; plusieurs blocs concurrents justifient STANDARD ($30/mois, 15 threads) ou au-delà. Chaque thread offre des résolutions illimitées sur le mois de facturation.
Comment éviter qu'un CAPTCHA bloque tout le pipeline ?
Bornez chaque résolution par un timeout, entourez l'appel d'un retry idempotent à backoff exponentiel, et traitez tout statut différent de la réussite comme une erreur explicite. Le bloc échoue alors proprement et Mage.ai peut le rejouer sans laisser le pipeline en attente indéfinie.
CaptchaAI prend-il en charge hCaptcha ?
Non — pas encore pris en charge, pas plus que FunCaptcha. CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR, les grilles d'images et BLS. GeeTest v4 est annoncé comme « à venir ».
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
