Introduction et démarrage rapide

1. Présentation du SDK CapSolver Python

Le SDK est livré sous forme de trois packages indépendants, chacun installable séparément via pip install, ainsi qu’un référentiel d’exemples complémentaire. Ensemble, ils vous permettent de passer de « il y a un CAPTCHA sur la page » à « J’ai un jeton valide » en quelques lignes de Python – que vous écriviez un script unique, que vous pilotiez un vrai navigateur avec Playwright ou que vous connectiez une capacité de résolution à un agent d’IA autonome.

It’s powered by CapSolver’s AI solving service. Le SDK gère tout de votre côté: détection du CAPTCHA, assemblage des paramètres, appel du service et remplissage du résultat, tandis que la reconnaissance et la résolution proprement dites se déroulent dans le cloud. L’idée principale se résume à une seule phrase: votre code (ou votre modèle) décide quoi faire, et CapSolver se charge de le résoudre.

1.1 Fonctionnalités principales

• ✅ Résolution de jetons basée sur l’IA — CapSolver renvoie un jeton que vous soumettez au site cible.
• ✅ Deux modes d’utilisation: API pure (mode Token, pour les clés de site connues, aucun navigateur requis) et mode navigateur basé sur Playwright.
• ✅ Couverture des principaux CAPTCHA — reCAPTCHA v2 / v3 (y compris Enterprise) et Cloudflare Turnstile.
• ✅ API entièrement asynchrone — construite sur async / await, une solution naturelle pour les robots et agents modernes.
• ✅ Trois packages en couches — du moteur de bas niveau aux outils d’agent en passant par un service MCP; choisissez ce dont vous avez besoin (voir 1.2).
• ✅ CLI groupées — capsolver , capsolver-agent et capsolver-mcp vous permettent d’exécuter des diagnostics sans écrire de code.

1.2 CAPTCHA et paramètres pris en charge

Le SDK résout actuellement les types CAPTCHA suivants:

Les paramètres de base requis par chaque type sont website_url + website_key . reCAPTCHA v3 peut en outre prendre page_action , min_score et un indice enterprise, tandis que Cloudflare peut prendre cdata . Vous pouvez inspecter les types pris en charge par votre build actuelle à tout moment:

cap = create_capsolver(api_key="YOUR_API_KEY")
print(cap.get_supported_captchas())

Remarque: En mode Navigateur, vous n’avez pas besoin de fournir ces paramètres manuellement: get_captcha_info(page) lit pour vous le type et la clé du site directement sur la page en direct.

2. Capacités de base (SDK)

2.1 Les trois packages

L’ensemble complet des fonctionnalités plus un référentiel d’exemples. Il ne s’agit pas de trois pairs parmi lesquels choisir: les deux derniers sont tous deux construits sur capsolver-core , offrant simplement la même capacité de résolution via une interface différente. Choisissez celui qui correspond le mieux à votre façon de travailler.

** capsolver-core — Le SDK principal (moteur)**

Le package de niveau le plus bas et le moteur partagé dont dépendent les deux autres. Il divise la résolution d’un CAPTCHA en quatre étapes — détecter → lire les paramètres → résoudre → remplir — et propose deux niveaux de granularité : lorsque la clé du site est connue, passez à l’API pure (mode Token, pas de navigateur) ; lorsque vous n’avez que la page, laissez Playwright détecter automatiquement et remplir le résultat. Entièrement asynchrone, avec un registre de gestionnaires enfichable.

• Idéal pour: les scripts, les robots d’exploration et l’automatisation pour lesquels vous contrôlez le code et n’avez pas besoin d’un LLM.
• Points d’entrée: create_capsolver() → solve() / solve_on_page() .
• Installer: pip install capsolver-core (ajouter [playwright] pour le mode Navigateur).

** capsolver-agent — Outils d’agent**

Enveloppe le noyau sous forme d’outils qu’un LLM peut appeler: il fournit des schémas d’outils indépendants du framework ainsi qu’un exécuteur asynchrone, ainsi que des implémentations LangChain BaseTool prêtes à l’emploi. Dans sa boucle, le modèle appelle «résoudre» de la même manière qu’il appelle «clic» ou «type», et l’exécuteur relaie cet appel aux méthodes du noyau et renvoie un résultat structuré.

• Idéal pour: laisser le modèle décider quand résoudre — Appel de fonction OpenAI, SDK OpenAI Agents, LangChain, utilisation du navigateur ou toute boucle d’agent personnalisée.
• Points d’entrée: get_all_tools() + create_executor() , ou get_langchain_tools() .
• Installer: pip install capsolver-agent (ajouter [langchain] pour LangChain).

** capsolver-mcp — Service MCP**

Expose le même ensemble d’outils qu’un service standard via le Model Context Protocol. Tout client compatible MCP découvre automatiquement ces outils lors de la connexion – aucun code d’adaptateur par client n’est requis. Prend en charge trois transports: stdio, SSE et streamable-http.

• Idéal pour: utilisation plug-and-play dans un client IA — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, et plus encore, avec presque aucun code d’intégration.
• Points d’entrée: la commande capsolver-mcp, ou create_server() .
• Installer: pip install capsolver-mcp (ajouter [browser] pour les outils du navigateur).

2.2 Cas d’utilisation

Chaque fois qu’un CAPTCHA bloque l’étape suivante, ce SDK gagne sa place. Quelques scénarios typiques:

Scraping Web / collecte de données

Un robot d’exploration frappe un reCAPTCHA ou un tourniquet sur une page de liste, une page de recherche ou un mur de connexion, et l’ensemble du pipeline de collecte se bloque. Utilisez le mode Jeton pour obtenir un jeton et soumettez-le avec votre demande, ou utilisez le mode Navigateur pour le remplir directement dans la page – dans tous les cas, le scraping continue. → Recommandé: capsolver-core (Mode Token lorsque la clé du site est connue ; solve_on_page pour les pages dynamiques).

Automatisation des comptes et des flux de travail

Les flux en plusieurs étapes comme l’inscription, la connexion, la réinitialisation du mot de passe et le paiement lancent souvent un CAPTCHA à une étape spécifique, gelant ainsi l’ensemble du script. Déposez la résolution exactement dans cette étape: une fois le jeton rempli, le script continue de soumettre le formulaire, attend la redirection et exécute les étapes restantes jusqu’à la fin. → Recommandé: capsolver-core Mode navigateur; particulièrement fluide lorsque votre script pilote déjà Playwright.

Agents IA (navigation autonome)

Donnez à un agent une tâche telle que «se connecter et extraire les commandes», et il frappera un CAPTCHA quelque part en cours de route sans avertissement. Plutôt que de laisser le modèle cliquer sur lui-même — un ciblage au pixel près et des chemins de curseur semblables à ceux d’un humain sont difficiles à simuler dans les moteurs de risque passés, et les boucles de nouvelle tentative d’image inondent la fenêtre contextuelle — enregistrez une action de « résolution » pour celui-ci : lorsqu’il atteint un CAPTCHA, il appelle l’action, récupère un jeton et continue dans la même session de navigateur sans interrompre le flux. → Recommandé: capsolver-agent (laissez le modèle l’appeler lui-même) ou capsolver-mcp (utilisez-le directement dans un client IA).

Tests automatisés/outils internes

Les tests de bout en bout et les outils d’exploitation internes doivent effacer les étapes CAPTCHA de manière fiable sur vos propres sites ou sur des sites tiers, sans qu’une intervention manuelle ne ralentisse les choses. → Recommandé: choisissez par environnement — capsolver-core (dans le code) ou capsolver-mcp (dans un client).

En bref: partout où vous devez effacer un CAPTCHA par programme en Python, ce SDK est à portée.

3. Installation et configuration de la clé API

Avant de commencer, gardez une chose à l’esprit: la résolution réelle se produit sur le service cloud de CapSolver– le SDK ne l’appelle que de votre côté. La première étape n’est donc pas d’installer un package ; c’est avoir un compte et une clé API. La configuration se déroule en trois étapes, dans l’ordre: s’inscrire et obtenir une clé → installer le SDK → connecter la clé.

3.1 Inscrivez-vous et obtenez votre clé API

1. Créez un compte sur le [site Web CapSolver] ( https://www.capsolver.com ).
2. Ouvrez le tableau de bord et copiez votre clé API.
3. Ajoutez des fonds à votre compte: chaque résolution réussie consomme le solde et la résolution échouera lorsque le solde atteindra zéro.

3.2 Installer le SDK

Les trois packages sont actuellement hébergés en open source sur GitHub et ne sont pas encore publiés sur PyPI, alors installez-les via git. capsolver-core est le moteur, et capsolver-agent et capsolver-mcp en dépendent — donc le noyau est toujours requis. Ajoutez la couche supérieure que vous souhaitez utiliser:

# Engine (required; both other packages depend on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# Optional: MCP service — exposes the tools to MCP clients
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git
 
# Optional: Agent tools — LLM-callable tool definitions + LangChain tools
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

Pour le mode Navigateur (détection des CAPTCHA sur une page réelle et remplissage du jeton), ajoutez le supplément [playwright] et installez Chromium:

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Remarque: detect et solve_on_page nécessitent un navigateur supplémentaire; Le mode jeton ne nécessite aucun navigateur.

Les trois référentiels sont:

Vous pouvez également cloner un dépôt localement avant de l’installer – pratique pour lire les sources ou faire votre propre développement:

git clone https://github.com/capsolver-ai/capsolver-core.git
cd capsolver-core
pip install .            # or: pip install -e .  for an editable install

3.3 Connectez votre clé API

Enfin, remettez la clé de l’étape 3.1 au SDK. Par défaut, tous les packages le lisent à partir de la variable d’environnement CAPSOLVER_API_KEY:

# bash / zsh
export CAPSOLVER_API_KEY="your-capsolver-api-key"
 
# PowerShell
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
 
# cmd
set CAPSOLVER_API_KEY=your-capsolver-api-key

Vous pouvez également ignorer la variable d’environnement et transmettre api_key="..." directement à create_capsolver() .

4. Votre première solution

L’environnement étant prêt, exécutons-le de bout en bout avec le plus petit code possible. Le chemin que vous emprunterez dépend de votre connaissance ou non de la clé du site: si vous la connaissez, utilisez le mode Token; si tout ce que vous avez est une URL de page, utilisez le mode Navigateur.

4.1 Mode Token (vous connaissez déjà la clé du site)

Lorsque vous connaissez le type CAPTCHA, l’URL de la page et la clé du site, aucun navigateur n’est nécessaire: transmettez les paramètres, récupérez un jeton.

import asyncio
from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    info = CaptchaInfo(
        type=CaptchaType.RECAPTCHA_V2,
        website_url="https://example.com",
        website_key="6Lc...",
    )
    solution = await cap.solve(info)
    print(solution.token)  # submit as g-recaptcha-response
 
asyncio.run(main())

4.2 Mode navigateur (un appel, directement sur la page en direct)

Si tout ce que vous avez est une page – et que vous préférez ne pas rechercher la clé du site vous-même – laissez le SDK détecter automatiquement chaque CAPTCHA sur la page, résolvez-les un par un et remplissez les jetons dans le DOM. Un seul appel fait tout.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto("https://example.com/login")
 
        results = await cap.solve_on_page(page)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())