SDK principal

O motor de todo o ecossistema. capsolver-core usa Python puro para detectar CAPTCHAs em uma página, ler seus parâmetros, resolvê-los por meio do serviço CapSolver AI e preencher o token novamente. Os pacotes capsolver-agent e capsolver-mcp de nível superior são construídos sobre ele.

Somente modo token. Este SDK resolve solicitando um token da API CapSolver (reCAPTCHA v2/v3, Cloudflare Turnstile). Ele não clica nas grades de imagem nem arrasta os controles deslizantes na página.

1. Visão geral

capsolver-core divide a “solução de um CAPTCHA” em quatro estágios claros, encadeados em um único pipeline:

1. Detectar ( detect ) — identifique quais tipos de CAPTCHA estão presentes na página.
2. Parâmetros de leitura ( get_captcha_info ) — leia os parâmetros estruturados de cada CAPTCHA (tipo, chave do site, URL e assim por diante) diretamente da página ativa.
3. Solve ( solve ) — entregue os parâmetros ao serviço de IA do CapSolver e receba de volta um token utilizável.
4. Preencher ( solve_on_page ) — escreva o token de volta no DOM da página para que o site trate a verificação como aprovada.

Em torno deste pipeline, ele adiciona diversas conveniências de engenharia:

• ✅ API totalmente assíncrona — construída em async / await , para que você possa executar um grande número de soluções simultaneamente.
• ✅ Reutilização e limpeza de conexões — mantém um pool de conexões HTTP interno e funciona como um gerenciador de contexto assíncrono.
• ✅ Registro de manipulador conectável — cada tipo de CAPTCHA é tratado por um manipulador, que você pode personalizar ou substituir.
• ✅ Dois níveis de granularidade — vá para API pura quando os parâmetros são conhecidos; use o modo Playwright Browser quando tudo o que você tem é a página.

Quando você deve usar core diretamente? Quando você mesmo controla o código e não precisa expor a solução a um LLM.

2. Instalação

capsolver-core é open source no GitHub e ainda não foi publicado no PyPI, então instale-o 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

Defina sua chave:

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

Observação: O SDK funciona sem o extra [playwright] — nesse caso, apenas o modo Token ( solve ) está disponível e os métodos dependentes do navegador detect / get_captcha_info / solve_on_page estão indisponíveis porque o Playwright está ausente.

3. A API e os dois modos

3.1 Criar um cliente

create_capsolver(**options) (ou Capsolver(**options) ) retorna um cliente.

Capsolver contém um pool de conexões HTTP interno, portanto é melhor usado como um gerenciador de contexto assíncrono para garantir que as conexões sejam liberadas:

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 Visão geral dos métodos

3.3 Resolver entrada: CaptchaInfo

A entrada principal para solve() é CaptchaInfo . type , website_url e website_key são obrigatórios (um website_url ou website_key vazio aumenta ValueError ); o restante é opcional dependendo do tipo de CAPTCHA:

As opções para solve_on_page() são controladas por SolveOnPageOptions :

O wait_options para solve() ( WaitOptions ) possui apenas dois campos opcionais, timeout e polling_interval , usados ​​para substituir os padrões globais do cliente para uma única solução.

3.4 Tipos de retorno

detect() retorna list[CaptchaType] e get_captcha_info() retorna list[CaptchaInfo] .

3.5 Como cada modo usa essas APIs

A única diferença entre os dois modos é de onde vêm os parâmetros — e é por isso que eles chamam APIs diferentes:

Modo token (você já conhece a chave do site) — usa apenas solve() . Você mesmo constrói o CaptchaInfo e recebe um token de volta:

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

Modo navegador (dirigindo a página com Playwright) — usa detect() / get_captcha_info() / solve_on_page() . O solve_on_page() multifuncional cobre detecção, resolução e preenchimento; ou você pode executar as etapas separadamente para controlar cada etapa:

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. Chamando cada API: solicitações e respostas

Esta seção percorre cada método individualmente — a chamada real, os parâmetros a serem passados, um exemplo de resposta e uma explicação dos campos de resposta.

4.1 solve — Resolver (modo Token)

Exemplo de chamada e resposta:

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())

Exemplo de resposta ( 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(...),
)

Campos de resposta:

• token — o token resolvido; envie-o como g-recaptcha-response para reCAPTCHA ou cf-turnstile-response para Turnstile.
• captcha_type — o tipo de CAPTCHA que foi resolvido.
• expire_time — expiração do token em segundos; presente apenas quando o serviço o retorna, caso contrário None .
• user_agent — o UA utilizado para resolver; presente apenas quando o serviço o retorna, caso contrário None .
• raw — o TokenSolution bruto, contendo g_recaptcha_response / token / user_agent / expire_time .

4.2 solve_on_page — Detecção de página inteira + resolução + preenchimento (modo navegador)

Chamada e parâmetros: a entrada é um Playwright page , com um opcional SolveOnPageOptions .

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())

Exemplo de resposta ( 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,
  ),
]

Campos de resposta (por item):

• info — o CaptchaInfo para esse CAPTCHA (tipo e parâmetros).
• solution — o Solution; None em caso de falha.
• filled — se o token foi preenchido com sucesso na página.
• error — string do motivo da falha; None em caso de sucesso.

4.3 detect — Detecte quais CAPTCHAs estão na página

Chamada e parâmetros: a entrada é um Playwright page .

types = await cap.detect(page)

Exemplo de resposta/campos ( list[CaptchaType] ):

[<CaptchaType.RECAPTCHA_V2: 'reCaptchaV2'>]

Retorna uma lista de enumerações do tipo CAPTCHA detectadas na página; uma lista vazia significa que nenhum foi encontrado.

4.4 get_captcha_info — Ler parâmetros estruturados

Chamada e parâmetros: a entrada é um Playwright 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

Exemplo de resposta/campos ( list[CaptchaInfo] ):

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

4.5 get_balance — Verificar saldo

Chamada e parâmetros: sem entrada.

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

Exemplo de resposta/campos ( BalanceResp ):

BalanceResp(balance=12.34, packages=[])

• balance — saldo da conta (float).
• packages — lista de planos/pacotes de assinatura; uma lista vazia se não houver nenhuma.

4.6 get_supported_captchas / get_handler — Acesso ao registro

Chamada e resposta:

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

• get_supported_captchas() — retorna uma lista dos tipos de strings atualmente suportados.