注意事项

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。

正常返回:
application/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的识别概率。

异常返回:
application/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。

正常返回:
application/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候选项的识别概率。

异常返回:
application/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访问自动识别、自动标点、文白翻译等服务。

3、如果access_token过期,则凭借尚未过期的refresh_token访问ocr_refresh(刷新),获取新的access_token。

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

注意事项

1、access_token(或refresh_token)应该始终放在请求的HeadersAuthorization 字段。格式为"gjcool <token>"。其中,<token>代表access_token(或refresh_token),与"gjcool"之间用一个空格分开。

1. 认证类API

1.1 授权

URL:
https://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。使用密码加密功能,需申请公钥。

正常返回:
application/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"

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

1.2 刷新access token

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

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

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

2. 图像类API

2.1 自动识别

URL:
https://api.jzd.cool:<端口号>/ocr_pro
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
1111
字段 是否必选 格式 说明
img form-data 图片。file。MIME: image/jpeg, image/png, image/tiff, image/webp, image/heic, image/heif, image/jp2。体积不得超过40MB。
layout form-data

版式。整数。取值范围: 0, 1。

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

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

若不作特意设定,则取默认值0。

area form-data

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

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

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

compact form-data

密集系数。整数。取值范围: 1, 2, 4, 6。

数值大于1时,可以改善密集文字的识别效果,但会消耗等值的使用次数。

若不作特意设定,则取默认值1。

正常返回:
application/json
字段 含义 格式
FileName 图片的文件名(不含扩展名) 字符串。
CharNumber 总字数 整数。
LineNumber 总行数 整数。
Width 图片宽度的像素值 整数。
Height 图片高度的像素值 整数。
chars 单字识别结果 列表。数据项为长度为1的字符串。数据项个数与总字数一致。
coors 单字坐标 列表。数据项为[x1,y1,x2,y2],分别代表字框的左边界、上边界、右边界、下边界的像素值,都是整数。数据项个数与总字数一致。
char_probs 单字识别结果的置信度 列表。数据项为四位小数。数据项个数与总字数一致。
coor_probs 单字坐标的置信度 列表。数据项为四位小数。数据项个数与总字数一致。
char_ids 单字的序号 列表。数据项为整数。数据项个数与总字数一致。
line_ids 单字所在行的序号 列表。数据项为整数。数据项个数与总字数一致。
异常返回:
application/json
字段 含义 格式
msg 错误类型

1. 设置错误

"image size too large": img体积超过限定值。

"image format wrong": img格式不支持。

"img wrong": img错误。

"img read failed": img读取错误。

"heic/heif failed": img heic/heif读取错误。

"layout wrong": layout错误。

"area wrong": area错误。

"image height or width wrong": img的高度或宽度错误。

"compact wrong": compact错误。

2. 执行错误

"OCR failed": OCR失败。

3. 认证错误

"user blocked": 未获得正式授权。

"token wrong": access_token错误。

"reach usage limit": 使用量达到上限或者授权过期。

"request too frequent": 请求过于频繁。

"reach traffic limit. wait *** hours": 达到流量上限,等待***小时后重试。

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

2.2 超分辨率

URL:
https://api.jzd.cool:<端口号>/sr
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
img form-data 图片。file。MIME: image/jpeg, image/png, image/tiff, image/webp, image/heic, image/heif, image/jp2。体积不得超过40MB。
scale form-data

放大倍数。整数。取值范围: 1, 2, 4。

若不作特意设定,则取默认值2。

style form-data

风格。整数。取值范围: 0, 1, 2, 3, 4。

若不作特意设定,则取默认值0。

ext form-data

返回图片格式。字符串。取值范围:"jpeg", "png", "tiff", "webp"。

若不作特意设定,则取默认值"jpeg"。

output form-data

数据格式。字符串。取值范围:"file", "base64"。

"file": 返回数据格式为image/jpeg, image/png, image/tiff, image/webp。

"base64": 返回数据格式为application/json。字段"base64"为图片的base64编码字符串。

若不作特意设定,则取默认值"file"。

正常返回:
image/jpeg, image/png, image/tiff, image/webp 或 application/json
异常返回:
application/json
字段 含义 格式
msg 错误类型

1. 设置错误

"image size too large": img体积超过限定值。

"image format wrong": img格式不支持。

"img wrong": img错误。

"img read failed": img读取错误。

"heic/heif failed": img heic/heif读取错误。

"style wrong": style错误。

"scale wrong": scale错误。

"ext wrong": ext错误。

"output wrong": output错误。

2. 执行错误

"sr failed": 超分辨率失败。

3. 认证错误

"user blocked": 未获得正式授权。

"token wrong": access_token错误。

"reach usage limit": 使用量达到上限或者授权过期。

"request too frequent": 请求过于频繁。

"reach traffic limit. wait *** hours": 达到流量上限,等待***小时后重试。

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

2.3 双层PDF

URL:
https://api.jzd.cool:<端口号>/pdf
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
img form-data 图片。文件。MIME: image/jpeg, image/png, image/tiff, image/webp, image/heic, image/heif, image/jp2。体积不得超过40MB。
data form-data

文本。json文件。支持两种格式:(1)包含字段:'char_ids', 'line_ids', 'chars', 'coors',参见ocr_pro的返回格式;(2)包含字段:'line_chars', 'line_coors',参见gj.cool标注平台的导出格式。

compression form-data

是否压缩。整数。取值范围: 0, 1。

0: 不压缩; 1: 压缩。

若不作特意设定,则取默认值0。

正常返回:
application/pdf
异常返回:
application/json
字段 含义 格式
msg 错误类型

1. 设置错误

"image size too large": img体积超过限定值。

"image format wrong": img格式不支持。

"img wrong": img错误。

"img read failed": img读取错误。

"heic/heif failed": img heic/heif读取错误。

"data wrong": data错误。

2. 执行错误

"pdf failed": pdf生成失败。

3. 认证错误

"user blocked": 未获得正式授权。

"token wrong": access_token错误。

"reach usage limit": 使用量达到上限或者授权过期。

"request too frequent": 请求过于频繁。

"reach traffic limit. wait *** hours": 达到流量上限,等待***小时后重试。

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

3. 文本类API

3.1 自动标点

URL:
https://gj.cool/punct_pro
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
src form-data 字符串。总字数上限为5000字。多个段落之间用\n分开。
正常返回:
application/json
字段 含义 格式
text 标点结果 字符串列表。数据项个数与src字段的段落数一致。每个数据项表示对应段落的自动标点结果。
异常返回:
application/json
字段 含义 格式
msg 错误类型

1. 设置错误

"parameter is wrong": 参数错误。

"text void": 空文本。

2. 执行错误

"punct failed": 自动标点失败。

3. 认证错误

"unauthorized user": 未获得非正式授权。

"reach usage limit":使用量达到上限或授权过期。

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

3.2. 文白翻译

URL:
https://api.jzd.cool:<端口号>/wenbai
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
src form-data 字符串。总字数上限10000字。
pairs form-data

0:整段输出。返回结果为字符串。

1:句对输出。返回结果为字符串列表。

若不作特意设定,则取默认值0。

正常返回:
application/json
字段 含义 格式
text 翻译结果

pairs取0时,字符串。

pairs取1时,字符串列表。数据项为字典,orig字段代表原文,trans字段代表译文。

异常返回:
application/json
字段 含义 格式
msg 错误类型

1. 设置错误

"wenbai text too long": 文本字数过多。

"wenbai text wrong": 文本错误。

2. 执行错误

"wenbai failed": 文白翻译失败。

3. 认证错误

"user blocked": 未获得正式授权。

"token wrong": access_token错误。

"reach usage limit": 使用量达到上限或者授权过期。

"request too frequent": 请求过于频繁。

"reach traffic limit. wait *** hours": 达到流量上限,等待***小时后重试。

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