Captcha API 开发文档API v1

图像匹配接口

提交文本描述和 6 张图片链接,返回最符合描述的 2 张图片。

POSThttps://captcha.onefeng.xyz/v1/recognize

认证

推荐在请求头中传入管理员分配的 API Key:

X-API-Key: cap_live_xxx

也可以使用 Bearer 认证:

Authorization: Bearer cap_live_xxx

调用示例

curl

curl --request POST 'https://captcha.onefeng.xyz/v1/recognize' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: cap_live_xxx' \
  --data '{
    "text": "有可以发光的物品",
    "image_urls": [
      "https://example.com/1.png",
      "https://example.com/2.png",
      "https://example.com/3.png",
      "https://example.com/4.png",
      "https://example.com/5.png",
      "https://example.com/6.png"
    ]
  }'

Python

import requests

endpoint = "https://captcha.onefeng.xyz/v1/recognize"
payload = {
    "text": "有可以发光的物品",
    "image_urls": [
        "https://example.com/1.png",
        "https://example.com/2.png",
        "https://example.com/3.png",
        "https://example.com/4.png",
        "https://example.com/5.png",
        "https://example.com/6.png",
    ],
}

response = requests.post(
    endpoint,
    headers={"X-API-Key": "cap_live_xxx"},
    json=payload,
    timeout=90,
)
print(response.status_code, response.json())

请求字段

位置字段类型必填说明
HeaderContent-Typestring固定为 application/json
HeaderX-API-Keystring是*客户 API Key;也可改用 Authorization: Bearer
Bodytextstring图片匹配描述,去除首尾空格后长度 1-500
Bodyimage_urlsstring[]必须正好 6 个 HTTP 或 HTTPS 图片地址,顺序对应序号 1-6

成功响应

{
  "request_id": "47aef27b-c915-4c64-8cff-4bfb1e87a18e",
  "selected_indices": [2, 5],
  "selected_image_urls": [
    "https://example.com/2.png",
    "https://example.com/5.png"
  ],
  "quota": {
    "used": 1,
    "limit": 3000,
    "remaining": 2999,
    "resets_at": "2026-08-26T00:00:00+08:00"
  }
}
字段类型说明
request_idstring (UUID)本次调用标识,排查问题时请提供
selected_indicesinteger[2]两个不重复的图片序号,范围 1-6
selected_image_urlsstring[2]与返回序号对应的原始图片地址
quota.usedinteger当日已使用次数,包含本次调用
quota.limitinteger当前套餐每日调用上限
quota.remaininginteger当日剩余调用次数
quota.resets_atstring (ISO 8601)配额下次重置时间,包含时区

错误码

除参数校验错误外,错误响应格式为 {"detail": "错误说明"}

HTTP 状态码情况处理建议
200识别成功读取响应中的两个图片序号或地址
401缺少 API Key,或 Key 无效、已停用检查认证请求头并联系管理员确认 Key 状态
403Key 已过期,或所属套餐已停用联系管理员续期或调整套餐
422JSON、字段类型、文本长度或图片数量不符合要求根据响应中的 detail[].locdetail[].msg 修正参数
429达到套餐当日调用上限等待 Retry-After 指定秒数,或联系管理员升级套餐
502上游识别服务异常或返回结果无效稍后重试;持续发生时联系服务方
503配额服务暂时不可用稍后重试,建议使用指数退避
500服务内部异常稍后重试并向服务方提供发生时间
进入识别流程后即占用一次额度,上游识别失败的请求也会计入当日用量。

调用限额响应头

响应头说明
X-RateLimit-Limit每日调用上限
X-RateLimit-Remaining当日剩余调用次数
X-RateLimit-Reset配额重置时间,Unix 时间戳(秒)
Retry-After仅在 429 时返回,距离可重试的秒数