CaptchaAI JSON API vs. Formular-API: Welches Format verwendet werden soll

Wer die CaptchaAI-API anbindet, steht früher oder später vor derselben Frage: form-encoded oder JSON? Technisch macht es keinen Unterschied. Der Endpunkt in.php verarbeitet beide Formate identisch – Lösungszeit, Erfolgsquote und Abrechnung bleiben gleich. Die Wahl ist keine Performance-, sondern eine Stilfrage: entscheidend ist, welche Sprache und welchen HTTP-Stack Sie ohnehin verwenden.

Wer von 2Captcha migriert, bleibt meist bei form-encoded; wer einen neuen Node.js- oder TypeScript-Service aufsetzt, greift eher zu JSON. Die folgenden Beispiele in Python und Node.js zeigen beide Wege und fassen am Ende zusammen, welches Format zu welchem Szenario passt.

Die Entscheidung in Kürze:

• Form-encoded für einfache Skripte, Altsysteme und die Migration bestehender 2Captcha-Integrationen.
• JSON für moderne REST-Services, TypeScript-Stacks und verschachtelte Datenstrukturen.
• Multipart nur für den direkten Datei-Upload von Bild-CAPTCHAs.

Form-encoded und JSON im direkten Vergleich

Beide Anfragen senden dieselben Parameter an denselben Endpunkt – nur die Verpackung unterscheidet sich:

Form-encoded (Standard)

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

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

Antwortformat: immer json=1 setzen

Unabhängig vom Anfrageformat entscheidet der Parameter json=1 über die Antwort. Ohne ihn liefert der Server eine Klartextzeile, mit ihm ein sauber verarbeitbares JSON-Objekt:

# 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"}

Setzen Sie json=1 grundsätzlich – das erspart Ihnen das Parsen von OK|...-Strings und macht die Fehlerbehandlung robuster. Schlägt die Übermittlung fehl, zeigt das status-Feld dies sofort an, während der Grund im request-Feld steht. Im Klartextformat müssten Sie dieselbe Unterscheidung umständlich über String-Vergleiche treffen.

Python: Anfrage übermitteln und Ergebnis abfragen

In Python steuert ein einziges Schlüsselwort das Format: data={} sendet form-encoded, json={} sendet JSON. Der Abruf über /res.php bleibt in beiden Fällen gleich – immer GET mit Query-Parametern.

Form-encoded

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,
})

JSON-Body

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,
})

Node.js: Anfrage senden mit axios

In Node.js serialisiert axios ein übergebenes Objekt automatisch als JSON. Für form-encoded serialisieren Sie die Daten vorab mit querystring.

Form-encoded

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;

JSON-Body

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;

Bild-CAPTCHAs: Datei-Upload oder Base64

Bei Bild-CAPTCHAs wird die Formatwahl greifbarer, weil Binärdaten übertragen werden. Drei Wege führen zum Ziel:

• Multipart-Upload – die Datei direkt an die Anfrage anhängen.
• Base64 in JSON – das Bild als String im JSON-Body.
• Base64 form-encoded – derselbe String, klassisch als Formularfeld verpackt.

Formular mit Datei-Upload (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 mit 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,
})

Formular mit 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,
})

Für sehr große Base64-Bilder ist form-encoded oft die pragmatischere Wahl, weil manche HTTP-Bibliotheken große JSON-Payloads schlechter verarbeiten.

Die wichtigsten Unterschiede auf einen Blick

In der Praxis fällt keiner dieser Punkte bei einfachen reCAPTCHA- oder Turnstile-Aufgaben ins Gewicht, denn sie senden ohnehin nur flache Parameter. Spürbar wird die Wahl erst bei Bild-CAPTCHAs mit Base64-Daten oder wenn Ihr Framework ein bestimmtes Format vorgibt – etwa ein REST-Client, der jede ausgehende Anfrage als JSON serialisiert.

Welches Format für welches Szenario?

Ein Beispiel aus der Praxis: Ein Preis-Monitoring-Dienst mit bestehendem 2Captcha-Skript bleibt bei form-encoded und ändert nur die Endpunkt-URL. Ein neuer Node.js-Microservice – etwa hinter einer GitLab-CI-Pipeline – startet dagegen direkt mit JSON.

Typische Fehler und wie Sie sie vermeiden

Häufige Fragen

Welches Format sollte ich bei der Migration von 2Captcha wählen?

Form-encoded. Die 2Captcha-API arbeitet form-encoded, CaptchaAI ergänzt JSON nur zusätzlich. Übernehmen Sie ein bestehendes Skript, ändern Sie idealerweise nur die Endpunkt-URL.

Muss ich den /res.php-Abruf ebenfalls als JSON senden?

Nein. Der Ergebnisabruf läuft immer als GET mit Query-Parametern – gleich, ob Sie die Aufgabe form-encoded oder als JSON übermittelt haben. Nur in.php kennt beide Formate.

Wie übergebe ich ein Bild-CAPTCHA im JSON-Format?

Als Base64-String im Feld body: Bilddatei einlesen, mit Base64 kodieren und mit method: "base64" senden. Bei sehr großen Bildern ist form-encoded häufig die stabilere Wahl.

Beeinflusst das Anfrageformat meine Kosten oder meinen Thread-Verbrauch?

Nein. CaptchaAI rechnet pro gleichzeitigem Thread ab – nicht pro Anfrage und nicht pro Format. Preis und Durchsatz hängen allein von Ihrem Tarif und der Zahl paralleler Threads ab.

Muss ich den Content-Type-Header selbst setzen?

Nein. Überlassen Sie das Ihrer HTTP-Bibliothek: requests und axios setzen den passenden Header automatisch, sobald Sie data= bzw. json= oder ein Objekt übergeben. Ein manuell gesetzter, falscher Content-Type gehört zu den häufigsten Fehlerquellen.

Fazit

• Server-seitig sind beide Formate gleichwertig – Lösungszeit, Erfolgsquote und Abrechnung ändern sich nicht.
• json=1 sollten Sie unabhängig vom Anfrageformat immer setzen, um saubere JSON-Antworten und eine robuste Fehlerbehandlung zu erhalten.
• Bei bestehenden 2Captcha-Skripten ist form-encoded der reibungsloseste Weg; für neue Services ist JSON meist die natürlichere Wahl.

Verwandte Leitfäden

• API-Antwortformate und Fehlercodes verstehen
• API-Kurzreferenz für alle Endpunkte

Wählen Sie Ihr bevorzugtes Format und testen Sie die CaptchaAI-API noch heute.