Explainers

CaptchaAI JSON API vs Form API: Which Format to Use

Automation Python All CAPTCHA Types Migration
By Irina
Published at Feb 20, 2026
CaptchaAI JSON API vs Form API: Which Format to Use
Featured image unavailable

CaptchaAI accepts requests in both form-encoded and JSON formats. Both work identically — choose based on your language and preferences.

Side-by-Side Comparison

Form-Encoded (Default)

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

Key Differences

Factor Form-Encoded JSON
Content-Type application/x-www-form-urlencoded application/json
Data structure Flat key-value pairs Nested objects possible
Binary data Use multipart for file upload Base64 encode in body field
Array support Limited Native
Python keyword data={} json={}
Node.js URLSearchParams JSON.stringify()
Readability Simple for flat params Better for complex data
Compatibility Works everywhere Works everywhere

Response Format

Add json=1 to get JSON responses regardless of request format:

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

Always use json=1 for easier parsing.

Python Examples

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 Examples

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;

Image CAPTCHA: Form vs JSON

For image CAPTCHAs, the format matters more:

Form with File 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 with 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,
})

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

When to Use Which

Scenario Recommended Why
Simple scripts Form-encoded Simpler, fewer dependencies
REST API integration JSON Matches typical API patterns
File uploads Multipart form Direct binary upload
Large base64 images Form-encoded Better handling of large payloads
TypeScript/modern JS JSON Native object support
Legacy system integration Form-encoded Universal compatibility
Migrating from 2Captcha Form-encoded Same format as 2Captcha

Common Mistakes

Mistake Problem Fix
Using json={} but no json: 1 in data Response is plain text Include "json": 1 in the data
Mixing data= and json= in Python requests Request malformed Use one or the other
Forgetting Content-Type header Server can't parse body Let your HTTP library set it automatically
Sending JSON body to poll endpoint Poll uses GET params Always use GET with query params for /res.php

FAQ

Does the format affect solving speed or accuracy?

No. Both formats produce identical results. The server processes them the same way.

Can I mix formats in the same project?

Yes. You can submit with JSON and poll with query params (which is how polling always works). Each request is independent.

Which format is used by the 2Captcha-compatible API?

The original 2Captcha API uses form-encoded. CaptchaAI adds JSON support on top. If you're migrating from 2Captcha, stick with form-encoded.

Choose your preferred format — try CaptchaAI API today.

Discussions (0)

No comments yet.