SDK de base

Le moteur de tout l’écosystème. capsolver-core utilise du Python pur pour détecter les CAPTCHA sur une page, lire leurs paramètres, les résoudre via le service CapSolver AI et remplir le jeton. Les packages capsolver-agent et capsolver-mcp de niveau supérieur sont tous deux construits dessus.

Mode jeton uniquement. Ce SDK résout en demandant un jeton à l’API CapSolver (reCAPTCHA v2/v3, Cloudflare Turnstile). Il ne clique pas sur les grilles d’images ni ne fait glisser les curseurs sur la page.

1. Aperçu

capsolver-core divise la « résolution d’un CAPTCHA » en quatre étapes claires, enchaînées dans un seul pipeline:

1. Détecter ( detect ) — identifiez les types CAPTCHA présents sur la page.
2. Lire les paramètres ( get_captcha_info ) — lisez les paramètres structurés de chaque CAPTCHA (type, clé du site, URL, etc.) directement depuis la page en direct.
3. Résoudre ( solve ) — transmettez les paramètres au service AI de CapSolver et récupérez un jeton utilisable.
4. Remplir ( solve_on_page ) — réécrivez le jeton dans la page DOM afin que le site traite la vérification comme réussie.

Autour de ce pipeline, il ajoute plusieurs commodités d’ingénierie:

• ✅ API entièrement asynchrone — construite sur async / await , vous pouvez donc exécuter un grand nombre de résolutions simultanément.
• ✅ Réutilisation et nettoyage des connexions — maintient un pool de connexions HTTP interne et fonctionne comme un gestionnaire de contexte asynchrone.
• ✅ Registre de gestionnaires enfichable — chaque type CAPTCHA est géré par un gestionnaire, que vous pouvez personnaliser ou remplacer.
• ✅ Deux niveaux de granularité — passez à l’API pure lorsque les paramètres sont connus; utilisez le mode Navigateur Playwright lorsque vous n’avez que la page.

Quand devez-vous utiliser core directement? Lorsque vous contrôlez le code vous-même et que vous n’avez pas besoin d’exposer la résolution à un LLM.

2.Installation

capsolver-core est open source sur GitHub et n’est pas encore publié sur PyPI, alors installez-le via git:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# With Playwright support (for detect / solve_on_page)
pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Définissez votre clé:

export CAPSOLVER_API_KEY="your-capsolver-api-key"

Remarque: Le SDK fonctionne sans l’extra [playwright] — dans ce cas, seul le mode Token ( solve ) est disponible et les méthodes dépendantes du navigateur detect / get_captcha_info / solve_on_page ne sont pas disponibles car Playwright est manquant.

3. L’API & les deux modes

3.1 Créer un client

create_capsolver(**options) (ou Capsolver(**options) ) renvoie un client.

Capsolver contient un pool de connexions HTTP interne, il est donc préférable de l’utiliser comme gestionnaire de contexte asynchrone pour garantir la libération des connexions:

async with create_capsolver(api_key="YOUR_API_KEY") as cap:
    solution = await cap.solve(info)
# or call await cap.aclose() explicitly when you're done

3.2 Aperçu des méthodes

3.3 Résoudre l’entrée: CaptchaInfo

L’entrée principale de solve() est un CaptchaInfo . type , website_url , and website_key are required (an empty website_url or website_key raises ValueError ); le reste est facultatif selon le type de CAPTCHA:

Les options pour solve_on_page() sont contrôlées par SolveOnPageOptions:

Le wait_options pour solve() ( WaitOptions ) ne comporte que deux champs facultatifs, timeout et polling_interval , utilisés pour remplacer les valeurs par défaut globales du client pour une seule résolution.

3.4 Types de retour

detect() renvoie list[CaptchaType] et get_captcha_info() renvoie list[CaptchaInfo] .

3.5 Comment chaque mode utilise ces API

La seule différence entre les deux modes réside dans l’origine des paramètres — c’est pourquoi ils appellent des API différentes:

Mode jeton (vous connaissez déjà la clé du site) — utilise uniquement solve() . Vous construisez vous-même le CaptchaInfo et récupérez un jeton:

info = CaptchaInfo(type=CaptchaType.RECAPTCHA_V2, website_url=..., website_key=...)
solution = await cap.solve(info)

Mode navigateur (pilotage de la page avec Playwright) — utilise detect() / get_captcha_info() / solve_on_page() . Le solve_on_page() tout-en-un couvre la détection, la résolution et le remplissage; ou vous pouvez exécuter les étapes séparément pour contrôler chaque étape vous-même:

results = await cap.solve_on_page(page)              # all in one call
# or step by step:
types = await cap.detect(page)
infos = await cap.get_captcha_info(page)
solution = await cap.solve(infos[0])

4. Appel de chaque API: requêtes et réponses

Cette section présente chaque méthode individuellement: l’appel réel, les paramètres à transmettre, un exemple de réponse et une explication des champs de réponse.

4.1 solve — Résoudre (mode Jeton)

Exemple d’appel et de réponse:

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,        # required: CAPTCHA type
        website_url="https://example.com",    # required: page URL
        website_key="6Lc...",                 # required: site public key (data-sitekey)
        # v3 also takes page_action / min_score; Enterprise takes enterprise/s; Cloudflare takes cdata
    )
    solution = await cap.solve(info)
    print(solution.token)
 
asyncio.run(main())

Exemple de réponse ( Solution ):

Solution(
  token="03AFcWeA6f...",                  # the credential to submit to the target site
  captcha_type=CaptchaType.RECAPTCHA_V2,
  expire_time=120,
  user_agent="Mozilla/5.0 ...",
  raw=TokenSolution(...),
)

Champs de réponse:

• token — le jeton résolu; soumettez-le sous le nom g-recaptcha-response pour reCAPTCHA ou cf-turnstile-response pour Turnstile.
• captcha_type — le type CAPTCHA qui a été résolu.
• expire_time — expiration du jeton en secondes; présent uniquement lorsque le service le renvoie, sinon None .
• user_agent — l’UA utilisé pour résoudre; présent uniquement lorsque le service le renvoie, sinon None .
• raw — le TokenSolution brut, contenant g_recaptcha_response / token / user_agent / expire_time .

4.2 solve_on_page — Détection d’une page entière + résolution + remplissage (mode navigateur)

Appel et paramètres: l’entrée est un dramaturge page , avec un SolveOnPageOptions en option.

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)   # or pass options=SolveOnPageOptions(...)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())

Exemple de réponse ( list[SolveOnPageResult] ):

[
  SolveOnPageResult(
      info=CaptchaInfo(type=CaptchaType.RECAPTCHA_V2, website_url=..., website_key=...),
      solution=Solution(token="03AF...", captcha_type=CaptchaType.RECAPTCHA_V2),
      filled=True,
      error=None,
  ),
]

Champs de réponse (par élément):

• info — le CaptchaInfo pour ce CAPTCHA (type et paramètres).
• solution — le Solution ; None en cas d’échec.
• filled — si le jeton a été correctement rempli dans la page.
• error — chaîne de raison de l’échec; None sur le succès.

4.3 detect — Détecter quels CAPTCHA se trouvent sur la page

Appel et paramètres: l’entrée est un dramaturge page .

types = await cap.detect(page)

Exemple de réponse/champs ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

Renvoie une liste des énumérations de type CAPTCHA détectées sur la page; une liste vide signifie qu’aucun n’a été trouvé.

4.4 get_captcha_info — Lire les paramètres structurés

Appel et paramètres: l’entrée est un dramaturge page .

infos = await cap.get_captcha_info(page)
for info in infos:
    print(info.type, info.website_url, info.website_key)
solution = await cap.solve(infos[0])     # once read, can be solved directly

Exemple de réponse/champs ( list[CaptchaInfo] ):

# [CaptchaInfo(type=CaptchaType.RECAPTCHA_V2,
#              website_url="https://example.com",
#              website_key="6Lc...")]

4.5 get_balance — Vérifier le solde

Appel et paramètres: aucune entrée.

balance = await cap.get_balance()
print(balance.balance, balance.packages)

Exemple de réponse/champs ( BalanceResp ):

BalanceResp(balance=12.34, packages=[])

• balance — solde du compte (flotteur).
• packages — liste des forfaits/forfaits d’abonnement; une liste vide s’il n’y en a pas.

4.6 get_supported_captchas / get_handler — Accès au registre

Appel et réponse:

cap.get_supported_captchas()      # → ['reCaptchaV2', 'reCaptchaV3', 'cloudflare']

• get_supported_captchas() — renvoie une liste des chaînes de types actuellement prises en charge.