验证码

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

概览

基础路径: 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"

方法

captcha.verify

POST /v1/captcha/verify

校验来自浏览器的验证码令牌。

参数

名称	类型	必填	说明
`token`	`string`	必填	验证码控件返回的令牌。
`vendor`	`"hcaptcha" \| "recaptcha" \| "turnstile" \| "infrai"`	可选	固定使用某个供应商，而非自动路由。
`remote_ip`	`string`	可选	用于风险评分的客户端 IP。
`min_score`	`number`	可选	可接受的最低分（基于分数的供应商）。

CaptchaVerifyResult { valid, score?, vendor, hostname?, action? }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/captcha/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "<client-captcha-token>", "remoteip": "203.0.113.5"}'

captcha.widget.create

POST /v1/captcha/widget/create

发放验证码控件代码段与脚本 URL。

参数

名称	类型	必填	说明
`vendor`	`string`	可选	固定使用某个供应商，而非自动路由。
`site_key_id`	`string`	可选	已配置的 site-key id。

{ html, script_url }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/captcha/widget/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendor": "turnstile", "sitekey_label": "checkout"}'

captcha.widget.get

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

按记录 ID 获取单个验证码组件，返回 sitekey、secret 句柄、域名与 provisioning 状态。

参数

名称	类型	必填	说明
`widget_record_id`	`string`	必填	WidgetStore 主键。

WidgetSetup { widget_record_id, name, vendor, status, sitekey?, domains, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

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

captcha.widget.list

GET /v1/captcha/widget/list

游标分页列出账户下的验证码组件，可选按 vendor 过滤。

参数

名称	类型	必填	说明
`vendor`	`string`	可选	可选，按 vendor 过滤。
`cursor`	`string`	可选	上一页返回的不透明游标；null 表示第一页。
`limit`	`number`	可选	每页条数，1–1000，默认 50。

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

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

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

captcha.widget.update

PATCH /v1/captcha/widget/update/{widget_record_id}

更新组件的域名白名单或渲染模式。仅 Cloudflare 支持 PATCH，其它 vendor 返回 status=manual_setup_required。

参数

名称	类型	必填	说明
`widget_record_id`	`string`	必填	WidgetStore 主键。
`domains`	`string[]`	可选	替换后的域名白名单。
`widget_mode`	`"managed" \| "non-interactive" \| "invisible"`	可选	vendor 渲染轴（managed/non-interactive/invisible）；不传表示不变。
`idempotency_key`	`string`	可选	标准写幂等键；重复请求返回 IDEMPOTENCY_KEY_CONFLICT。

WidgetSetup { widget_record_id, name, vendor, status, domains, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X PATCH https://api.infrai.cc/v1/captcha/widget/update/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"widget_record_id": "..."}'

captcha.widget.rotate

POST /v1/captcha/widget/rotate/{widget_record_id}

轮换组件密钥：通过 vendor 管理 API 重新置备并切换 secret。无通用 vendor 轮换 API（recaptcha 始终手动），不支持时返回 status=manual_setup_required。

参数

名称	类型	必填	说明
`widget_record_id`	`string`	必填	WidgetStore 主键。
`idempotency_key`	`string`	可选	标准写幂等键；重复请求返回 IDEMPOTENCY_KEY_CONFLICT。

WidgetSetup { widget_record_id, name, vendor, status, secret_handle?, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/captcha/widget/rotate/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"widget_record_id": "..."}'

captcha.widget.delete

DELETE /v1/captcha/widget/delete/{widget_record_id}

退役一个 sitekey 组件。仅 Cloudflare 支持 DELETE，其它 vendor 仅从存储移除并返回 status=manual_setup_required。

参数

名称	类型	必填	说明
`widget_record_id`	`string`	必填	WidgetStore 主键。
`idempotency_key`	`string`	可选	标准写幂等键；重复请求返回 IDEMPOTENCY_KEY_CONFLICT。

WidgetDeleteResult { widget_record_id, status, message? }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/captcha/widget/delete/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

captcha.stats.get

GET /v1/captcha/stats/get

获取一段窗口内的验证码聚合统计（总数/通过/失败/机器人信号数/平均分）。为近实时进程内计数，since/until 为非权威建议值。

参数

名称	类型	必填	说明
`sitekey_label`	`string`	可选	限定到单个 sitekey；null 表示跨全部聚合。
`since`	`string`	可选	建议的窗口起点（date-time）。
`until`	`string`	可选	建议的窗口终点（date-time）。

CaptchaStats { since, until, total, pass, fail, bot_signal_count, avg_score? }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/captcha/stats/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

全部能力

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

能力	端点	说明
`captcha.stats.get`	`GET /v1/captcha/stats/get`	Get near-real-time aggregate CAPTCHA stats over a window (total, passed, failed, average score).
`captcha.verify`	`POST /v1/captcha/verify`	Verify a client-submitted CAPTCHA token against the vendor and return the success result; idempotent.
`captcha.widget.create`	`POST /v1/captcha/widget/create`	Create a CAPTCHA widget (sitekey) for a vendor with allowed domains and render mode; idempotent.
`captcha.widget.delete`	`DELETE /v1/captcha/widget/delete/{widget_record_id}`	Retire a sitekey widget (DELETE supported on Cloudflare only; other vendors return manual_setup_required).
`captcha.widget.get`	`GET /v1/captcha/widget/get/{widget_record_id}`	Get one CAPTCHA widget by record ID (sitekey, secret handle, provisioning status).
`captcha.widget.list`	`GET /v1/captcha/widget/list`	List the account's CAPTCHA widgets with cursor pagination, optionally filtered by vendor.
`captcha.widget.rotate`	`POST /v1/captcha/widget/rotate/{widget_record_id}`	Rotate a widget's secret (re-provision at the vendor and swap; manual_setup_required if unsupported).
`captcha.widget.update`	`PATCH /v1/captcha/widget/update/{widget_record_id}`	Update a widget's allowed domains or render mode (Cloudflare only; others return manual_setup_required).

完整示例

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

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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 the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 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 '{"token": "<client-captcha-token>", "remoteip": "203.0.113.5"}'

# 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 '{"vendor": "turnstile", "sitekey_label": "checkout"}'

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

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

# 6) captcha.widget.update
curl -X PATCH https://api.infrai.cc/v1/captcha/widget/update/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"widget_record_id": "..."}'

# 7) captcha.widget.rotate
curl -X POST https://api.infrai.cc/v1/captcha/widget/rotate/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"widget_record_id": "..."}'

# 8) captcha.widget.delete
curl -X DELETE https://api.infrai.cc/v1/captcha/widget/delete/WIDGET_RECORD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"