Méthodes d'authentification proxy pour l'API CaptchaAI

Un token peut être parfaitement valide et se faire refuser quand même : beaucoup de protections comparent l'IP qui a chargé la page et celle qui a résolu le défi CAPTCHA. L'API CaptchaAI répond à ce problème avec deux paramètres, proxy et proxytype, qui déplacent la résolution vers votre propre sortie réseau.

Ce guide couvre le format attendu, les quatre modes d'authentification et la marche à suivre quand le proxy est refusé.

Le format attendu par le paramètre proxy

Tout part de ce tableau : la valeur envoyée est une simple chaîne.

Trois détails décident du succès de l'appel :

• Le séparateur est le deux-points : un mot de passe contenant lui-même un : casse le découpage — demandez-en un autre.
• proxytype doit correspondre au protocole réellement exposé par le proxy. Un proxy SOCKS5 déclaré en HTTP produit une erreur de connexion, pas une erreur d'authentification.
• Le couple proxy / proxytype s'ajoute aux paramètres habituels (key, method, googlekey, pageurl), il ne les remplace pas.

Faut-il vraiment transmettre un proxy ?

Par défaut, non : chaque proxy ajoute une dépendance réseau, de la latence et une cause de panne. Transmettez-en un quand le défi est lié à l'IP.

En cas de doute, testez sans proxy : si la cible accepte le token, gardez le circuit court.

Les quatre méthodes d'authentification

1. Identifiants HTTP (utilisateur et mot de passe)

Le cas le plus courant chez les fournisseurs de proxys résidentiels. Les quatre champs tiennent dans un seul paramètre, et la boucle d'interrogation du résultat ne change pas.

import requests
import time

CAPTCHAAI_KEY = "YOUR_API_KEY"
CAPTCHAAI_URL = "https://ocr.captchaai.com"


def solve_with_http_proxy(site_url, sitekey, proxy_host, proxy_port,
                           proxy_user, proxy_pass):
    """Pass HTTP proxy to CaptchaAI for IP-matched solving."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

    data = resp.json()
    if data["status"] != 1:
        raise Exception(f"Submit: {data['request']}")

    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY,
            "action": "get",
            "id": task_id,
            "json": 1,
        })
        data = resp.json()
        if data["request"] == "CAPCHA_NOT_READY":
            continue
        if data["status"] == 1:
            return data["request"]
        raise Exception(f"Solve: {data['request']}")

    raise TimeoutError("Timeout")


# Usage
token = solve_with_http_proxy(
    site_url="https://example.com/form",
    sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy_host="proxy.example.com",
    proxy_port=8080,
    proxy_user="myuser",
    proxy_pass="mypass",
)

2. Identifiants SOCKS5

Même principe, seul proxytype change : SOCKS5 s'impose quand le fournisseur n'expose que ce protocole.

def solve_with_socks5_proxy(site_url, sitekey, proxy_host, proxy_port,
                             proxy_user, proxy_pass):
    """Pass SOCKS5 proxy to CaptchaAI."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "SOCKS5",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

3. Liste blanche d'IP, sans identifiants

Certains fournisseurs authentifient par liste blanche d'IP. Le paramètre se réduit alors à host:port :

def solve_with_whitelisted_proxy(site_url, sitekey, proxy_host, proxy_port):
    """Proxy with IP whitelist — no username/password."""
    proxy_param = f"{proxy_host}:{proxy_port}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

Important : avec une liste blanche, ce sont les serveurs de CaptchaAI qui ouvrent la connexion, pas les vôtres. Autorisez donc leurs IP côté fournisseur, sinon chaque tâche échoue en ERROR_PROXY_NOT_AUTHORIZED.

4. Proxy HTTPS (tunnel CONNECT)

À utiliser quand la liaison client-proxy est elle-même chiffrée. Le format ne bouge pas, seul proxytype passe à HTTPS.

def solve_with_https_proxy(site_url, sitekey, proxy_host, proxy_port,
                            proxy_user, proxy_pass):
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTPS",
        "json": 1,
    })

    # ... same polling logic ...

Le même appel en Node.js

Côté Node.js, la configuration tient dans un objet — pratique quand vous alternez entre plusieurs pools.

const axios = require("axios");

const CAPTCHAAI_KEY = "YOUR_API_KEY";
const API = "https://ocr.captchaai.com";

async function solveWithProxy(siteUrl, sitekey, proxyConfig) {
  const params = {
    key: CAPTCHAAI_KEY,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: siteUrl,
    proxy: `${proxyConfig.host}:${proxyConfig.port}:${proxyConfig.user}:${proxyConfig.pass}`,
    proxytype: proxyConfig.type || "HTTP",
    json: 1,
  };

  const submit = await axios.post(`${API}/in.php`, null, { params });
  const taskId = submit.data.request;

  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));

    const result = await axios.get(`${API}/res.php`, {
      params: { key: CAPTCHAAI_KEY, action: "get", id: taskId, json: 1 },
    });

    if (result.data.request === "CAPCHA_NOT_READY") continue;
    if (result.data.status === 1) return result.data.request;
  }

  throw new Error("Timeout");
}

// Usage
const token = await solveWithProxy(
  "https://example.com/form",
  "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  {
    host: "proxy.example.com",
    port: 8080,
    user: "myuser",
    pass: "mypass",
    type: "HTTP", // HTTP, HTTPS, SOCKS4, or SOCKS5
  }
);

Formats propres aux principaux fournisseurs

Chaque fournisseur encode ses options (zone, pays, session) dans le nom d'utilisateur. Reprenez la chaîne de votre tableau de bord, puis remettez-la au format host:port:user:pass :

# Bright Data
proxy = "brd.superproxy.io:22225:brd-customer-ID-zone-residential:PASSWORD"
proxytype = "HTTP"

# Smartproxy
proxy = "gate.smartproxy.com:10001:spuser:sppassword"
proxytype = "HTTP"

# Oxylabs
proxy = "pr.oxylabs.io:7777:customer-USERNAME:PASSWORD"
proxytype = "HTTP"

Cas concret : un worker européen face à Cloudflare Turnstile

Une équipe QA lyonnaise surveille les parcours de connexion d'un site e-commerce protégé par Cloudflare Turnstile. Son worker tourne sur une instance parisienne (OVHcloud, Scaleway ou AWS eu-west-3) et sort par un pool de proxys résidentiels français en session sticky. Sans proxy transmis, la résolution partait d'une IP étrangère à celle du navigateur et la cible rejetait le token ; avec proxy et proxytype=HTTP sur la même session, le parcours redevient stable.

Trois points à cadrer avant la mise en production :

• Capacité. Le plan détermine le nombre de résolutions simultanées, pas le nombre de proxys : BASIC ($15/mois, 5 threads) autorise cinq défis en cours à la fois, quel que soit le nombre d'IP de sortie. Passez à STANDARD ($30/mois, 15 threads) quand la file d'attente s'allonge.
• Latence. Comptez 2 à 5 s de plus par résolution : elle transite par votre proxy, dont la qualité pèse directement sur le temps de résolution.
• RGPD. Stockez les identifiants de proxy dans un gestionnaire de secrets plutôt que dans le dépôt, et limitez la journalisation des URL susceptibles de contenir des données personnelles.

Dépannage

Commencez par le code d'erreur : il isole presque toujours la cause.

FAQ

Quelle différence entre proxytype=HTTP et proxytype=HTTPS ?

HTTPS désigne un proxy dont la liaison cliente est chiffrée (tunnel CONNECT), et non le fait de viser une page en https://. Un proxy HTTP classique traite très bien une cible sécurisée : ne passez à HTTPS que si votre fournisseur l'indique.

Dois-je autoriser les IP de CaptchaAI chez mon fournisseur de proxys ?

Oui, dès que l'authentification se fait par liste blanche : ce sont les serveurs de CaptchaAI qui se connectent à votre proxy, pas votre application. Avec des identifiants, aucune autorisation d'IP n'est nécessaire.

Le nombre de threads de mon plan limite-t-il le nombre de proxys ?

Non. Les threads mesurent les résolutions simultanées, pas les adresses IP : avec BASIC ($15/mois, 5 threads), vous alimentez autant de proxys que nécessaire tant que cinq tâches au maximum tournent en parallèle.

Puis-je utiliser un proxy rotatif ?

Uniquement en session sticky. Avec une rotation à chaque requête, la résolution part d'une IP différente de celle qui a chargé la page, et la cible refuse le token.

Le proxy influence-t-il le score reCAPTCHA v3 ?

Il peut. Le score dépend en partie de la réputation de l'IP : un proxy datacenter partagé et très sollicité tire le score vers le bas, là où une IP résidentielle stable donne des résultats plus réguliers.

Guides connexes

• Configurer un proxy SOCKS5 avec CaptchaAI
• Comment la qualité des proxys agit sur le taux de réussite
• Intégrer les proxys datacenter Oxylabs à CaptchaAI

Transmettez votre proxy à l'API pour une résolution alignée sur votre IP de sortie — récupérez votre clé API.