API JSON CaptchaAI vs API Form : quel format utiliser

Réponse courte : peu importe. L'API CaptchaAI accepte aussi bien les requêtes codées par formulaire que les requêtes JSON, et les deux renvoient un résultat strictement identique. Le format n'a aucun effet sur la vitesse de résolution ni sur le taux de réussite — le serveur traite les deux corps de la même manière.

Ce qui vous fait pencher d'un côté ou de l'autre, c'est votre pile technique : le langage, la bibliothèque HTTP et les conventions de votre code d'intégration.

Ce guide pose d'abord les différences concrètes, une grille de décision et les pièges à éviter, puis donne le code Python et Node.js pour chaque format.

Différences clés entre JSON et formulaire

Pour les paramètres de résolution habituels — clé, méthode, sitekey, URL de la page — la structure reste plate des deux côtés, et l'écart pratique est mince.

Il ne se creuse vraiment que sur les charges imbriquées ou binaires, traitées plus bas.

Quel format choisir selon votre cas

Un exemple concret

Prenons une équipe qui exploite un service de scraping en Node.js déployé sur Scaleway ou OVHcloud, avec une API REST déjà en JSON de bout en bout. Rester en JSON évite une conversion inutile et garde le code homogène : les corps de requête ressemblent au reste de la couche HTTP. À l'inverse, une équipe qui migre un ancien pipeline depuis 2Captcha a tout intérêt à conserver le codage par formulaire — l'API compatible 2Captcha attend ce format, et vous ne touchez pas au code d'envoi existant. Dans les deux cas, la seule vraie contrainte reste RGPD côté données collectées, pas côté format de requête.

Erreurs fréquentes à éviter

Les deux formats en un coup d'œil

Requête codée par formulaire (par défaut)

import requests

resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})

Content-Type : application/x-www-form-urlencoded

Requête JSON

import requests

resp = requests.post("https://ocr.captchaai.com/in.php", json={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})

Content-Type : application/json

En Python, tout tient dans un seul mot-clé : data= envoie un corps codé par formulaire, json= envoie un corps JSON et pose l'en-tête Content-Type à votre place. Le reste des paramètres ne bouge pas.

Format de réponse : forcer du JSON avec json=1

Ajoutez json=1 pour recevoir une réponse JSON, quel que soit le format de la requête. Sans ce paramètre, l'API répond en texte brut au format historique OK|ID, qu'il faut découper à la main :

# Without json=1 — plain text response
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
})
# Response: "OK|12345678"

# With json=1 — JSON response
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})
# Response: {"status": 1, "request": "12345678"}

Gardez toujours json=1 : une réponse structurée s'analyse sans découpage de chaîne et se prête mieux à la gestion d'erreurs. Le format de la requête et celui de la réponse sont deux réglages distincts — vous pouvez envoyer un corps codé par formulaire et recevoir du JSON.

Exemples Python

Codage par formulaire

import requests

# Submit
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})
task_id = resp.json()["request"]

# Poll (always GET with query params)
resp = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": "YOUR_API_KEY",
    "action": "get",
    "id": task_id,
    "json": 1,
})

Corps JSON

import requests

# Submit with JSON
resp = requests.post("https://ocr.captchaai.com/in.php", json={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})
task_id = resp.json()["request"]

# Poll (same as form-encoded — GET with params)
resp = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": "YOUR_API_KEY",
    "action": "get",
    "id": task_id,
    "json": 1,
})

Un point à retenir : seule l'étape d'envoi change de format. L'interrogation du résultat sur /res.php reste un GET avec paramètres de requête dans les deux cas — c'est la seule façon d'interroger le résultat, quel que soit le format d'envoi choisi.

Exemples Node.js

Codage par formulaire

const axios = require('axios');
const qs = require('querystring');

// Submit
const resp = await axios.post(
  'https://ocr.captchaai.com/in.php',
  qs.stringify({
    key: 'YOUR_API_KEY',
    method: 'userrecaptcha',
    googlekey: 'SITE_KEY',
    pageurl: 'https://example.com',
    json: 1,
  })
);
const taskId = resp.data.request;

Corps JSON

const axios = require('axios');

// Submit with JSON
const resp = await axios.post(
  'https://ocr.captchaai.com/in.php',
  {
    key: 'YOUR_API_KEY',
    method: 'userrecaptcha',
    googlekey: 'SITE_KEY',
    pageurl: 'https://example.com',
    json: 1,
  }
);
const taskId = resp.data.request;

Avec Axios, un objet passé tel quel est sérialisé en JSON et l'en-tête est posé automatiquement. Pour le codage par formulaire, il faut passer par querystring (ou URLSearchParams) afin d'aplatir l'objet — d'où la dépendance supplémentaire.

CAPTCHA image : formulaire ou JSON

Pour les CAPTCHA image, le format pèse davantage, car il faut transporter des octets. Trois approches sont possibles.

Formulaire avec envoi de fichier (multipart)

# File upload — form-encoded with multipart
resp = requests.post("https://ocr.captchaai.com/in.php",
    data={
        "key": "YOUR_API_KEY",
        "method": "post",
        "json": 1,
    },
    files={
        "file": open("captcha.png", "rb"),
    },
)

JSON avec Base64

import base64

# Base64 in JSON body
with open("captcha.png", "rb") as f:
    body = base64.b64encode(f.read()).decode()

resp = requests.post("https://ocr.captchaai.com/in.php", json={
    "key": "YOUR_API_KEY",
    "method": "base64",
    "body": body,
    "json": 1,
})

Formulaire avec Base64

# Base64 in form data
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "base64",
    "body": body,
    "json": 1,
})

Le multipart évite de gonfler la charge : il envoie le fichier tel quel.

Le Base64 alourdit le payload d'environ un tiers, mais reste pratique quand l'image est déjà en mémoire ou vient d'une autre étape du pipeline. Sur de grandes images, le codage par formulaire encaisse mieux ces payloads volumineux.

FAQ

Le format change-t-il la vitesse ou la précision de la résolution ?

Non. Les deux formats produisent des résultats identiques et le serveur les traite de la même façon. Choisissez selon votre langage et vos bibliothèques, pas selon la performance attendue.

Faut-il quand même envoyer json=1 quand j'utilise un corps JSON ?

Oui. Le format d'envoi et le format de réponse sont indépendants : json={} code la requête en JSON, mais c'est json: 1 dans le corps qui demande une réponse JSON. Sans ce paramètre, vous recevez le texte brut OK|ID.

Comment envoyer une image CAPTCHA en JSON ?

Encodez le fichier en Base64 et passez-le dans le champ body avec "method": "base64". Pour de très grandes images, le codage par formulaire ou l'envoi multipart reste plus économe en bande passante.

Puis-je interroger le résultat en JSON aussi ?

L'interrogation sur /res.php est toujours un GET avec paramètres de requête, quel que soit le format d'envoi. Ajoutez json=1 à ces paramètres pour recevoir la réponse au format JSON.

Quel format utiliser si je migre depuis 2Captcha ?

Restez sur le codage par formulaire. L'API 2Captcha d'origine l'utilise, et CaptchaAI ajoute le JSON par-dessus : conserver le formulaire vous évite de retoucher votre code d'envoi existant.

Guides connexes

• L'arbre de décision pour gérer les erreurs de l'API
• La carte de référence rapide de l'API

Prêt à envoyer votre première requête ? Créez votre compte CaptchaAI et testez les deux formats en quelques minutes.