Skip to content

Captcha

Captcha token verification and widget issuance.

1. Overview

Base path: https://api.infrai.cc/v1/captcha
Auth header: Authorization: Bearer $INFRAI_API_KEY
bash
# Call any /v1/captcha capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/captcha/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

2. Methods (1)

2.1captcha.verify

POST /v1/captcha/verify

Verify a captcha token from the browser.

Parameters

NameTypeRequiredDescription
tokenstring
Required
Token returned by the captcha widget.
≥ 1 chars
vendor"hcaptcha" | "recaptcha" | "turnstile" | "infrai"OptionalPin a specific vendor instead of auto-routing.
remote_ipstringOptionalClient IP for risk scoring.
min_scorenumberOptionalMinimum acceptable score (score-based vendors).

Returns

CaptchaVerifyResult { valid, score?, vendor, hostname?, action? }
NameTypeDescription
successbooleanWhether the captcha verification passed
scorenumber | null0=bot, 1=human (normalized).
0–1
hostnamestring | nullHostname of the site where the captcha was solved
actionstring | nullAction performed (e.g. created, updated, deleted)
challenge_tsstringISO 8601 timestamp when the captcha challenge was issued
format: date-time
vendorstringVendor that handled or will handle this request
reasons("timeout-or-duplicate" | "invalid-input-response" | "invalid-sitekey" | "low-score" | "hostname-mismatch")[]List of reasons contributing to the risk score

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/captcha/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "sample"}'
Advanced: pin a vendor

By default infrai routes each call to the best available provider — you do not pick a vendor. As an escape hatch, this capability accepts an optional vendor parameter to pin one specific provider. Every live vendor for this capability is available in real time from the discovery endpoint for the capability id — see the discovery API.

GET /v1/discovery/{capability}

captcha.verify

3. All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

captcha.verifyPOST /v1/captcha/verify

Verify a client-submitted CAPTCHA token against the vendor and return the success result; idempotent.

Parameters (10)
NameTypeRequiredDescription
tokenstringRequiredOne-time vendor response token from the client widget.
≥ 1 chars
vendorstring | nullOptionalPin to a specific vendor (turnstile/hcaptcha/recaptcha). Default: routed.
ipstring | nullOptionalEnd-user IP for vendor-side risk scoring. Alias: `remoteip`.
remoteipstring | nullOptionalAlias of `ip` (module accepts both; `ip = ip or remoteip`).
actionstring | nullOptionalAction name bound at challenge time; rejected if mismatched (anti cross-form replay).
expected_hostnamestring | nullOptionalIf set, token hostname must match.
score_thresholdnumber | nullOptionalMinimum acceptable score [0,1]; below → fail with low-score reason.
0–1
mode"default_vendor" | "verified_account"OptionalRouting axis (CaptchaMode); orthogonal to widget_mode.
default: "default_vendor"
sitekey_labelstringOptionalKeyPool entry name selecting which sitekey/secret to verify against (multi-sitekey accounts).
default: "default"
idempotency_keystring | nullOptionalCarries one-time-token semantics; duplicate replay → CAPTCHA_IDEMPOTENCY_KEY_CONFLICT.

4. End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

A copy-paste-runnable single-file Python program (stdlib only, no SDK): set your INFRAI_API_KEY, run it, and walk this module's core flow with REAL billed calls — later steps reuse real fields returned by earlier ones. The 12-line helper is the entire integration.

python
#!/usr/bin/env python3
"""Infrai · captcha — runnable real-app example (single file, zero deps).

Copy this file, set your key, run it: every step is a REAL call to
api.infrai.cc, billed at the real (tiny) per-call price, printing the
live JSON response. Get a key at https://infrai.cc/login (Google/
GitHub sign-in grants $2 free credit); add funds at
https://infrai.cc/billing. No SDK — the 12-line helper below is the
entire integration."""
import json
import os
from urllib import error, request

KEY = os.environ.get("INFRAI_API_KEY") or "ifr_..."  # <- your key
BASE = "https://api.infrai.cc"


# Same raw HTTPS POST/GET as every per-method example on this page —
# wrapped once for reuse. There is nothing else to it: no SDK.
def infrai(method, path, body=None):
    req = request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": f"Bearer {KEY}",
                 "Content-Type": "application/json"})
    try:
        with request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except error.HTTPError as e:
        return json.loads(e.read())


def show(label, resp):
    print(f"\n== {label} ==")
    print(json.dumps(resp, indent=2, ensure_ascii=False))
    return resp


# 1) capture token — client widget handoff
r1 = show("capture token", {"note": "Render the CAPTCHA widget in the browser, then copy the one-time token into the verify step below."})

# 2) captcha.verify — POST /v1/captcha/verify · Verify a client-submitted CAPTCHA token against the vendor and return the success result; idempotent.
r2 = show("captcha.verify", infrai("POST", "/v1/captcha/verify", {"token":"<client-captcha-token>","remote_ip":"203.0.113.5"}))