CaptchaAI JSON API vs Form API: Format Mana yang Digunakan

Tiket support paling umum soal format request CaptchaAI bukan soal mana yang "benar" — tapi kenapa respons yang didapat malah teks polos OK|12345678, padahal kode sudah pakai json={}.

Jawaban singkatnya: CaptchaAI menerima form-encoded dan JSON secara identik — solve time dan hasilnya sama persis. Yang sering bikin bingung adalah parameter json=1, yang mengatur format respons dan terpisah total dari format request itu sendiri.

Panduan ini langsung ke intinya: kapan pakai format yang mana, cara mengirim gambar CAPTCHA dan data biner di keduanya, serta contoh kode Python dan Node.js yang bisa langsung disalin.

Kapan Pakai Form-Encoded, Kapan Pakai JSON

Untuk tim automation dan freelance scraping di Indonesia yang biasanya mengelola beberapa script kecil sekaligus — bukan satu codebase besar — pilihan format lebih soal kecocokan dengan proyek daripada soal performa, karena kecepatan solve-nya identik apa pun formatnya:

1. Script sederhana atau cron job berdiri sendiri — pakai form-encoded. Dependency lebih sedikit, gampang dipelihara sendiri tanpa tim.
2. Integrasi REST API modern atau service Node.js/TypeScript yang sudah pakai axios dan payload JSON di endpoint lain — pakai JSON, ikuti pola yang sudah ada supaya kode konsisten.
3. Upload file CAPTCHA gambar langsung — pakai multipart form. Data biner dikirim langsung tanpa encoding tambahan.
4. Gambar Base64 berukuran besar — form-encoded, penanganan payload besarnya sedikit lebih ringan.
5. Migrasi dari 2Captcha — pertahankan form-encoded dulu. Endpoint dan parameternya kompatibel langsung, migrasi selesai tanpa mengubah struktur request.
6. Integrasi ke sistem lama yang belum tentu punya parser JSON modern — form-encoded, kompatibilitasnya paling luas.

Form-Encoded vs JSON: Request yang Sama, Bentuk Beda

Dua potongan kode di bawah melakukan hal yang identik — submit reCAPTCHA v2 ke in.php — bedanya cuma cara data dibungkus di body request.

Form-Encoded (default requests)

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

Tipe Konten: application/x-www-form-urlencoded

JSON (kwarg 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,
})

Tipe Konten: application/json

Perbedaan Teknis Form-Encoded dan JSON

Untuk CAPTCHA berbasis sitekey seperti reCAPTCHA dan Turnstile, perbedaan ini jarang terasa di hasil akhir. Yang penting diketahui:

Kesalahan yang Sering Terjadi

Lima kesalahan ini yang paling sering muncul di tiket support terkait format request:

• Pakai json={} tapi lupa "json": 1 di data — respons tetap berupa teks polos. Sertakan "json": 1, terlepas dari format body yang dipakai.
• Mencampur data= dan json= dalam request requests yang sama — parameter sering hilang di sisi server. Pakai salah satu saja per request.
• Lupa set Content-Type manual — server gagal parse body. Biarkan library HTTP (requests, axios) yang mengatur otomatis.
• Kirim JSON body ke endpoint polling — /res.php cuma membaca GET query params. Selalu polling pakai GET dengan query params, bukan JSON body.
• Base64 gambar dikirim tanpa .decode() di Python — field body berisi bytes, bukan string, request ditolak. Selalu .decode() hasil base64.b64encode() sebelum dikirim.

Parameter json=1: Bukan Bagian dari Format Request

Ini titik yang paling sering bikin bingung: json=1 bukan soal apakah Anda submit pakai data={} atau json={}. Parameter ini murni mengatur format respons yang dikirim balik oleh CaptchaAI — independen dari bagaimana request-nya sendiri dikirim.

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

Tanpa json=1, kode Anda harus split string manual pakai | — rawan error kalau ada perubahan kecil di format. Sertakan json=1 di setiap request, apa pun format body yang Anda pakai.

Contoh Python Lengkap

Dua pola submit + polling di bawah setara secara fungsi — pilih salah satu, dan jangan campur data= dengan json= dalam request yang sama.

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

Body 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 (sama dengan form-encoded — GET dengan params)
resp = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": "YOUR_API_KEY",
    "action": "get",
    "id": task_id,
    "json": 1,
})

Contoh Node.js Lengkap

Pola submit dan polling yang sama, ditulis pakai axios.

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;

Body 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;

Kirim Gambar CAPTCHA: Multipart vs Base64

Untuk CAPTCHA gambar, pilihan format lebih berpengaruh dibanding CAPTCHA berbasis sitekey karena menyangkut cara data biner dikemas ke dalam request.

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

Base64 di form data (blok terakhir) dan Base64 di body JSON menghasilkan payload yang kurang lebih sama besar — bedanya cuma pembungkusnya. Untuk gambar berukuran besar, multipart upload tetap paling efisien karena file dikirim langsung tanpa overhead encoding Base64 yang menambah ukuran payload sekitar sepertiganya.

Pertanyaan Umum

Apakah pemilihan format memengaruhi kecepatan atau tingkat keberhasilan solve?

Tidak. Form-encoded dan JSON diproses server dengan cara yang sama persis — waktu solve dan hasilnya identik. Perbedaannya murni di cara Anda membungkus request, bukan di cara CaptchaAI menyelesaikan CAPTCHA-nya.

Kenapa respons saya jadi teks polos OK|12345678, padahal saya kira sudah minta JSON?

Karena json=1 belum ada di data atau body request Anda. Format body (data= vs json=) dan parameter json=1 untuk format respons adalah dua pengaturan terpisah — pastikan keduanya ada bersamaan kalau Anda ingin parsing JSON di sisi klien.

Codebase saya sudah pakai json={} di semua service lain — wajib konsisten untuk request ke CaptchaAI juga?

Tidak wajib, tapi disarankan. CaptchaAI menerima keduanya tanpa membedakan hasil, jadi ikuti pola yang sudah dipakai di codebase Anda supaya kode lebih mudah dirawat tim — bukan supaya solve lebih cepat.

Untuk gambar CAPTCHA Base64 yang besar, format mana yang lebih ringan diproses?

Form-encoded sedikit lebih ringan untuk payload Base64 besar karena overhead parsing-nya lebih rendah dibanding body JSON bersarang. Kalau ukuran file jadi masalah nyata, multipart form upload — tanpa Base64 sama sekali — tetap yang paling efisien.

Saya migrasi dari 2Captcha ke CaptchaAI — apakah format request-nya perlu diubah?

Tidak perlu. API 2Captcha asli pakai form-encoding, dan CaptchaAI kompatibel dengan format itu secara langsung. JSON tersedia sebagai opsi tambahan kalau Anda mau, tapi migrasi dari 2Captcha tetap bisa jalan tanpa mengubah struktur request sama sekali.

Panduan Terkait

Sebelum lanjut ke integrasi format tertentu, lihat dulu quickstart CaptchaAI untuk alur dasar kirim task sampai token pertama.

Form-encoded atau JSON, keduanya siap pakai — ambil API key CaptchaAI dan kirim request pertama Anda hari ini.