接口文档 · Captcha Service

Captcha Service

接口文档

把识别接进你的代码

这页写给要调用接口的人。识别请求用 X-API-Key 请求头鉴权，Key 在控制台「API Keys」页创建，只显示一次。

服务地址本机：http://127.0.0.1:8891

每次消耗成功识别扣 1 点；失败、超时、图片有误都不扣

同时请求账号与 Key 各有一层上限，默认账号 4、Key 2，超限返回 429

接口描述/openapi.json · /docs

识别字符型验证码

POST /v1/ocr，使用 multipart/form-data，图片放在 file 字段。

curl -X POST http://127.0.0.1:8891/v1/ocr \
  -H "X-API-Key: cap_xxxxxxxx" \
  -F "file=@captcha.png"

import requests

resp = requests.post(
    "http://127.0.0.1:8891/v1/ocr",
    headers={"X-API-Key": "cap_xxxxxxxx"},
    files={"file": open("captcha.png", "rb")},
    timeout=10,
)
data = resp.json()
print(data["text"], data["confidence"], data["points_charged"])

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("captcha.png")]), "captcha.png");
const resp = await fetch("http://127.0.0.1:8891/v1/ocr", {
  method: "POST",
  headers: { "X-API-Key": "cap_xxxxxxxx" },
  body: form,
});
const data = await resp.json();
console.log(data.text, data.confidence, data.points_charged);

识别正常时返回：

{
  "ok": true,
  "request_id": "c0a801...",
  "type": "ocr",
  "text": "AB12",
  "confidence": 0.9841,
  "elapsed_ms": 42.7,
  "provider": "local",
  "cost_points": 1,
  "points_charged": 1
}

定位滑块缺口

POST /v1/slide，字段 target 是滑块图，background 是背景图，可选 simple_target=true。返回的 x、y 是缺口在背景图中的位置。

curl -X POST http://127.0.0.1:8891/v1/slide \
  -H "X-API-Key: cap_xxxxxxxx" \
  -F "target=@target.png" \
  -F "background=@background.png"

import requests

resp = requests.post(
    "http://127.0.0.1:8891/v1/slide",
    headers={"X-API-Key": "cap_xxxxxxxx"},
    files={
        "target": open("target.png", "rb"),
        "background": open("background.png", "rb"),
    },
    timeout=10,
)
print(resp.json())

import fs from "node:fs";

const form = new FormData();
form.append("target", new Blob([fs.readFileSync("target.png")]), "target.png");
form.append("background", new Blob([fs.readFileSync("background.png")]), "background.png");
const resp = await fetch("http://127.0.0.1:8891/v1/slide", {
  method: "POST",
  headers: { "X-API-Key": "cap_xxxxxxxx" },
  body: form,
});
console.log(await resp.json());

查点数和调用记录

GET /v1/wallet这个 Key 所属账号还剩多少点、今天是否已签到

GET /v1/stats?limit=20最近的调用记录与扣点情况

GET /v1/quota兼容旧接口，返回的也是可用点数，不按月重置

GET /healthz服务是否正常，不需要鉴权

curl http://127.0.0.1:8891/v1/wallet -H "X-API-Key: cap_xxxxxxxx"

出错时怎么处理

HTTP	错误码	含义	你可以做什么
401	INVALID_API_KEY	没有带 API Key，或 Key 不正确	到「API Keys」页确认 Key；Key 只显示一次，遗失就重新创建
402	INSUFFICIENT_CREDITS	点数不够这次扣减	到「点数钱包」签到或输入兑换码，再重试
429	CONCURRENCY_LIMIT	账号或 Key 同时请求过多	等几百毫秒后重试，不要立刻重发
429	RATE_LIMITED	短时间内请求太密	降低频率，或把请求排队发送
429	FAILURE_LIMIT	近 1 小时失败次数过多	先检查图片质量和参数，隔一段时间再试
400	INVALID_IMAGE	图片打不开或为空	确认文件是完整图片后重新上传
413	IMAGE_TOO_LARGE	图片超过 2 MB	压缩或裁剪后重试
502	UPSTREAM_FAILED	这次没识别出结果	换一张更清晰的图片；本次不扣点
503	NO_PROVIDER_AVAILABLE	暂时没有可用的识别通道	稍后重试，或联系管理员

402 表示点数不够，429 表示请求太集中。前者去补点数，后者等一会儿再发。

点数从哪来

登录后每天可以在「点数钱包」签到一次，点数有有效期。
兑换码由管理员生成，输入后立即到账；过期、作废或次数用完会明确提示。
点数不按月重置，先到期的先扣。
API Key 不单独限制点数，所有 Key 共用账号里的点数；每个 Key 只限制同时请求数。

Captcha Service · 仅用于自有系统与已获授权的环境