El **SDK oficial de Python de CaptchaSonic** convierte cada CAPTCHA compatible en una sola llamada a función. Incluye un cliente síncrono (`CaptchaSonic`) y otro asíncrono (`AsyncCaptchaSonic`), se comunica con nuestra infraestructura por **gRPC de forma predeterminada** (con un transporte HTTP opcional), e incluye anotaciones de tipo completas, reintentos automáticos ante errores transitorios y sondeo integrado para los desafíos de tipo token.

---

## Instalación

```bash
pip install captchasonic
```

El transporte gRPC se instala de forma predeterminada. Para usar también el transporte opcional HTTP/JSON, instala el extra:

```bash
pip install "captchasonic[http]"
```

> [!TIP]
> El SDK es compatible con **Python 3.10, 3.11, 3.12 y 3.13** y se publica bajo la licencia MIT.

---

## Autenticación

Necesitas una clave API de CaptchaSonic. Crea una cuenta y obtén tu clave desde el [panel](/app); después, recarga tu saldo desde [Añadir fondos](/docs/guides/add-funds).

Pasa la clave como primer argumento posicional del cliente:

<Snippet sdk="python" region="authConstruct" />

> [!WARNING]
> Trata tu clave API como una contraseña. Manténla fuera del control de versiones: cárgala desde una variable de entorno o un gestor de secretos en lugar de escribirla en el código.

<Snippet sdk="python" region="authEnvVar" />

---

## Inicio rápido

La mayoría de los CAPTCHAs de tipo token (reCAPTCHA, Turnstile, hCaptcha) se resuelven con una sola llamada. El cliente sondea por ti y devuelve el token cuando la tarea está lista.

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveRecaptchaV2Token_quickstart" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveRecaptchaV2Token" />

  </LangTabs.Tab>
</LangTabs>

> Devuelve el token de reCAPTCHA: envíalo como `g-recaptcha-response` de la página.

Los métodos de tipo token sondean durante hasta 120 segundos por defecto antes de agotar el tiempo (ver [Configuración](#configuration)).

---

## Tipos de CAPTCHA compatibles

El SDK divide los métodos en dos familias:

- **Métodos de token** (`*_token`, `solve_turnstile`, `solve_cloudflare`): tú proporcionas `website_url` / `website_key`, el SDK sondea nuestra infraestructura y devuelve un `result["token"]` listo para enviar.
- **Métodos de imagen / interactivos**: tú proporcionas las imágenes del desafío y el SDK devuelve un `result["typed_solution"]` que describe qué pulsar, arrastrar o escribir.

Todos los argumentos de imagen aceptan el tipo flexible `ImageInput`: una ruta de archivo (`str`), un `pathlib.Path`, `bytes` sin procesar o un objeto de archivo binario abierto.

<Snippet sdk="python" region="imageInputTypes" />

### reCAPTCHA v2 (token)

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<Snippet sdk="python" region="solveRecaptchaV2Token" />

> Devuelve `result["token"]`: envíalo como `g-recaptcha-response` de la página.

### reCAPTCHA v3 (token)

<Snippet sdk="python" region="solveRecaptchaV3Token" />

> Devuelve `result["token"]`: envíalo como `g-recaptcha-response` de la página.

### reCAPTCHA v2 (cuadrícula de imágenes)

Cuando ya tienes las casillas del desafío, resuelve la cuadrícula directamente y recibe los índices en los que hacer clic.

<Snippet sdk="python" region="solveRecaptchaV2" />

> Devuelve `result["typed_solution"]["grid"]["objects"]`: la lista de índices de casillas en las que hacer clic.

### Cloudflare Turnstile

<MethodRef name="solve_turnstile" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveTurnstile" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveTurnstile" />

  </LangTabs.Tab>
</LangTabs>

> Devuelve el token de Turnstile: envíalo como `cf-turnstile-response` del formulario.

<TaskTypeRef captcha="cloudflare-turnstile" />

### Cloudflare Challenge

El desafío completo de Cloudflare **requiere** un proxy.

<Snippet sdk="python" region="solveCloudflare" />

> Devuelve `result["token"]`: el token de autorización para la petición protegida.

### Popular CAPTCHA (desafíos de imagen estilo hCaptcha)

`solve_popular_captcha` gestiona las variantes interactivas con imágenes; `solve_popular_captcha_token` devuelve un token directamente.

<Snippet sdk="python" region="solvePopularCaptcha" />

> La variante de imagen devuelve `result["typed_solution"]["grid"]["objects"]` (índices de casillas en las que hacer clic); la variante de token devuelve `result["token"]`.

### GeeTest

<Snippet sdk="python" region="solveGeetest" />

> Devuelve `result["typed_solution"]`: la acción a realizar, con la forma que determina `geetest_type`.

### AWS WAF

<Snippet sdk="python" region="solveAwsWaf" />

> Devuelve `result["typed_solution"]["grid"]["objects"]`: la lista de índices de casillas en las que hacer clic.

### Imagen a texto (OCR)

<Snippet sdk="python" region="solveOcr" />

> Devuelve `result["typed_solution"]["text"]["texts"][0]`: el texto reconocido que hay que escribir.

### Rompecabezas deslizante

Pasa el fondo y la pieza del rompecabezas; recibirás el desplazamiento horizontal en píxeles.

<Snippet sdk="python" region="solveSlideImage" />

> Devuelve `result["typed_solution"]["slide"]["x"]`: el desplazamiento horizontal en píxeles para arrastrar la pieza.

### TikTok

<Snippet sdk="python" region="solveTikTok" />

> Devuelve `result["typed_solution"]`: la acción a realizar, con la forma que determina `type`.

### Binance

<Snippet sdk="python" region="solveBinance" />

> Devuelve `result["typed_solution"]`: la acción a realizar, con la forma que determina `type`.

---

## Uso asíncrono

Para cargas de trabajo con alta concurrencia (manejadores de FastAPI, spiders de Scrapy, pipelines de asyncio), usa `AsyncCaptchaSonic`. Replica exactamente la API síncrona, pero cada método de resolución se puede esperar (`await`). Úsalo como gestor de contexto asíncrono para que el canal subyacente se limpie automáticamente.

<Snippet sdk="python" region="asyncUsage" />

El cliente síncrono también admite el protocolo de gestor de contexto:

<Snippet sdk="python" region="syncContextManager" />

---

## Compatibilidad con proxy

Los métodos de token aceptan un argumento `proxy` opcional (obligatorio para `solve_cloudflare`). Usa una URL de proxy estándar:

<Snippet sdk="python" region="proxyUsage" />

> [!TIP]
> Proporcionar un proxy permite a nuestro solucionador reflejar la ubicación geográfica y la reputación de IP de tu petición, lo que mejora las tasas de éxito en sitios con reglas antibot estrictas.

---

## Configuración

Todas las opciones se pasan al constructor del cliente y se aplican tanto al cliente síncrono como al asíncrono.

<Snippet sdk="python" region="clientConfiguration" />

| Opción | Predeterminado | Descripción |
| :--- | :--- | :--- |
| `transport` | `"grpc"` | Protocolo de transmisión. `"grpc"` envía las imágenes sin sobrecarga de base64; `"http"` (requiere el extra `[http]`) envía REST/JSON con imágenes codificadas en base64. |
| `url` | `api.captchasonic.com:443` | Sustituye el endpoint de la API (por ejemplo, para instancias propias o de staging). |
| `timeout` | `30.0` | Tiempo límite de red por llamada, en segundos. |
| `polling_interval` | `2.0` | Segundos entre sondeos mientras se espera una tarea de token. |
| `polling_timeout` | `120.0` | Segundos máximos de espera para una tarea de token antes de lanzar una excepción. |
| `secure` | `True` | Usa TLS para el canal gRPC. |

Los errores transitorios de gRPC se reintentan automáticamente (hasta 3 intentos) con retroceso exponencial, así que solo necesitas gestionar los errores de negocio reales.

---

## Manejo de errores

Todos los errores del SDK heredan de `SonicError`, así que puedes capturarlos todos con una sola cláusula `except` o bifurcar según la subclase específica. Cada error también incluye un `error_id` numérico.

<Snippet sdk="python" region="errorHandling" />

<ErrorIdTable />

---

## Ayudantes de cuenta

<Snippet sdk="python" region="accountHelpers" />

Usa `health_check()` como sonda ligera de disponibilidad en los servicios y `get_balance()` para validar los trabajos antes de empezar a gastar créditos.

---

## Solución de problemas

> [!TIP]
> **`ModuleNotFoundError` al usar el transporte HTTP.** El cliente HTTP depende de `httpx`, que es un extra opcional. Instálalo con `pip install "captchasonic[http]"` y define `transport="http"`.

- **Una tarea de token lanza una excepción a los ~120 segundos.** Es el `polling_timeout`. Auméntalo para destinos lentos, por ejemplo `CaptchaSonic(key, polling_timeout=240.0)`.
- **`solve_cloudflare` falla de inmediato.** El argumento `proxy` es obligatorio para el desafío de Cloudflare: proporciona una URL de proxy válida.
- **Errores de conexión gRPC detrás de un proxy o cortafuegos corporativo.** gRPC necesita HTTP/2 por el puerto 443. Si tu red lo bloquea, cambia a `transport="http"`.
- **Los métodos de imagen devuelven índices, no un token.** Los métodos interactivos (`solve_recaptcha_v2`, `solve_popular_captcha`, `solve_aws_waf`, `solve_geetest`, etc.) devuelven `result["typed_solution"]`, que describe la acción a realizar; solo `*_token`, `solve_turnstile` y `solve_cloudflare` devuelven `result["token"]`.

---

## Recursos

- [Paquete en PyPI](https://pypi.org/project/captchasonic/)
- [Referencia de la API REST](/docs/api)
