API JSON CaptchaAI so với API biểu mẫu: nên dùng định dạng nào

CaptchaAI nhận request ở cả hai định dạng — form-encoded và JSON — và trả về kết quả giải giống hệt nhau. Chọn định dạng nào không liên quan đến tốc độ hay độ chính xác, mà phụ thuộc vào ngôn ngữ và cách bạn tổ chức code.

Trả lời nhanh: 3 dấu hiệu nên chọn JSON

1. Bạn tích hợp REST API hiện đại (TypeScript, Node.js, service dùng JSON toàn hệ thống).
2. Request cần mảng hoặc object lồng nhau — nhiều site-key, proxy, batch CAPTCHA.
3. Codebase không ràng buộc với 2Captcha hay hệ thống legacy dùng form-encoded.

Ví dụ thực tế: nhiều team outsourcing tại TP.HCM và Hà Nội chạy song song service Python xử lý dữ liệu và service Node.js làm API gateway. Chọn JSON cho gateway giúp code hai bên dùng chung một kiểu dữ liệu.

Khi nào nên giữ form-encoded

• Script đơn giản, một file, không muốn thêm dependency.
• Đang porting code cũ từ 2Captcha — API gốc dùng form-encoded.
• Gửi ảnh Base64 kích thước lớn — form-encoded xử lý payload lớn ổn định hơn.
• Tích hợp vào hệ thống legacy chỉ hỗ trợ application/x-www-form-urlencoded.

Khác biệt kỹ thuật giữa hai định dạng

Cách gửi request cơ bản

Về cú pháp, khác biệt chỉ nằm ở keyword bạn truyền cho thư viện HTTP:

Form-encoded (mặc định)

Gửi tham số phẳng qua data=:

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

Cùng request, chỉ đổi data= thành 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

requests tự set header tương ứng — bạn không cần khai báo tay.

Bật json=1 để nhận JSON response

Bất kể gửi request ở định dạng nào, thêm json=1 vào payload để CaptchaAI trả về response dạng JSON thay vì text thuần:

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

Bật json=1 cho mọi service mới để khỏi phải parse text thủ công.

Lỗi hay gặp khi build request

Ví dụ đầy đủ bằng Python

Form-encoded

Submit rồi polling kết quả:

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

Gửi bằng JSON

Chỉ đổi bước submit, phần polling giữ nguyên:

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

Polling res.php luôn dùng GET với query params, dù task được submit bằng định dạng nào.

Ví dụ đầy đủ bằng Node.js

Form-encoded

Dùng querystring để encode payload trước khi gửi:

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;

Gửi bằng JSON

Truyền thẳng object cho axios, không cần encode tay:

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;

Bản JSON gọn hơn vì không cần import querystring — lý do nhiều service Node.js hiện đại mặc định chọn JSON.

CAPTCHA hình ảnh: định dạng ảnh hưởng nhiều hơn

Với text/image CAPTCHA (OCR), cách bạn gửi file thực sự thay đổi cấu trúc request, không chỉ đổi header:

Upload file qua multipart (form-encoded)

Đưa file nhị phân thẳng vào request, không cần encode:

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

Base64 trong JSON

Encode ảnh thành Base64 rồi nhét vào field body:

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

Base64 trong form-encoded

Cùng chuỗi Base64 đó, gửi qua form thay vì JSON:

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

Multipart tránh ảnh phình to ~33% do encode Base64; Base64-trong-JSON tiện hơn khi pipeline đã xử lý JSON toàn hệ thống.

Câu hỏi thường gặp

Vì sao request báo lỗi dù dữ liệu trông vẫn đúng?

Thường do body và Content-Type không khớp — ví dụ gửi payload JSON nhưng dùng data= thay vì json= trong requests. Kiểm tra lại keyword trong thư viện HTTP trước khi debug xa hơn.

Polling res.php có cần gửi bằng JSON không?

Không. Polling luôn dùng GET với query params, bất kể task được submit bằng form-encoded hay JSON.

JSON có giúp gửi nhiều tham số proxy hoặc site-key cùng lúc không?

Có — JSON hỗ trợ mảng và object lồng nhau native, còn form-encoded chỉ xử lý tốt cặp key-value phẳng. Cấu trúc dữ liệu phức tạp thì JSON tự nhiên hơn.

Đang migrate từ 2Captcha thì nên giữ định dạng nào?

Giữ form-encoded trong giai đoạn đầu. API gốc kiểu 2Captcha dùng form-encoded, nên giữ nguyên format giúp bạn đổi base URL và key mà gần như không phải sửa logic request.

Hướng dẫn liên quan

• Cây quyết định xử lý lỗi API CaptchaAI
• Thẻ tham khảo nhanh API CaptchaAI

Chọn định dạng phù hợp với stack của bạn — thử API CaptchaAI ngay hôm nay.