注意事项

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

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

is_long form-data

是否生成长效access_token。

0:否。过期时间为24小时。

1:是。过期时间为90天。

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

正常返回:
application/json
字段 含义 格式
access_token 用于授权服务的鉴权。 JSON Web Token
refresh_token 用于刷新access token。过期时间为30天。 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 用于授权服务的鉴权。过期时间为24小时。 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:
字段 是否必选 格式 说明
img form-data 图片。file。MIME: image/jpeg, image/png, image/tiff, image/webp, image/heic, image/heif, image/jp2。体积不得超过70MB。
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 图片的文件名(不含扩展名) 字符串。
ContentType 图片的MIME 字符串。
CharNumber 总字数 整数。
LineNumber 总行数 整数。
Width 图片宽度的像素值 整数。
Height 图片高度的像素值 整数。
Size 图片的存储空,单位byte 整数。
Layout 识别版式 整数。
Area 识别区域 字符串。含义同
Compact 识别密集系数 整数。
chars 单字识别结果 列表。数据项为长度为1的字符串。数据项个数与总字数一致。
coors 单字坐标 列表。数据项为[x1,y1,x2,y2],分别代表字框的左边界、上边界、右边界、下边界的像素值,都是整数。数据项个数与总字数一致。
char_probs 单字识别结果的置信度 列表。数据项为四位小数。数据项个数与总字数一致。
coor_probs 单字坐标的置信度 列表。数据项为四位小数。数据项个数与总字数一致。
char_ids 单字的序号 列表。数据项为整数。数据项个数与总字数一致。
line_ids 单字所在行的序号 列表。数据项为整数。数据项个数与总字数一致。
layer 单字的版面层次。 列表。数据项为列表。数据项个数与总字数一致。数据项通常是包含1-3个整数的列表。第一个数字代表单字所在的文字列(由界栏分隔的列,可以包含若干夹注)的序号。第二个数字代表单字所在文字列子区域的序号。第三个数字通常代表单字所在夹注的左右位置,右侧为0,左侧为1。
option 单字的非top1候选项 列表。数据项为字典。数据项个数与总字数一致。数据项的键是候选项,值是置信度。
text 所有单字的文字列形式 字符串。文字列之间用\n分隔。夹注部分用【】包围起来。
异常返回:
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。体积不得超过70MB。
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。体积不得超过70MB。
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://api.jzd.cool:<端口号>/punct_pro
Method:
POST
Headers:
字段 内容 说明
Authorization gjcool <access_token> "gjcool"与access_token之间用一个空格连接
Body:
字段 是否必选 格式 说明
src form-data 字符串。总字数上限为20000字。多个段落之间用\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": 达到流量上限,等待***小时后重试。

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