Python Integration

pip install gkcaptcha

from gkcaptcha import GkCaptchaClient

client = GkCaptchaClient(
    secret_key="sk_live_...",
    site_key="pk_live_...",
)

result = client.verify_token(request.POST.get("captchaToken"))
if not result.success:
    return HttpResponseForbidden("CAPTCHA verification failed")

import asyncio
from gkcaptcha import GkCaptchaClient

client = GkCaptchaClient(secret_key="sk_live_...", site_key="pk_live_...")

async def verify(token: str):
    result = await client.verify_token_async(token)
    return result.success

# views.py
from django.http import HttpResponseForbidden
from gkcaptcha import GkCaptchaClient, VerifyOptions

client = GkCaptchaClient()  # reads from environment

def my_form_view(request):
    if request.method == "POST":
        token = request.POST.get("captchaToken", "")
        result = client.verify_token(token, options=VerifyOptions(
            client_ip=request.META.get("REMOTE_ADDR"),
            user_agent=request.META.get("HTTP_USER_AGENT"),
        ))
        if not result.success:
            return HttpResponseForbidden("CAPTCHA verification failed")
        # Process form...

from fastapi import Depends, HTTPException, Request
from gkcaptcha import GkCaptchaClient, GkCaptchaError, VerifyOptions

client = GkCaptchaClient()  # reads from environment

async def verify_captcha(request: Request, captcha_token: str) -> None:
    options = VerifyOptions(
        client_ip=request.client.host,
        user_agent=request.headers.get("user-agent"),
    )
    try:
        result = await client.verify_token_async(captcha_token, options=options)
    except GkCaptchaError as e:
        if e.code == "TIMEOUT":
            raise HTTPException(status_code=503, detail="CAPTCHA service timeout")
        raise
    if not result.success:
        raise HTTPException(status_code=400, detail="CAPTCHA verification failed")

@app.post("/register")
async def register(form: RegisterForm, _: None = Depends(verify_captcha)):
    ...

@dataclass(frozen=True)
class VerifyTokenResponse:
    success: bool           # True = human, False = bot/failed
    score: float | None     # Risk score 0.0 (human) to 1.0 (bot)
    timestamp: int | None   # Unix timestamp of verification
    error: str | None       # Error message if success=False
    reason_code: str | None # Machine-readable failure reason
    fail_open: bool         # True if network error caused pass-through

# Fail-closed mode: raises GkCaptchaError on network failure
client = GkCaptchaClient(secret_key="...", site_key="...", fail_closed=True)
try:
    result = client.verify_token(token)
except GkCaptchaError as e:
    if e.code == "NETWORK_ERROR":
        return HttpResponse("Service temporarily unavailable", status=503)
    raise

export GKCAPTCHA_SECRET_KEY=sk_live_...
export GKCAPTCHA_SITE_KEY=pk_live_...

# Then construct without arguments:
client = GkCaptchaClient()