Une seule API de résolution de captcha
pour tous les défis

Authentification

Envoyez votre clé sous la forme Authorization: Bearer cn-… (ou dans un en-tête X-API-Key). Créez et révoquez vos clés dans le tableau de bord. Les clés ne sont affichées qu'une seule fois et sont stockées sous forme hachée : conservez-en une copie en lieu sûr.

Endpoints

• POST /v1/solve — soumet un défi. Sans wait, la requête renvoie 202 avec un id et status: "solving". Avec ?wait=N (jusqu'à 120 secondes), la requête reste ouverte jusqu'à ce que la résolution soit prête et renvoie 200, ou renvoie 202 si la résolution est toujours en cours à l'expiration du délai.
• GET /v1/task/{id} — interroge une tâche. Interrogez toutes les cinq secondes ; le statut passe de solving à ready ou failed. Une solution payée reste récupérable pendant dix minutes.
• GET /v1/balance — votre crédit restant, en USD.

Types de défis

• recaptcha_v2 — url, sitekey ; invisible en option. $0.00598 par résolution réussie.
• recaptcha_v3 — url, sitekey ; action, minScore en option. $0.00598 par résolution réussie.
• recaptcha_enterprise — url, sitekey ; invisible en option — widgets Enterprise de type case à cocher (les clés Enterprise basées sur un score ne sont pas prises en charge). $0.00598 par résolution réussie.
• turnstile — url, sitekey ; action, cData, pageData en option. $0.00435 par résolution réussie.
• datadome — url, challengeUrl, proxy (obligatoire), userAgent. $0.00435 par résolution réussie.
• image — body (image en base64). $0.003 par résolution réussie.

Les champs qui décident de l'acceptation

proxy accepte une chaîne comme http://user:pass@host:port (http, socks4 et socks5 sont acceptés). Il est facultatif pour les défis à token et obligatoire pour DataDome. Transmettre le proxy qui soumettra le token est le levier le plus important pour l'acceptation : un token obtenu derrière une autre IP est la raison la plus fréquente du rejet d'un token apparemment valide.

action et minScore s'appliquent au reCAPTCHA basé sur un score. Envoyez l'action indiquée par la page elle-même, sinon le score est minoré lors de la vérification. Lorsque la solution contient un userAgent, réutilisez-le à l'identique lors de la soumission.

Erreurs

Les erreurs comportent un code stable lisible par une machine et un message lisible par un humain, soit sous la forme { "error": { "code", "message" } }, soit sur une tâche avec status: "failed". Tout ce qui n'a pas produit de solution utilisable n'est pas facturé.

• invalid_api_key (401) — Clé absente, révoquée ou incorrecte.
• insufficient_balance (402) — Le solde ne couvre pas une résolution. Rechargez votre compte.
• unsupported_type (400 / 422) — Type inconnu, url absente ou champ obligatoire manquant.
• invalid_sitekey (422) — La sitekey a été rejetée pour cette page.
• proxy_required (422) — DataDome a été demandé sans proxy.
• proxy_unreachable (400 / 422) — Chaîne de proxy mal formée, ou le proxy a refusé la connexion.
• unsolvable (422) — Le défi n'a pas pu être résolu. Non facturé.
• capacity_unavailable (503 / 422) — Impossible d'accepter des résolutions pour le moment. Réessayez avec un backoff.
• task_not_found (404) — Aucune tâche avec cet id sur votre compte.
• upstream_error (422) — La résolution n'a pas pu aboutir. Non facturé.

Facturation

Chaque réponse ready indique son cost en USD, déduit de votre solde prépayé. Les résolutions échouées ne coûtent rien. Les prix de chaque type figurent sur la page des tarifs.

SDK

L'API repose simplement sur HTTPS et JSON : aucun paquet n'est nécessaire. Si vous préférez en utiliser un, les SDK officiels open source prennent en charge tous les types, les erreurs typées et l'attente bloquante : Python, Node.js et TypeScript, Go et PHP.

Exemples

Des exemples fonctionnels pour Selenium, Puppeteer, Playwright et Scrapy, ainsi que des wrappers d'outils pour les frameworks d'agents IA, sont disponibles dans la documentation.