图像匹配接口
提交文本描述和 6 张图片链接,返回最符合描述的 2 张图片。
POST
https://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())请求字段
| 位置 | 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| Header | Content-Type | string | 是 | 固定为 application/json |
| Header | X-API-Key | string | 是* | 客户 API Key;也可改用 Authorization: Bearer |
| Body | text | string | 是 | 图片匹配描述,去除首尾空格后长度 1-500 |
| Body | image_urls | string[] | 是 | 必须正好 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_id | string (UUID) | 本次调用标识,排查问题时请提供 |
selected_indices | integer[2] | 两个不重复的图片序号,范围 1-6 |
selected_image_urls | string[2] | 与返回序号对应的原始图片地址 |
quota.used | integer | 当日已使用次数,包含本次调用 |
quota.limit | integer | 当前套餐每日调用上限 |
quota.remaining | integer | 当日剩余调用次数 |
quota.resets_at | string (ISO 8601) | 配额下次重置时间,包含时区 |
错误码
除参数校验错误外,错误响应格式为 {"detail": "错误说明"}。
| HTTP 状态码 | 情况 | 处理建议 |
|---|---|---|
| 200 | 识别成功 | 读取响应中的两个图片序号或地址 |
| 401 | 缺少 API Key,或 Key 无效、已停用 | 检查认证请求头并联系管理员确认 Key 状态 |
| 403 | Key 已过期,或所属套餐已停用 | 联系管理员续期或调整套餐 |
| 422 | JSON、字段类型、文本长度或图片数量不符合要求 | 根据响应中的 detail[].loc 和 detail[].msg 修正参数 |
| 429 | 达到套餐当日调用上限 | 等待 Retry-After 指定秒数,或联系管理员升级套餐 |
| 502 | 上游识别服务异常或返回结果无效 | 稍后重试;持续发生时联系服务方 |
| 503 | 配额服务暂时不可用 | 稍后重试,建议使用指数退避 |
| 500 | 服务内部异常 | 稍后重试并向服务方提供发生时间 |
进入识别流程后即占用一次额度,上游识别失败的请求也会计入当日用量。
调用限额响应头
| 响应头 | 说明 |
|---|---|
X-RateLimit-Limit | 每日调用上限 |
X-RateLimit-Remaining | 当日剩余调用次数 |
X-RateLimit-Reset | 配额重置时间,Unix 时间戳(秒) |
Retry-After | 仅在 429 时返回,距离可重试的秒数 |