验证码

验证码令牌校验与控件发放。

1. 概览

基础路径: https://api.infrai.cc/v1/captcha

鉴权头: 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. 方法 (4)

2.1captcha.verify

POST /v1/captcha/verify

校验由 Infrai 托管浏览器控件返回的验证码令牌。

参数

名称	类型	必填	说明
`widget_record_id`	`string`	必填	captcha.widget.create 返回的 Infrai widget ID。 `≥ 1 chars`
`token`	`string`	必填	浏览器控件返回的一次性令牌。 `≥ 1 chars`
`ip`	`string`	可选	用于风险评分的客户端 IP。
`score_threshold`	`number`	可选	可接受的最低分（基于分数的供应商）。 `0–1`

CaptchaVerification { success, score?, vendor, hostname?, action?, reasons }

名称	类型	说明
`success`	`boolean`	验证码校验是否通过
`score`	`number \| null`	0=机器人，1=人类（归一化）。 `0–1`
`hostname`	`string \| null`	验证码被解决的站点主机名
`action`	`string \| null`	执行的操作（如 created、updated、deleted）
`challenge_ts`	`string`	ISO 8601 时间戳：the captcha challenge was issued（ISO 8601） `format: date-time`
`vendor`	`string`	处理此请求的供应商
`reasons`	`("timeout-or-duplicate" \| "invalid-input-response" \| "invalid-sitekey" \| "low-score" \| "hostname-mismatch")[]`	reasons contributing to the risk score列表

示例

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

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 '{"widget_record_id": "cwid_...", "token": "<client-captcha-token>", "ip": "203.0.113.5"}'

python

# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/captcha/verify",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
    json={'widget_record_id': 'cwid_...', 'token': '<client-captcha-token>', 'ip': '203.0.113.5'},
)
resp.raise_for_status()
print(resp.json())

javascript

// Browser prerequisite: fetch the public WidgetSetup from your server; never expose INFRAI_API_KEY.
const widget = await fetch("/captcha-config").then((r) => r.json());
const script = document.createElement("script");
script.src = widget.embed_url;
script.onload = () => turnstile.render("#captcha", {
  sitekey: widget.sitekey, action: "signup",
  callback: (token) => fetch("/signup", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token, widget_record_id: widget.widget_record_id }),
  }),
});
document.head.appendChild(script); // page contains <div id="captcha"></div>

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/verify",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"widget_record_id": "cwid_...", "token": "<client-captcha-token>", "ip": "203.0.113.5"}),
  },
);
console.log(await resp.json());

typescript

declare const turnstile: { render(selector: string, options: { sitekey: string; action: string; callback(token: string): void }): void };
// Browser prerequisite: fetch the public WidgetSetup from your server; never expose INFRAI_API_KEY.
const widget = await fetch("/captcha-config").then((r) => r.json());
const script = document.createElement("script");
script.src = widget.embed_url;
script.onload = () => turnstile.render("#captcha", {
  sitekey: widget.sitekey, action: "signup",
  callback: (token) => fetch("/signup", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token, widget_record_id: widget.widget_record_id }),
  }),
});
document.head.appendChild(script); // page contains <div id="captcha"></div>

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/verify",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"widget_record_id": "cwid_...", "token": "<client-captcha-token>", "ip": "203.0.113.5"}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// Zero-install REST call — no SDK required (short-term the API is REST-only).
package main

import (
	"bytes"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{"widget_record_id": "cwid_...", "token": "<client-captcha-token>", "ip": "203.0.113.5"}`)
	req, _ := http.NewRequest("POST", "https://api.infrai.cc/v1/captcha/verify", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

java

// Zero-install REST call — no SDK required (short-term the API is REST-only).
import java.net.URI;
import java.net.http.*;

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.infrai.cc/v1/captcha/verify"))
    .header("Authorization", "Bearer " + System.getenv("INFRAI_API_KEY"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"widget_record_id\": \"cwid_...\", \"token\": \"<client-captcha-token>\", \"ip\": \"203.0.113.5\"}"))
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

csharp

// Zero-install REST call — no SDK required (short-term the API is REST-only).
using System;
using System.Net.Http;

var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("POST"), "https://api.infrai.cc/v1/captcha/verify");
var key = Environment.GetEnvironmentVariable("INFRAI_API_KEY");
req.Headers.Add("Authorization", "Bearer " + key);
req.Content = new StringContent("{\"widget_record_id\": \"cwid_...\", \"token\": \"<client-captcha-token>\", \"ip\": \"203.0.113.5\"}", System.Text.Encoding.UTF8, "application/json");
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

php

<?php
// Zero-install REST call — no SDK required (short-term the API is REST-only).
$ch = curl_init("https://api.infrai.cc/v1/captcha/verify");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("INFRAI_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"widget_record_id\": \"cwid_...\", \"token\": \"<client-captcha-token>\", \"ip\": \"203.0.113.5\"}");
$response = curl_exec($ch);
curl_close($ch);
echo $response;

ruby

# Zero-install REST call — no SDK required (short-term the API is REST-only).
require "net/http"
require "uri"

uri = URI("https://api.infrai.cc/v1/captcha/verify")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV['INFRAI_API_KEY']}"
req["Content-Type"] = "application/json"
req.body = '{"widget_record_id": "cwid_...", "token": "<client-captcha-token>", "ip": "203.0.113.5"}'
res = http.request(req)
puts res.body

rust

// Zero-install REST call — no SDK required (short-term the API is REST-only). (uses the reqwest + tokio crates)
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let resp = reqwest::Client::new()
        .post("https://api.infrai.cc/v1/captcha/verify")
        .header("Authorization", format!("Bearer {}", env::var("INFRAI_API_KEY")?))
        .header("Content-Type", "application/json")
        .body(r#"{"widget_record_id": "cwid_...", "token": "<client-captcha-token>", "ip": "203.0.113.5"}"#)
        .send()
        .await?;
    println!("{}", resp.text().await?);
    Ok(())
}

2.2captcha.widget.create

POST /v1/captcha/widget/create

完全通过 Infrai 创建验证码组件并获取浏览器公开配置。

参数

名称	类型	必填	说明
`name`	`string`	必填	便于识别的 widget 名称。 `1–128 chars`
`domains`	`string[]`	可选	允许渲染该 widget 的主机名。
`widget_mode`	`"managed" \| "non-interactive" \| "invisible"`	可选	供应商控件的渲染模式。 `default: "managed"`

WidgetSetup { widget_record_id, vendor, sitekey, embed_url, embed_snippet, status }

名称	类型	说明
`widget_record_id`	`string`	Infrai widget ID；用于 widget.get 和 captcha.verify。
`name`	`string`	Human label; doubles as verify-time sitekey_label hint.
`vendor`	`string`	-
`status`	`any`	vendor widget 和服务端验证密钥均已成功创建。
`sitekey`	`string`	Public; embed in client HTML. `≥ 1 chars`
`widget_id`	`string \| null`	Vendor-side widget identifier.
`domains`	`string[]`	-
`embed_url`	`string`	Public vendor browser script URL. `format: uri`
`embed_snippet`	`string`	Copy-paste HTML snippet. `≥ 1 chars`
`dashboard_url`	`string \| null`	Vendor dashboard link for manual completion.
`message`	`string \| null`	Human-readable note (e.g. manual setup instructions).
`metadata`	`object \| null`	-
`error`	`string \| null`	-
`created_at`	`string`	- `format: date-time`

示例

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

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/widget/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "signup", "domains": ["app.example.com"], "widget_mode": "managed"}'

python

# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/captcha/widget/create",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
    json={'name': 'signup', 'domains': ['app.example.com'], 'widget_mode': 'managed'},
)
resp.raise_for_status()
print(resp.json())

javascript

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "signup", "domains": ["app.example.com"], "widget_mode": "managed"}),
  },
);
console.log(await resp.json());

typescript

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "signup", "domains": ["app.example.com"], "widget_mode": "managed"}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// Zero-install REST call — no SDK required (short-term the API is REST-only).
package main

import (
	"bytes"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{"name": "signup", "domains": ["app.example.com"], "widget_mode": "managed"}`)
	req, _ := http.NewRequest("POST", "https://api.infrai.cc/v1/captcha/widget/create", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

java

// Zero-install REST call — no SDK required (short-term the API is REST-only).
import java.net.URI;
import java.net.http.*;

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.infrai.cc/v1/captcha/widget/create"))
    .header("Authorization", "Bearer " + System.getenv("INFRAI_API_KEY"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"name\": \"signup\", \"domains\": [\"app.example.com\"], \"widget_mode\": \"managed\"}"))
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

csharp

// Zero-install REST call — no SDK required (short-term the API is REST-only).
using System;
using System.Net.Http;

var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("POST"), "https://api.infrai.cc/v1/captcha/widget/create");
var key = Environment.GetEnvironmentVariable("INFRAI_API_KEY");
req.Headers.Add("Authorization", "Bearer " + key);
req.Content = new StringContent("{\"name\": \"signup\", \"domains\": [\"app.example.com\"], \"widget_mode\": \"managed\"}", System.Text.Encoding.UTF8, "application/json");
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

php

<?php
// Zero-install REST call — no SDK required (short-term the API is REST-only).
$ch = curl_init("https://api.infrai.cc/v1/captcha/widget/create");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("INFRAI_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"name\": \"signup\", \"domains\": [\"app.example.com\"], \"widget_mode\": \"managed\"}");
$response = curl_exec($ch);
curl_close($ch);
echo $response;

ruby

# Zero-install REST call — no SDK required (short-term the API is REST-only).
require "net/http"
require "uri"

uri = URI("https://api.infrai.cc/v1/captcha/widget/create")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV['INFRAI_API_KEY']}"
req["Content-Type"] = "application/json"
req.body = '{"name": "signup", "domains": ["app.example.com"], "widget_mode": "managed"}'
res = http.request(req)
puts res.body

rust

// Zero-install REST call — no SDK required (short-term the API is REST-only). (uses the reqwest + tokio crates)
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let resp = reqwest::Client::new()
        .post("https://api.infrai.cc/v1/captcha/widget/create")
        .header("Authorization", format!("Bearer {}", env::var("INFRAI_API_KEY")?))
        .header("Content-Type", "application/json")
        .body(r#"{"name": "signup", "domains": ["app.example.com"], "widget_mode": "managed"}"#)
        .send()
        .await?;
    println!("{}", resp.text().await?);
    Ok(())
}

2.3captcha.widget.list

GET /v1/captcha/widget/list

列出当前账户由 Infrai 托管的验证码组件。

WidgetListResult { items: WidgetSetup[], total_count, next_cursor? }

名称	类型	说明
`items`	`object[]`	-
`items[].widget_record_id`	`string`	Infrai widget ID；用于 widget.get 和 captcha.verify。
`items[].name`	`string`	Human label; doubles as verify-time sitekey_label hint.
`items[].vendor`	`string`	-
`items[].status`	`any`	vendor widget 和服务端验证密钥均已成功创建。
`items[].sitekey`	`string`	Public; embed in client HTML. `≥ 1 chars`
`items[].widget_id`	`string \| null`	Vendor-side widget identifier.
`items[].domains`	`string[]`	-
`items[].embed_url`	`string`	Public vendor browser script URL. `format: uri`
`items[].embed_snippet`	`string`	Copy-paste HTML snippet. `≥ 1 chars`
`items[].dashboard_url`	`string \| null`	Vendor dashboard link for manual completion.
`items[].message`	`string \| null`	Human-readable note (e.g. manual setup instructions).
`items[].metadata`	`object \| null`	-
`items[].error`	`string \| null`	-
`items[].created_at`	`string`	- `format: date-time`
`total_count`	`integer`	Optional; may be omitted for high-cardinality lists. `≥ 0`
`next_cursor`	`string \| null`	传入 list() 以获取下一页；null 表示结束。

示例

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

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 GET https://api.infrai.cc/v1/captcha/widget/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/captcha/widget/list",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
)
resp.raise_for_status()
print(resp.json())

javascript

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// Zero-install REST call — no SDK required (short-term the API is REST-only).
package main

import (
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.infrai.cc/v1/captcha/widget/list", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

java

// Zero-install REST call — no SDK required (short-term the API is REST-only).
import java.net.URI;
import java.net.http.*;

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.infrai.cc/v1/captcha/widget/list"))
    .header("Authorization", "Bearer " + System.getenv("INFRAI_API_KEY"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

csharp

// Zero-install REST call — no SDK required (short-term the API is REST-only).
using System;
using System.Net.Http;

var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("GET"), "https://api.infrai.cc/v1/captcha/widget/list");
var key = Environment.GetEnvironmentVariable("INFRAI_API_KEY");
req.Headers.Add("Authorization", "Bearer " + key);
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

php

<?php
// Zero-install REST call — no SDK required (short-term the API is REST-only).
$ch = curl_init("https://api.infrai.cc/v1/captcha/widget/list");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("INFRAI_API_KEY"),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

ruby

# Zero-install REST call — no SDK required (short-term the API is REST-only).
require "net/http"
require "uri"

uri = URI("https://api.infrai.cc/v1/captcha/widget/list")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV['INFRAI_API_KEY']}"
res = http.request(req)
puts res.body

rust

// Zero-install REST call — no SDK required (short-term the API is REST-only). (uses the reqwest + tokio crates)
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let resp = reqwest::Client::new()
        .get("https://api.infrai.cc/v1/captcha/widget/list")
        .header("Authorization", format!("Bearer {}", env::var("INFRAI_API_KEY")?))
        .send()
        .await?;
    println!("{}", resp.text().await?);
    Ok(())
}

2.4captcha.widget.get

GET /v1/captcha/widget/get/{widget_record_id}

获取 Infrai 托管验证码组件的浏览器公开配置。

参数

名称	类型	必填	说明
`widget_record_id`	`string`	必填	captcha.widget.create 返回的 Infrai widget ID。

WidgetSetup { widget_record_id, vendor, sitekey, embed_url, embed_snippet, status }

名称	类型	说明
`widget_record_id`	`string`	Infrai widget ID；用于 widget.get 和 captcha.verify。
`name`	`string`	Human label; doubles as verify-time sitekey_label hint.
`vendor`	`string`	-
`status`	`any`	vendor widget 和服务端验证密钥均已成功创建。
`sitekey`	`string`	Public; embed in client HTML. `≥ 1 chars`
`widget_id`	`string \| null`	Vendor-side widget identifier.
`domains`	`string[]`	-
`embed_url`	`string`	Public vendor browser script URL. `format: uri`
`embed_snippet`	`string`	Copy-paste HTML snippet. `≥ 1 chars`
`dashboard_url`	`string \| null`	Vendor dashboard link for manual completion.
`message`	`string \| null`	Human-readable note (e.g. manual setup instructions).
`metadata`	`object \| null`	-
`error`	`string \| null`	-
`created_at`	`string`	- `format: date-time`

示例

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

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 GET https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
)
resp.raise_for_status()
print(resp.json())

javascript

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// Zero-install REST call — no SDK required (short-term the API is REST-only).
package main

import (
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

java

// Zero-install REST call — no SDK required (short-term the API is REST-only).
import java.net.URI;
import java.net.http.*;

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID"))
    .header("Authorization", "Bearer " + System.getenv("INFRAI_API_KEY"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

csharp

// Zero-install REST call — no SDK required (short-term the API is REST-only).
using System;
using System.Net.Http;

var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("GET"), "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID");
var key = Environment.GetEnvironmentVariable("INFRAI_API_KEY");
req.Headers.Add("Authorization", "Bearer " + key);
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

php

<?php
// Zero-install REST call — no SDK required (short-term the API is REST-only).
$ch = curl_init("https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("INFRAI_API_KEY"),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

ruby

# Zero-install REST call — no SDK required (short-term the API is REST-only).
require "net/http"
require "uri"

uri = URI("https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV['INFRAI_API_KEY']}"
res = http.request(req)
puts res.body

rust

// Zero-install REST call — no SDK required (short-term the API is REST-only). (uses the reqwest + tokio crates)
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let resp = reqwest::Client::new()
        .get("https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID")
        .header("Authorization", format!("Bearer {}", env::var("INFRAI_API_KEY")?))
        .send()
        .await?;
    println!("{}", resp.text().await?);
    Ok(())
}

高级:指定 vendor

默认情况下 infrai 会把每次调用智能路由到最佳可用供应商——无需自己挑选 vendor。作为高级逃生口,本能力支持可选的 vendor 入参以锁定某个供应商。本能力当前所有可用 vendor 可通过该能力 id 对应的 discovery 端点实时获取——参见 discovery API。

GET /v1/discovery/{capability}

captcha.verify

captcha.widget.create

captcha.widget.list

3. 全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

captcha.verifyPOST /v1/captcha/verify

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

参数 (10)

名称	类型	必填	说明
`widget_record_id`	`string`	必填	Infrai widget ID returned by captcha.widget.create; selects the exact vendor and server-side secret. `≥ 1 chars`
`token`	`string`	必填	One-time vendor response token from the client widget. `≥ 1 chars`
`vendor`	`string \| null`	可选	Optional consistency assertion; must match the widget vendor when provided.
`ip`	`string \| null`	可选	End-user IP for vendor-side risk scoring. Alias: `remoteip`.
`remoteip`	`string \| null`	可选	Alias of `ip` (module accepts both; `ip = ip or remoteip`).
`action`	`string \| null`	可选	Action name bound at challenge time; rejected if mismatched (anti cross-form replay).
`expected_hostname`	`string \| null`	可选	If set, token hostname must match.
`score_threshold`	`number \| null`	可选	Minimum acceptable score [0,1]; below → fail with low-score reason. `0–1`
`mode`	`"default_vendor" \| "verified_account"`	可选	Routing axis (CaptchaMode); orthogonal to widget_mode. `default: "default_vendor"`
`sitekey_label`	`string`	可选	Deprecated compatibility hint; widget_record_id selects the exact sitekey and secret. `default: "default"`

captcha.widget.createPOST /v1/captcha/widget/create

Create and manage a CAPTCHA widget through Infrai; returns the public sitekey and browser embed snippet while keeping the vendor secret server-side.

参数 (5)

名称	类型	必填	说明
`name`	`string`	必填	Human label; also the verify-time sitekey_label hint. `1–128 chars`
`domains`	`string[]`	可选	Allowed hostnames for this sitekey.
`vendor`	`"turnstile" \| null`	可选	Optional vendor pin. Widget provisioning currently supports Turnstile.
`mode`	`"default_vendor" \| "verified_account"`	可选	Routing axis (CaptchaMode). `default: "default_vendor"`
`widget_mode`	`"managed" \| "non-interactive" \| "invisible"`	可选	Vendor render axis (orthogonal to mode). `default: "managed"`

captcha.widget.getGET /v1/captcha/widget/get/{widget_record_id}

Get this account's CAPTCHA widget and public browser configuration.

参数 (1)

名称	类型	必填	说明
`widget_record_id`	`string`	必填	WidgetStore primary key.

captcha.widget.listGET /v1/captcha/widget/list

List this account's CAPTCHA widgets.

参数 (3)

名称	类型	必填	说明
`vendor`	`string \| null`	可选	Optional filter by vendor.
`cursor`	`string \| null`	可选	Opaque cursor from a previous page; null = first page.
`limit`	`integer`	可选	`1–1000default: 50`

4. 完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

单文件可运行 Python 程序(仅标准库、无 SDK):拷贝后填入 INFRAI_API_KEY 运行,即可按真实业务流逐步体验本模块核心 API——每一步都真实调用并计费,后续步骤复用前一步返回的真实字段。12 行 helper 就是全部集成代码。

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) captcha.widget.create — POST /v1/captcha/widget/create · Create and manage a CAPTCHA widget through Infrai; returns the public sitekey and browser embed snippet while keeping the vendor secret server-side.
r1 = show("captcha.widget.create", infrai("POST", "/v1/captcha/widget/create", {"name":"signup","domains":["app.example.com"],"widget_mode":"managed"}))

# 2) captcha.verify — POST /v1/captcha/verify · Verify a client-submitted CAPTCHA token against the vendor and return the success result; idempotent.
ask1 = input("Paste the one-time token returned by the browser widget: ").strip()
widget_record_id_2 = (r1.get("data") or {}).get("widget_record_id") or ""
r2 = show("captcha.verify", infrai("POST", "/v1/captcha/verify", {"widget_record_id":widget_record_id_2,"token":ask1,"ip":"203.0.113.5"}))

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

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

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at https://infrai.cc/login for a
#    project key + $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_..."   # from https://infrai.cc/login


# 2) captcha.verify
curl -X POST https://api.infrai.cc/v1/captcha/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"widget_record_id": "sample", "token": "sample"}'

# 3) captcha.widget.create
curl -X POST https://api.infrai.cc/v1/captcha/widget/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example"}'

# 4) captcha.widget.list
curl -X GET https://api.infrai.cc/v1/captcha/widget/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 5) captcha.widget.get
curl -X GET https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

# 1) Auth: every call is a raw HTTPS request carrying only your project key.
#    No SDK to install — just the `requests` library.
import os, requests

BASE = "https://api.infrai.cc"
HEADERS = {
    "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    "Content-Type": "application/json",
}


# 2) captcha.verify
# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/captcha/verify",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
    json={'widget_record_id': 'sample', 'token': 'sample'},
)
resp.raise_for_status()
print(resp.json())

# 3) captcha.widget.create
# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/captcha/widget/create",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
    json={'name': 'example'},
)
resp.raise_for_status()
print(resp.json())

# 4) captcha.widget.list
# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/captcha/widget/list",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
)
resp.raise_for_status()
print(resp.json())

# 5) captcha.widget.get
# Zero-install REST call — no SDK required (short-term the API is REST-only).
import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID",
    headers={
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    },
)
resp.raise_for_status()
print(resp.json())

javascript

// 1) Auth: every call is a raw HTTPS request carrying only your project key.
//    No SDK to install — just the built-in fetch().
const BASE = "https://api.infrai.cc";
const HEADERS = {
  "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
  "Content-Type": "application/json",
};


// 2) captcha.verify
// Browser prerequisite: fetch the public WidgetSetup from your server; never expose INFRAI_API_KEY.
const widget = await fetch("/captcha-config").then((r) => r.json());
const script = document.createElement("script");
script.src = widget.embed_url;
script.onload = () => turnstile.render("#captcha", {
  sitekey: widget.sitekey, action: "signup",
  callback: (token) => fetch("/signup", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token, widget_record_id: widget.widget_record_id }),
  }),
});
document.head.appendChild(script); // page contains <div id="captcha"></div>

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/verify",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"widget_record_id": "sample", "token": "sample"}),
  },
);
console.log(await resp.json());

// 3) captcha.widget.create
// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "example"}),
  },
);
console.log(await resp.json());

// Browser code (public values only; never expose INFRAI_API_KEY):
// Your server exposes only the public create response at /captcha-config.
const widget = await fetch("/captcha-config").then((r) => r.json());
const script = document.createElement("script");
script.src = widget.embed_url;
script.onload = () => turnstile.render("#captcha", {
  sitekey: widget.sitekey, action: "signup",
  callback: (token) => fetch("/signup", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ captcha_token: token, widget_record_id: widget.widget_record_id }),
  }),
});
document.head.appendChild(script); // page contains <div id="captcha"></div>

// 4) captcha.widget.list
// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

// 5) captcha.widget.get
// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

// 1) Auth: every call is a raw HTTPS request carrying only your project key.
//    No SDK to install — just the built-in fetch(), typed.
const BASE = "https://api.infrai.cc";
const HEADERS: Record<string, string> = {
  "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
  "Content-Type": "application/json",
};


// 2) captcha.verify
declare const turnstile: { render(selector: string, options: { sitekey: string; action: string; callback(token: string): void }): void };
// Browser prerequisite: fetch the public WidgetSetup from your server; never expose INFRAI_API_KEY.
const widget = await fetch("/captcha-config").then((r) => r.json());
const script = document.createElement("script");
script.src = widget.embed_url;
script.onload = () => turnstile.render("#captcha", {
  sitekey: widget.sitekey, action: "signup",
  callback: (token) => fetch("/signup", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token, widget_record_id: widget.widget_record_id }),
  }),
});
document.head.appendChild(script); // page contains <div id="captcha"></div>

// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/verify",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"widget_record_id": "sample", "token": "sample"}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 3) captcha.widget.create
// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "example"}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// Browser code (public values only; never expose INFRAI_API_KEY):
declare const turnstile: { render(selector: string, options: { sitekey: string; action: string; callback(token: string): void }): void };
// Your server exposes only the public create response at /captcha-config.
const widget = await fetch("/captcha-config").then((r) => r.json()) as { sitekey: string; embed_url: string; widget_record_id: string };
const script = document.createElement("script");
script.src = widget.embed_url;
script.onload = () => turnstile.render("#captcha", {
  sitekey: widget.sitekey, action: "signup",
  callback: (token) => { void fetch("/signup", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ captcha_token: token, widget_record_id: widget.widget_record_id }),
  }); },
});
document.head.appendChild(script); // page contains <div id="captcha"></div>

// 4) captcha.widget.list
// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 5) captcha.widget.get
// Zero-install REST call — no SDK required (short-term the API is REST-only).
const resp = await fetch(
  "https://api.infrai.cc/v1/captcha/widget/get/WIDGET_RECORD_ID",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

5. 开发者指南（英文）

从端点细节继续进入完整工作流、生产模式和基于实时 API 验证的故障排查指南。

验证码开发者指南