注意事项

1、正常状态下，识别API每24小时最多请求80次，无论是否正常返回识别结果。

2、超过限定调用次数后，将进入限流状态。此时将只返回错误信息，提示恢复时间，不返回识别结果。

3、在限流状态下，发起任何调用都会大幅延长恢复时间，因此使用者务必重视恢复时间提示，避免持续无效调用给使用体验造成严重负面影响。

1. 识别

1.1 调用方法
URL:
https://ocr.gj.cool/recog
Method:
POST
Headers:
无特殊设定
Body:
字段 是否必选 格式 说明
img 是 form-data

MIME: image/jpeg, image/png, image/tiff。如果MIME跟文件扩展名不一致，则以MIME为准。

体积不得超过4MB。
mode 否 form-data、x-www-form-urlencoded

识别模式。若不作特意设置，则取默认值0。

0：字识别，1：列识别。
coor 否 form-data、x-www-form-urlencoded

坐标。若不作特意设定或者设置为"[]"，则默认将全图视作一个单字或单列区域进行识别。

字识别模式下（mode=0），格式："[[a1,b1,c1,d1], [a2,b2,c2,d2], ...]"。a1,b1,c1,d1分别代表是单字区域左边界、上边界、右边界、下边界的像素值，都是整数，用","间隔，外部用"[]"包围。各单字区域用","间隔，最外层用"[]"包围。

列识别模式下（mode=1），格式："[[Ax,Ay,Bx,By,Cx,Cy,Dx,Dy], ...]"。Ax,Ay,Bx,By,Cx,Cy,Dx,Dy分别代表单列区域四个顶点的x、y坐标，都是整数，用","间隔，外部用"[]"包围。各单列区域用","间隔，最外层用"[]"包围。
topk 否 form-data、x-www-form-urlencoded

置信度最大的前k项。仅对字识别模式（mode=0）生效。

整数，取值范围是1-10。若不作特意设置，则取默认值1。
正常返回:
JSON
字段 含义 格式
chars 汉字

字识别模式下（mode=0），返回结果为列表，数据项为单字识别结果，之间用","分隔，格式：[[单字识别结果], [单字识别结果], ...]，个数与coor个数一致。单字识别结果为字符串列表，数据项代表当前单字的top-k候选项，用","分隔，格式：[t1, t2, ..., tk]。其中，t1, t2, ..., tk等代表top-k候选项。

列识别模式下（mode=1），返回结果为列表，数据项为单列识别结果，之间用","分隔，格式：[[单列识别结果], [单列识别结果], ...]，个数与coor个数一致。单列识别结果为字符串列表，数据项代表各单字的top-1，用","分隔，格式：[a1, b1, c1, d1, ...]。其中a1, b1, c1, d1等代表各单字的top1。
char_probs 置信度

字识别模式下（mode=0），返回结果为列表，数据项为单字识别概率，之间用","分隔，格式：[[单字识别概率], [单字识别概率], ...]，个数与coor的区域个数一致。单字识别概率为小数列表，数据项代表单字的top-k候选项的识别概率，用","分隔，格式：[p1, p2, ..., pk]。其中，p1, p2, ..., pk代表top-k候选项的识别概率。

列识别模式下（mode=1），返回结果为列表，数据项为单列识别概率，之间用","分隔，格式：[[单列识别概率], [单列识别概率], ...]，个数与coor的区域个数一致。单列识别概率为小数列表，数据项代表各单字top-1的识别概率，用","分隔，格式：[p1, p2, ...]。其中p1, p2, ...代表各单字的top-1的识别概率。
异常返回:
JSON
字段 含义 格式
msg 错误类型

img体积超过限定值，返回值为 "File size too large" 。

img格式不支持，返回值为 "Image format wrong" 。

其他img设置错误，返回值为 "img wrong" 。

mode设置错误，返回值为 "mode wrong" 。

coor设置错误，返回值为 "coor wrong" 。

topk设置错误，返回值为 "topk wrong" 。

识别结果为空，返回值为 "recog void" 。

识别失败，返回值为 "recog failed" 。

超过限流设定，返回值为 "Retry after least **** seconds." 。
code 状态码

整数。部分错误类型会同时返回状态码。
1.2 curl示例

提示：

1、以上命令行适用于Linux、macOS系统。使用时请将“/home/abc/1.png”替换为实际的文件路径。

2、Windows系统，使用时请将“/home/abc/1.png”替换为类似“C:\abc\1.png”格式的文件路径。

3、当坐标较长时，建议使用form-data。
类型 命令
单字 curl -X POST 'https://ocr.gj.cool/recog' -F 'img=@"/home/abc/1.png"'
单列 curl -X POST 'https://ocr.gj.cool/recog' -F 'img=@"/home/abc/1.png"' -F 'mode=1'
或：curl -X POST 'https://ocr.gj.cool/recog?mode=1' -F 'img=@"/home/abc/1.png"'
多字 curl -X POST 'https://ocr.gj.cool/recog' -F 'img=@"/home/abc/1.png"' -F 'coor="[[82,8,196,137],[64,44,208,164]]"'
或：curl -g -X POST 'https://ocr.gj.cool/recog?coor=[[82,8,196,137],[64,44,208,164]]' -F 'img=@"/home/abc/1.png"'
多列 curl -X POST 'https://ocr.gj.cool/recog' -F 'img=@"/home/abc/1.png"' -F 'mode=1' -F 'coor="[[2373,2116,2382,1108,2496,1108,2514,2116],[2448,2947,2436,2153,2544,2153,2559,2947]]"'
或：curl -g -X POST 'https://ocr.gj.cool/recog?mode=1&coor=[[2373,2116,2382,1108,2496,1108,2514,2116],[2448,2947,2436,2153,2544,2153,2559,2947]]' -F 'img=@"/home/abc/1.png"'
1.3 Postman示例: 多列识别
Responsive image

注意：这里的img应设为File类型，mode、coor应设为Text类型。

2. 检测

2.1 调用方法
URL:
https://ocr.gj.cool/detect
Method:
POST
Headers:
无特殊设定
Body:
字段 是否必选 格式 说明
img 是 form-data

MIME: image/jpeg, image/png, image/tiff。如果MIME跟文件扩展名不一致，则以MIME为准。

体积不得超过4MB。
topk 否 form-data、x-www-form-urlencoded

置信度最大的前k项。

整数，取值范围是1-10。若不作特意设置，则取默认值1。
正常返回:
JSON
字段 含义 格式
coors 单字区域坐标

列表。数据项之间用","分隔，格式：[[单字区域坐标], [单字区域坐标], ...]。单字区域坐标为整数列表，格式：[x1,y1,x2,y2]。其中，x1,y1,x2,y2分别代表单字区域的左边界、上边界、右边界和下边界。
coor_probs 单字区域置信度

小数列表。数据项之间用","分隔，格式：[a, b, c, d, ...]，数量与coors的数据项一致。
chars 单字识别结果

列表。数据项之间用","分隔，格式：[[单字识别结果], [单字识别结果], ...]，数量与coors的数据项一致。单字识别结果为字符串列表，数据项之间用","分隔，格式：[t1, t2, ..., tk]。其中，t1, t2, ..., tk等代表top-k候选项。
char_probs 单字识别置信度

列表。数据项之间用","分隔，格式：[[单字识别概率], [单字识别概率], ...]，数量与coors的数据项一致。单字识别概率为小数列表，数据项之间用","分隔，格式：[p1, p2, ..., pk]。其中，p1, p2, ..., pk代表top-k候选项的识别概率。
异常返回:
JSON
字段 含义 格式
msg 错误类型

img体积超过限定值，返回值为 "File size too large" 。

img格式不支持，返回值为 "Image format wrong" 。

其他img设置错误，返回值为 "img wrong" 。

topk设置错误，返回值为 "topk wrong" 。

检测结果为空，返回值为 "detect void" 。

检测失败，返回值为 "detect failed" 。

超过限流设定，返回值为 "Retry after least **** seconds." 。
code 状态码

整数。部分错误类型会同时返回状态码。
2.2 curl示例

提示：

1、以上命令行适用于Linux、macOS系统。使用时请将“/home/abc/1.png”替换为实际的文件路径。

2、Windows系统，使用时请将“/home/abc/1.png”替换为类似“C:\abc\1.png”格式的文件路径。
类型 命令
检测 curl -X POST 'https://ocr.gj.cool/detect' -F 'img=@"/home/abc/1.png"'
检测后识别 curl -X POST 'https://ocr.gj.cool/detect' -F 'img=@"/home/abc/1.png"' -F 'topk=1'
或：curl -X POST 'https://ocr.gj.cool/detect?topk=1' -F 'img=@"/home/abc/1.png"'
2.3 Postman示例: 检测后识别
Responsive image

注意：这里的img应设为File类型，topk应设为Text类型。

以下各项API仅面向正式授权用户

使用方式

1、首先访问ocr_login（授权），获取access_token和refresh_token。

2、然后凭借尚未过期的access_token访问ocr_pro、ocr_line_recog、ocr_enhance_detect等服务。

3、如果access_token过期，则凭借尚未过期的refresh_token访问ocr_refresh（刷新），获取新的access_token。

4、如果refresh_token过期，则根据方式1，获取新的refresh_token。

注意事项

1、调用ocr_refresh、ocr_pro、ocr_line_recog、ocr_enhance_detect等服务时，access_token(或refresh_token)应该放在请求的Headers（注意：不是Body）的Authorization 。格式为"gjcool <token>"。其中，<token>代表access_token(或refresh_token)，与"gjcool"之间用一个空格分开。

2、对于初始等级的用户，ocr_pro、ocr_line_recog、ocr_enhance_detect等服务采取动态流量限定策略：连续24小时内成功请求的动态计数不高于1000次。发起请求时，成功请求消耗一个动态计数，失败请求不消耗动态计数；不发生请求时，动态计数以每24小时1000次的速率恢复。如果需要提高动态计数上限和恢复速率，可以申请提升用户等级。

3、ocr_pro、ocr_line_recog、ocr_enhance_detect等服务两次请求之间应当至少间隔5秒以上，否则将返回错误信息。

1. 授权

URL:
https://ocr.gj.cool/ocr_login
Method:
POST
Headers:
无特殊设定
Body:
字段 是否必选 格式 说明
apiid 是 form-data 使用授权服务的唯一用户标识。可从账户页面获取。
password 是 form-data 密码
encrypt 否 form-data

0：password字段使用明文格式；

1：password字段使用加密格式。

加密步骤：(1)密码明文用UTF-8编码；(2)利用公钥加密；(3)加密后的密文再用base64编码。

若不作特意设定，则取默认值0。使用密码加密功能，需申请公钥。
返回格式:
JSON
字段 含义 格式
access_token 用于授权服务的鉴权。过期时间为60分钟 JSON Web Token
refresh_token 用于刷新access token。过期时间为7天 JSON Web Token
msg 错误类型

apiid或password校验错误，返回值为 "Bad request"

非正式授权用户或用户授权过期，返回值为 "User blocked"

encrypt设置错误，返回值为 "encrypt wrong"

密文解密失败，返回值为 "Decrypt failed"

其他密码相关错误，返回值为 "password wrong"

以上为常见错误类型，其他错误类型恕不赘述。

2. 刷新access token

URL:
https://ocr.gj.cool/ocr_refresh
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <refresh_token> "gjcool"与refresh_token之间用一个空格连接
Body:
无特殊设定
返回格式:
JSON
字段 含义 格式
access_token 用于授权服务的鉴权。过期时间为60分钟。 JSON Web Token
msg 错误类型

refresh_token过期，返回值为 "Token has expired"

以上为常见错误类型，其他错误类型恕不赘述。

3. 自动识别

URL:
https://ocr.gj.cool/ocr_pro
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
img 是 form-data MIME: image/jpeg, image/png, image/tiff。如果MIME跟文件扩展名不一致，则以MIME为准。体积不得超过4MB。
layout 否 form-data

0：竖版，文字方向从上至下，行排列方向从右至左，适用于绝大多数古籍图像；

1：横版，文字方向从左至右，行排列方向从上至下，适用于现代出版物。

若不作特意设定，则取默认值0。
area 否 form-data

若不作特意设定或者设置为"[]"，则默认针对全图进行识别，适合于大多数简单版式的情况。

针对复杂版式，可以通过设置此字段，针对图片中的若干区域依次识别。

字符串，格式："[[a1,b1,c1,d1],[a2,b2,c2,d2]]"。a1、b1、c1、d1分别代表单个区域的左边界、上边界、右边界、下边界的像素值，都是整数，用","间隔，外部用"[]"包围。各个区域用","间隔，最外层用"[]"包围。
正常返回:
JSON
字段 含义 格式
FileName 图片的文件名（不含扩展名） 字符串。
CharNumber 总字数 整数。
LineNumber 总行数 整数。
Width 图片宽度的像素值 整数。
Height 图片高度的像素值 整数。
chars 单字识别结果 列表。数据项为长度为1的字符串。数据项个数与总字数一致。
coors 单字坐标 列表。数据项为[x1,y1,x2,y2]，分别代表字框的左边界、上边界、右边界、下边界的像素值，都是整数。数据项个数与总字数一致。
char_probs 单字识别结果的置信度 列表。数据项为四位小数。数据项个数与总字数一致。
coor_probs 单字坐标的置信度 列表。数据项为四位小数。数据项个数与总字数一致。
char_ids 单字的序号 列表。数据项为整数。数据项个数与总字数一致。
line_ids 单字所在行的序号 列表。数据项为整数。数据项个数与总字数一致。
异常返回:
JSON
字段 含义 格式
msg 错误类型

img体积超过限定值，返回值为 "File size too large" 。

img格式不支持，返回值为 "Image format wrong" 。

其他img设置错误，返回值为 "img wrong" 。

layout设置错误，返回值为 "layout wrong" 。

area设置错误，返回值为 "area wrong" 。

OCR失败，返回值为 "OCR failed" 。

当前请求超过24小时限量，返回值为 "Retry ****** seconds later" 。

请求间隔过短，返回值为 "Request too frequent"。

非正式授权用户或用户授权过期，返回值为 "User blocked" 。

access_token过期，返回值为 "Token has expired" 。

以上为常见错误类型，其他错误类型恕不赘述。
code 状态码

整数。部分错误类型会同时返回状态码。

4. 列识别

URL:
https://ocr.gj.cool/ocr_line_recog
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
img 是 form-data MIME: image/jpeg, image/png, image/tiff。如果MIME跟文件扩展名不一致，则以MIME为准。体积不得超过4MB。
area 否 form-data

字符串，格式："[[a1,b1,c1,d1],[a2,b2,c2,d2]]"。a1、b1、c1、d1分别代表单列的左边界、上边界、右边界、下边界的像素值，都是整数，用","间隔，外部用"[]"包围。各列用","间隔，最外层用"[]"包围。

若不作特意设定或者设置为"[]"，则默认将全图视作单列。
正常返回：
JSON。格式为：[{数据项},{数据项}]。数据项之间用","分隔，数据项的数量与area的数量一致。
数据项的字段说明:
字段 含义 格式
line_ids 列序号 整数。
line_coors 列坐标 格式：[x1,y1,x2,y2]，分别代表列的左边界、上边界、右边界、下边界的像素值，都是整数。一般情况下，与参数area的对应列坐标一致。
line_chars 识别结果 列表，数据项为单字识别结果，之间用","分隔，格式：[[识别结果], [识别结果], [识别结果]]。识别结果的格式为字符串列表，数据项代表识别结果的候选项，之间用","分隔，格式：[a, b, c, d]。其中a, b, c, d代表各候选项。个数不固定，取决于前top-k的概率和是否足够接近1。
line_char_probs 识别概率 列表，数据项为单字识别概率，之间用","分隔。格式：[[识别概率],[识别概率],[识别概率]]。识别概率的格式为小数列表，数据项代表识别结果候选项的识别概率，之间用","分隔，格式：[a, b, c, d]。其中a, b, c, d代表各候选项的识别概率。个数不固定，取决于前top-k的概率和是否足够接近1。
异常返回:
JSON
字段 含义 格式
msg 错误类型

img体积超过限定值，返回值为 "File size too large" 。

img格式不支持，返回值为 "Image format wrong" 。

其他img设置错误，返回值为 "img wrong" 。

area设置错误，返回值为 "area wrong" 。

识别失败，返回值为 "Line Recog failed" 。

当前请求超过24小时限量，返回值为 "Retry ****** seconds later" 。

请求间隔过短，返回值为 "Request too frequent" 。

非正式授权用户或用户授权过期，返回值为 "User blocked" 。

access_token过期，返回值为 "Token has expired" 。

以上为常见错误类型，其他错误类型恕不赘述。
code 状态码

整数。部分错误类型会同时返回状态码。

5. 增强型检测

URL:
https://ocr.gj.cool/ocr_enhance_detect
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
img 是 form-data MIME: image/jpeg, image/png, image/tiff。如果MIME跟文件扩展名不一致，则以MIME为准。体积不得超过4MB。
正常返回：
JSON。格式为：[{数据项},{数据项}]，数据项之间用","分隔。每个数据项代表一个单字检测结果。
数据项的字段说明:
字段 含义 格式
chars 单字识别结果 字符串列表。格式：[a, b, c, d]。其中a, b, c, d代表各候选项，之间用","分隔。个数不固定，取决于前top-k的概率和是否足够接近1。
char_probs 单字识别概率 小数列表。格式：[a, b, c, d]。其中a, b, c, d代表各候选项的识别概率，之间用","分隔。个数不固定，取决于前top-k的概率和是否足够接近1。
coors 单字坐标 格式：[x1, y1, x2, y2]，分别代表单字坐标的左边界、上边界、右边界、下边界的像素值，都是整数。
coors_probs 单字检测概率 小数，最多保留小数点后四位。
异常返回:
JSON
字段 含义 格式
msg 错误类型

img体积超过限定值，返回值为 "File size too large" 。

img格式不支持，返回值为 "Image format wrong" 。

其他img设置错误，返回值为 "img wrong" 。

检测失败，返回值为 "Detect failed" 。

当前请求超过24小时限量，返回值为 "Retry ****** seconds later" 。

请求间隔过短，返回值为 "Request too frequent" 。

非正式授权用户或用户授权过期，返回值为 "User blocked" 。

access_token过期，返回值为 "Token has expired" 。

以上为常见错误类型，其他错误类型恕不赘述。
code 状态码

整数。部分错误类型会同时返回状态码。

6. 查询动态计数余额和上限

URL:
https://ocr.gj.cool/ocr_balance
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
无特殊设定
返回格式:
json
字段 含义 格式
balance 动态计数余额

整数
maximums 动态计数上限

整数
msg 错误类型

请求间隔过短，返回值为 "Request too frequent"

非正式授权用户或用户授权过期，返回值为 "User blocked"

access_token过期，返回值为 "Token has expired"

以上为常见错误类型，其他错误类型恕不赘述。
1. 调用方法
URL:
https://punct.gj.cool/punct/test
Method:
POST
Headers:
Content-Type: application/json
参数:
字段 是否必选 内容 格式
src 是 待标点的文本 [{"src":"文本内容"}]
返回格式:
json
字段 内容 格式
pred_sent 标点后的文本

[{"pred_sent": "返回结果"}]

2. curl示例
提示：以上命令行适用于Linux、macOS系统。使用时请将“文本内容”替换为实际文本。
类型 命令
请求 curl -X POST 'https://punct.gj.cool/punct/test' -d '[{"src":"文本内容"}]'
返回 [{"pred_sent": "返回结果"}]
3. Postman示例
Responsive image