Pengaturan dan Autentikasi Kunci API CaptchaAI

CaptchaAI hanya mengenal satu kredensial: API key Anda. Tidak ada OAuth, tidak ada request signature, dan tidak ada secret khusus per method — cukup satu kunci yang Anda kirim sebagai parameter key di setiap permintaan. Panduan ini menunjukkan cara mengambil kunci tersebut, memastikannya valid, mengautentikasi request, dan menyimpannya dengan aman saat kode Anda naik ke produksi.

Satu string ini membuka seluruh akun dan saldo Anda. Perlakukan seperti password database: jangan pernah ditulis di kode, jangan pernah ikut ter-commit.

Mengambil API key dari dashboard

1. Buat akun di captchaai.com
2. Masuk ke dashboard Anda
3. Buka menu API Settings atau Account
4. Salin API key Anda — berupa string heksadesimal 32 karakter huruf kecil, misalnya 1a2b3c4d5e6f7890abcdef1234567890
5. Tambahkan dana ke saldo Anda (mulai dari $1)

Beberapa catatan sebelum Anda melangkah lebih jauh:

• Saldo awal $1 sudah cukup untuk menguji beberapa penyelesaian CAPTCHA sebelum memilih paket bulanan.
• Penagihan CaptchaAI berbasis thread, bukan per solve — Anda baru memikirkan tier seperti BASIC ($15/bulan, 5 thread) atau ADVANCE ($90/bulan, 50 thread) setelah tahu berapa banyak permintaan bersamaan yang Anda butuhkan.
• Satu kunci yang sama berlaku di semua proyek, server, dan endpoint Anda.

Autentikasi: satu kunci di setiap request

Setiap panggilan API menyertakan kunci Anda sebagai parameter key. Tidak ada header khusus dan tidak ada langkah handshake — parameter key itulah yang menentukan apakah request diterima.

Kirim CAPTCHA

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

Polling hasil

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

Cek saldo

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

Endpoint getbalance juga cara termurah untuk memverifikasi kunci sebelum Anda menyambungkannya ke klien apa pun. Sekali panggil, dan ia memastikan tiga hal sekaligus: kunci benar, IP Anda bisa menjangkau API, dan akun sudah terisi saldo. Outputnya satu angka desimal (saldo dalam USD). Jika responsnya diawali ERROR_ atau IP_BANNED, ada yang perlu diperbaiki — kunci, egress jaringan, atau status akun — sebelum Anda lanjut.

Contoh kode: Python, Node.js, dan cURL

Ketiga contoh di bawah menjalankan alur yang sama: cek saldo dulu, lalu kirim reCAPTCHA v2. Kunci selalu dibaca dari environment variable, bukan ditulis langsung di kode.

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"

Kunci yang sama melayani semua endpoint dan semua jenis CAPTCHA yang didukung. Anda hanya mengganti nilai method, bukan kuncinya:

• reCAPTCHA v2, reCAPTCHA v2 Invisible, dan reCAPTCHA v3
• Cloudflare Turnstile dan Cloudflare Challenge
• GeeTest v3, image/OCR, serta grid image
• CaptchaFox (beta), Friendly Captcha (beta), dan Lemin (beta)

Menjaga keamanan API key

Pakai environment variable

Jangan pernah menuliskan API key langsung (hardcode) di dalam kode sumber:

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

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

Tetapkan variabelnya:

# Linux/macOS
export CAPTCHAAI_API_KEY="abc123def456"

# Windows PowerShell
$env:CAPTCHAAI_API_KEY = "abc123def456"

# Windows CMD
set CAPTCHAAI_API_KEY=abc123def456

Simpan di file .env untuk pengembangan lokal

Saat mengembangkan di mesin sendiri, taruh kunci di 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;

Tambahkan .env ke .gitignore Anda agar kredensial tidak ikut ter-commit ke repositori:

# .gitignore
.env

Rotasi kunci saat dicurigai bocor

Rotasi bukan hanya reaksi darurat. Jadwalkan penggantian kunci berkala agar kredensial lama tidak menumpuk di riwayat konfigurasi.

Jika Anda menduga sebuah kunci telah bocor:

1. Masuk ke dashboard CaptchaAI Anda
2. Buat API key baru
3. Perbarui environment variable Anda
4. Cabut kunci lama

Kode respons kesalahan yang umum

Satu kebiasaan operasional yang menyelamatkan banyak masalah:

• Cache kegagalan autentikasi seperti ERROR_WRONG_USER_KEY selama minimal 60 detik di sisi worker.
• Tanpa itu, worker yang salah konfigurasi bisa terus menghantam API dan berujung pada status IP_BANNED.
• Emit saldo getbalance sebagai metrik dan beri alarm saat turun drastis dalam jendela 5 menit.

Satu kunci untuk banyak worker

Kondisi yang lumrah di tim scraping dan otomasi di Indonesia — baik agensi price-monitoring maupun pekerja freelance bergaya Fastwork — adalah satu akun mendanai beberapa pipeline sekaligus. Misalnya sekumpulan worker yang di-deploy ke region ap-southeast-3 (Jakarta) dan ap-southeast-1 (Singapura) berbagi satu API key. Dua kebiasaan menjaga hal ini tetap aman:

1. Jangan menyalin file .env ke setiap server. Tarik kunci dari secrets manager (misalnya AWS Secrets Manager atau HashiCorp Vault) sehingga hanya ada satu sumber kebenaran yang bisa dirotasi sekali jalan.
2. Aktifkan IP whitelisting di dashboard CaptchaAI agar kunci hanya mengotorisasi request dari IP egress produksi Anda — kunci yang bocor ke luar rentang itu menjadi tidak berguna.

Pantau juga saldo lewat getbalance secara berkala; penurunan saldo mendadak dari IP tak dikenal adalah tanda paling awal sebuah kunci telah disalahgunakan.

Pertanyaan umum

Bagaimana cara menguji apakah API key sudah valid?

Panggil endpoint getbalance satu kali. Jika muncul angka desimal, kunci valid dan akun terisi. Jika muncul ERROR_ atau IP_BANNED, perbaiki dulu sebelum lanjut.

Di mana sebaiknya menyimpan API key di server produksi?

Di secrets manager, bukan di kode atau file .env yang disalin manual. Untuk satu developer, .env yang masuk .gitignore sudah cukup; untuk CI runner, banyak server, atau tim, gunakan secrets manager plus IP whitelisting.

Apa yang harus dilakukan jika API key bocor?

Segera buat kunci baru dari dashboard, perbarui environment variable atau secrets manager, lalu cabut kunci lama. Aktifkan IP whitelisting agar kunci yang bocor tidak bisa dipakai dari luar IP Anda.

Berapa saldo minimum untuk mulai memakai API?

Anda bisa menambahkan dana mulai dari $1 — cukup untuk menguji beberapa penyelesaian sebelum memilih paket thread bulanan seperti BASIC ($15/bulan, 5 thread).

Perlukah kunci berbeda untuk tiap jenis CAPTCHA?

Tidak. Satu API key melayani reCAPTCHA, Turnstile, GeeTest v3, image/OCR, dan tipe lain yang didukung — Anda cukup mengubah nilai method di setiap request.

Panduan terkait

• Panduan memulai CaptchaAI
• Format respons API CaptchaAI
• Callback vs polling