OCR API 文档

📌 服务概览

Base URLhttp://localhost:9898 请求方式HTTP POST 请求格式multipart/form-data | application/json | application/octet-stream 响应格式application/json; charset=utf-8 图片格式PNG / JPG / JPEG / GIF / BMP / WEBP 建议尺寸验证码类 ≤ 500×500,大图自动等比缩放 字符编码所有文本统一 UTF-8

接口目录

POST /ocr POST /ocr/old POST /det POST /slide/match POST /slide/compare

🔐 鉴权说明

所有识别接口必须携带 API Key,三种传递方式任选其一,优先级 Header > Query > Body。

方式	位置	示例
Header	请求头	`X-API-Key: YOUR_API_KEY`
Query	URL 参数	`?key=YOUR_API_KEY`
Body	JSON 字段	`{"key":"YOUR_API_KEY", ...}`

每个 Key 可设置剩余可用次数,次数耗尽返回 HTTP 402。请妥善保管,泄露请联系服务管理员重新签发。

📋 统一响应结构

所有接口响应均为 JSON,基本结构如下:

{
  "code": 0,           // 业务状态码,0 表示成功,其它表示失败
  "result": ...,      // 成功时返回的识别结果,类型因接口不同 (字符串 / 数组 / 对象)
  "msg": "..."        // 失败时的错误说明,成功时不返回
}

HTTP 状态码 / 错误码对照

HTTP	code	含义	排查建议
200	0	成功	读取 result 字段
400	400	缺少图片或参数错误	检查是否上传了图片、滑块接口是否同时传了 target 和 background
401	401	未携带 Key / Key 无效	检查 X-API-Key Header 或参数,确认 Key 拼写正确
402	402	Key 调用次数已耗尽	联系管理员追加次数
500	500	识别异常	查看 msg 字段,常见为图片损坏或格式不支持

📥 图片传递方式(通用)

下方所有接口的图片输入,都支持以下三种方式之一,优先级 file > image(JSON/form) > raw body:

① multipart/form-data(推荐)

Content-Type: multipart/form-data,以表单字段上传图片文件。单图接口字段名为 file,滑块接口为 target 和 background。

② JSON + base64

Content-Type: application/json,字段 image(或 img / base64)放 base64 字符串。支持 data:image/png;base64, 前缀,会自动剥离。

③ 原始二进制流

Content-Type: application/octet-stream,Body 直接放图片字节,key 通过 Header 或 Query 传。

🔍 接口详情

POST/ocr

通用文字 / 验证码识别。基于新版 ddddocr 模型,适用于英数混合验证码、中文文字、特殊符号等绝大多数场景。

请求参数

名称	类型	必填	说明
`key`	string	是	API Key,可通过 Header / Query / Body 任一方式传递
`file`	file (multipart)	否	图片文件,与 image / raw body 三选一
`image`	string (base64)	否	JSON 或 form 中的 base64 字符串;别名 `img` / `base64`;支持 data: URI 前缀
(原始 body)	binary	否	Content-Type 为 `application/octet-stream` 时,body 即图片字节

响应字段

字段	类型	说明
`code`	int	0 = 成功
`result`	string	识别出的文本内容,如 `"a8b3"`、`"你好"`;若图中无可识别字符,返回空字符串

成功响应示例

{
  "code": 0,
  "result": "a8b3k"
}

调用示例

# multipart 上传文件
curl -X POST "http://localhost:9898/ocr" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@captcha.png"

# JSON + base64
curl -X POST "http://localhost:9898/ocr" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY","image":"iVBORw0KGgoAAAA..."}'

import requests

with open("captcha.png", "rb") as f:
    r = requests.post(
        "http://localhost:9898/ocr",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"file": f},
        timeout=30,
    )
print(r.json()["result"])

const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

const fd = new FormData();
fd.append('file', fs.createReadStream('captcha.png'));
axios.post('http://localhost:9898/ocr', fd, {
  headers: { ...fd.getHeaders(), 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => console.log(r.data));

POST/ocr/old

使用 ddddocr 旧版模型识别。当新模型对特定样式验证码识别效果不佳时(例如某些扭曲较强的传统字符验证码),可改用此接口。参数与响应结构 完全同 /ocr。

请求参数

名称	类型	必填	说明
`key`	string	是	同 /ocr
`file` / `image` / raw	file / base64 / binary	三选一	图片输入,同 /ocr

调用示例

curl -X POST "http://localhost:9898/ocr/old" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@captcha.png"

POST/det

文字目标检测。返回图片中所有文字 / 字符所在的矩形区域(不识别内容),常用于点选式验证码(如"按顺序点击图中的'今天真好'")的字符定位。

请求参数

名称	类型	必填	说明
`key`	string	是	API Key
`file` / `image` / raw	file / base64 / binary	三选一	待检测图片

响应字段

字段	类型	说明
`code`	int	0 = 成功
`result`	array<[x1,y1,x2,y2]>	每个元素为一个文字框坐标 `[左上 x, 左上 y, 右下 x, 右下 y]`,单位为像素;未检出时返回空数组

成功响应示例

{
  "code": 0,
  "result": [
    [12, 34, 80, 96],
    [110, 40, 175, 100]
  ]
}

调用示例

curl -X POST "http://localhost:9898/det" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@click_captcha.png"

POST/slide/match

滑块缺口匹配。传入滑块小图 + 带缺口的背景图,返回缺口在背景图中的位置,可直接用于计算滑动距离。

请求参数

名称	类型	必填	说明
`key`	string	是	API Key
`target`	file / base64	是	滑块小图(被拖动的那块)
`background`	file / base64	是	背景大图(带缺口/凹槽的完整图)
`simple_target`	bool	否	默认 `false`。若小图已抠成纯净 PNG(无白边/无背景),设为 `true` 可获得更高精度

响应字段

字段	类型	说明
`code`	int	0 = 成功
`result.target`	[x1,y1,x2,y2]	缺口在背景图中的矩形坐标
`result.target_y`	int	缺口左上角 y 坐标(便于直接取用)

成功响应示例

{
  "code": 0,
  "result": {
    "target_y": 42,
    "target": [168, 42, 228, 102]
  }
}

滑动距离 = target[0] − 滑块在背景图中的初始 x 偏移(通常为左边距)。如有缩放,需按页面真实显示比例换算。

调用示例

curl -X POST "http://localhost:9898/slide/match" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target=@slider.png" \
  -F "background=@bg.png" \
  -F "simple_target=false"

POST/slide/compare

坑位识别(图像对比定位)。传入带阴影坑位的图 + 完整原图,通过逐像素对比定位坑位中心点。适用于阴影型滑块、找不同等场景。

请求参数

名称	类型	必填	说明
`key`	string	是	API Key
`target`	file / base64	是	带坑位/阴影的图(差异图)
`background`	file / base64	是	完整背景原图(无坑位)

两张图尺寸必须完全一致,否则返回 500。

响应字段

字段	类型	说明
`code`	int	0 = 成功
`result.x`	int	坑位区域左上角 x 坐标
`result.y`	int	坑位区域左上角 y 坐标

成功响应示例

{
  "code": 0,
  "result": { "x": 172, "y": 46 }
}

调用示例

curl -X POST "http://localhost:9898/slide/compare" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target=@with_gap.png" \
  -F "background=@full_bg.png"

❓ 常见问题

识别结果为空? 检查图片是否过小或对比度不足;可尝试 /ocr/old。
返回 401? 确认 Key 是否正确,Header 名为 X-API-Key(大小写不敏感,但拼写要对)。
返回 402? 当前 Key 配额耗尽,请联系管理员追加次数。
滑块结果不准? 确保上传的滑块图和背景图使用原始分辨率,前端如有缩放需按比例还原坐标。
支持批量? 单次请求只处理一张图,如需批量请并发调用。