Thiết lập và xác thực khóa API CaptchaAI

API key là thông tin xác thực duy nhất mà CaptchaAI dùng: không có OAuth, không chữ ký request riêng, không secret theo từng method. Bạn lấy khóa trong bảng điều khiển, đính kèm vào mỗi request qua tham số key, và cùng khóa đó chạy được cho mọi loại CAPTCHA lẫn mọi endpoint. Vì key nắm toàn bộ quyền truy cập và trực tiếp tiêu số dư, hãy đối xử với nó như mật khẩu database. Bài này đi qua bốn việc theo thứ tự bạn cần khi tích hợp lần đầu: lấy key, xác thực request, kiểm tra số dư và giữ key an toàn khi lên production.

Lấy API key trong bảng điều khiển

1. Tạo tài khoản tại captchaai.com
2. Đăng nhập vào bảng điều khiển của bạn
3. Mở mục API Settings hoặc Account
4. Sao chép API key — chuỗi trông giống như abc123def456...
5. Nạp số dư cho tài khoản (bắt đầu từ $1)

Số dư tính bằng USD, nên developer Việt Nam thường thanh toán qua thẻ quốc tế hoặc bên trung gian; giá gói cũng niêm yết bằng USD, ví dụ gói BASIC ($15/tháng, 5 thread). CaptchaAI tính tiền theo thread (luồng giải đồng thời), không theo từng lần giải, nên key vẫn giữ nguyên khi bạn nâng gói.

Xác minh key trước khi tích hợp

Ngay sau khi có key, hãy gọi thử endpoint kiểm tra số dư — lệnh xác thực rẻ nhất, xác nhận cùng lúc ba điều:

• Key đúng và đang hoạt động
• IP của bạn ra được tới API
• Tài khoản đã có số dư

Nếu bước này trả về một số thập phân, key đã sẵn sàng để tích hợp.

Xác thực mọi request bằng tham số key

Mọi lệnh gọi API đều đính kèm key dưới dạng tham số key. Ba endpoint dưới đây là bộ tối thiểu cho một vòng giải hoàn chỉnh: gửi task, polling kết quả và kiểm tra số dư.

Gửi CAPTCHA lên in.php

GET https://ocr.captchaai.com/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=SITE_KEY&pageurl=URL

Polling kết quả từ res.php

GET https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=TASK_ID

Kiểm tra số dư

GET https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=getbalance

Endpoint in.php trả về ID task, sau đó bạn polling res.php cho tới khi nhận token. getbalance trả về một số thập phân — số dư USD của bạn. Nếu phản hồi bắt đầu bằng ERROR_ hoặc IP_BANNED, cần xử lý trước khi đi tiếp.

Ví dụ code: Python, Node.js và cURL

Các đoạn dưới đây đọc key từ biến môi trường, kiểm tra số dư rồi gửi một task reCAPTCHA v2. Chỉ cần thay googlekey và pageurl bằng giá trị thật của trang cần giải.

Python

import requests
import os

# Load from environment variable (recommended)
API_KEY = os.environ.get("CAPTCHAAI_API_KEY")

# Check balance
balance = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": API_KEY,
    "action": "getbalance"
})
print(f"Balance: ${balance.text}")

# Submit a CAPTCHA
resp = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "6Le-wvkS...",
    "pageurl": "https://example.com"
})
print(f"Response: {resp.text}")

Node.js

const axios = require("axios");

const API_KEY = process.env.CAPTCHAAI_API_KEY;

// Check balance
const balance = await axios.get("https://ocr.captchaai.com/res.php", {
  params: { key: API_KEY, action: "getbalance" },
});
console.log(`Balance: $${balance.data}`);

// Submit a CAPTCHA
const resp = await axios.get("https://ocr.captchaai.com/in.php", {
  params: {
    key: API_KEY,
    method: "userrecaptcha",
    googlekey: "6Le-wvkS...",
    pageurl: "https://example.com",
  },
});
console.log(`Response: ${resp.data}`);

cURL

# Check balance
curl "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=getbalance"

# Submit reCAPTCHA v2
curl "https://ocr.captchaai.com/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=SITE_KEY&pageurl=https://example.com"

Cùng một tham số key xuất hiện trong cả ba ví dụ — đó là toàn bộ cơ chế xác thực, không có bước bắt tay hay refresh token nào khác.

Bảo mật API key

Một key bị lộ nghĩa là người khác tiêu số dư của bạn. Với đội QA hay agency ở TP.HCM dùng chung tài khoản cho nhiều pipeline scraping, chỉ cần key lọt vào commit hoặc log là cả nhóm gánh chi phí phát sinh.

Dùng biến môi trường

Không bao giờ hardcode API key thẳng trong mã nguồn:

# ❌ Bad — key in source code
API_KEY = "abc123def456"

# ✅ Good — key from environment
API_KEY = os.environ["CAPTCHAAI_API_KEY"]

Đặt biến môi trường tùy theo hệ điều hành:

# Linux/macOS
export CAPTCHAAI_API_KEY="abc123def456"

# Windows PowerShell
$env:CAPTCHAAI_API_KEY = "abc123def456"

# Windows CMD
set CAPTCHAAI_API_KEY=abc123def456

Dùng file .env cho môi trường phát triển

Khi phát triển cục bộ, đặt key trong file .env:

# .env
CAPTCHAAI_API_KEY=abc123def456

# Python
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.environ["CAPTCHAAI_API_KEY"]

// Node.js
require("dotenv").config();
const API_KEY = process.env.CAPTCHAAI_API_KEY;

Thêm .env vào .gitignore để tránh vô tình commit thông tin xác thực lên repo:

# .gitignore
.env

File .env đủ dùng cho một máy cá nhân. Khi lên CI runner hay nhiều server dùng chung, hãy lấy key từ secrets manager thay vì copy file qua lại, và bật whitelist IP trong bảng điều khiển để key chỉ có tác dụng từ dải IP production — một key rò rỉ ra ngoài dải đó sẽ vô dụng.

Xoay API key định kỳ

Nếu bạn nghi ngờ một key đã bị lộ:

1. Đăng nhập vào bảng điều khiển CaptchaAI của bạn
2. Tạo API key mới
3. Cập nhật biến môi trường ở mọi nơi đang dùng key cũ
4. Thu hồi key cũ

CaptchaAI không có endpoint thống kê riêng cho từng key ngoài số dư, nên getbalance là công cụ phát hiện lộ key thực tế nhất.

Bảng mã lỗi xác thực thường gặp

Các mã lỗi này là chuỗi tiếng Anh do API trả về nguyên văn — giữ nguyên khi log và so khớp trong code. IP_BANNED thường không phải do bạn bị cấm vĩnh viễn mà do một worker cấu hình sai gửi liên tục key sai.

Vài thói quen vận hành giúp bắt sự cố key sớm khi nhiều pipeline dùng chung một tài khoản:

• Poll getbalance mỗi phút và ghi thành chỉ số (gauge) để cảnh báo khi số dư tụt bất thường.
• Gắn nhãn mỗi request log theo service và môi trường để tách được nguồn đang tiêu số dư.
• Cache các lỗi xác thực ít nhất 60 giây, tránh để một tiến trình hỏng dội API tới mức bị chặn IP.

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

API key CaptchaAI nằm ở đâu?

Trong bảng điều khiển, mục API Settings hoặc Account. Đăng nhập, sao chép chuỗi key và nạp tối thiểu $1 là sẵn sàng gửi request đầu tiên.

Một key có dùng cho mọi loại CAPTCHA không?

Có. Cùng một API key giải được reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3, ảnh/OCR và các loại được hỗ trợ khác, trên mọi endpoint — không cần key riêng cho từng loại.

Làm sao kiểm tra key có hoạt động trước khi tích hợp?

Gọi res.php?action=getbalance một lần. Nhận về số thập phân là key hợp lệ, IP thông và tài khoản có tiền; nhận ERROR_... thì xử lý theo bảng mã lỗi ở trên.

Nhiều dự án dùng chung một key có được không?

Được. Một key chạy trên mọi dự án và server. Cần tách hóa đơn theo team thì tạo tài khoản riêng thay vì chia nhỏ key.

Nghi ngờ key bị lộ thì xử lý thế nào?

Tạo key mới trong bảng điều khiển, cập nhật biến môi trường ở mọi nơi rồi thu hồi key cũ. Song song, theo dõi getbalance: số dư tụt khi pipeline không chạy gần như chắc chắn là key đang bị dùng ở nơi khác.

Hướng dẫn liên quan

• Bắt đầu nhanh với CaptchaAI
• Các định dạng phản hồi API
• Chọn giữa polling và callback