看典古籍OCR API使用文档

您可以在此查看API接口的请求参数和响应内容，并在线调用测试，若您有任何问题，您可以向我们提交反馈或直接联系我们。

快速开始

  1. 注册/登录看典古籍账号，进入 古籍数字化 - OCR API 申请 API Token。
  2. 在 Token 查看页面复制您的 token 和账号（邮箱或手机号均可）。
  3. 根据下方接口文档构造请求，调用 https://ocr.kandianguji.com/ocr_api 进行文字识别。
  4. 通过 /get_token_status 接口查询 Token 剩余额度和状态。

通用说明

  • API 基础地址：https://ocr.kandianguji.com
  • 认证方式：每个请求都需要 token 和 email。这里的 email 实际是账号：邮箱注册的传邮箱，手机号注册的传手机号。
  • 请求方式：POST 接口支持 Form Data 或 JSON；PDF 上传接口使用 Form Data/multipart。
  • 统一响应结构：message / id / info / data。成功时 message=success，失败时 message=error 且 info 返回具体错误信息。
  • 图片建议使用 JPG/PNG 并转为 base64 字符串；可通过 image_size 调整最长边以提升识别速度。

API接口说明：

本接口实现古籍图像文字识别功能

API接口地址： https://ocr.kandianguji.com/ocr_api

API Token查看：

您可以点击此处查看您的API Token信息

请求参数：

参数名 类型 必填 默认值 说明
token string 必传 - 您所申请的 API Token，点此申请
email string 必传 - 申请 API Token 的账号（邮箱或手机号均可，即注册账号）
image string(base64) 必传 - 需要识别的古籍图像，base64 编码后的字符串。可在 此处 将图像转为 base64
char_ocr boolean 否 false 是否进行单字符检测识别；不检测文本行，只检测图像上的字符，文本行顺序可能会出错
det_mode string 否 auto 文字内容排版样式：auto（自动识别）、sp（竖向排版）、hp（横向排版）
image_size integer 否 0 识别前图像尺寸调整；0 为不调整，设置指定值将按最长边等比例调整，图像越小识别越快
return_position boolean 否 false 是否返回详细识别结构；false 时 data 直接为 texts 文本行数组；true 时返回包含 width/height/text_lines 等字段的对象
return_choices boolean 否 false 是否返回每个字符的其它候选字；仅在 return_position=true 时生效
texts_positions array/string 否 - 开启后接受用户指定的文字坐标，直接识别文字内容；JSON 请求可传数组，Form Data 可传字符串
version string 否 default 识别算法版本：default（v1标准版本）、beta（古籍语序优化版本）、v2（最新版本）
det_layout（v2） boolean/string 否 false 是否开启版面识别（判断正文、页眉页脚/版心等），对分栏式、多栏式文档效果较好；支持 true/false，也支持字符串 oushi_ocr，用于识别欧式家谱格式
only_plain_text（v2） boolean 否 false 仅当版面识别开启时生效；只识别返回正文内容，不识别页眉/页脚/版心等
return_layout（v2） boolean 否 false 仅在 return_position=true 且版面识别开启时生效；是否返回版面信息
auto_insert_space（v2） boolean 否 false 按照字符间距自动插入空格
hp_line_words_angel（v2） string 否 left2right 横排句子文字排序方向：left2right（从左到右）、right2left（从右到左）
sp_line_words_angel（v2） string 否 top2bottom 竖排句子文字排序方向：top2bottom（从上到下）、bottom2top（从下到上）

请求方式：

POST请求，请求体可以为 Form Data 或 JSON 两种方式均可接受

响应内容：

字段说明：text_angel / text_angel_confidence 中的 angel 为历史遗留拼写，实际含义是 angle（文字排版方向）。为兼容已接入的调用方，后端暂时保留该字段名，文档与线上接口保持一致。

响应结构说明：默认 return_position=false 时，data 直接是 texts 文本行数组；只有 return_position=true 时，data 才是包含 width/height/text_lines 等字段的对象。

字段路径 类型 返回条件 说明
message string 总是 请求状态：success / error
id string 总是 请求对应的唯一 id
info string 总是 与 message 关联；成功为空，错误时返回具体错误信息
data object/array 总是 return_position=false 时为 texts 文本行数组；return_position=true 时为包含详细识别结果的对象
data.width integer return_position=true 图像宽度（像素）
data.height integer return_position=true 图像高度（像素）
data.text_angel integer return_position=true 文字排版方向：0 横排；1 竖排
data.text_angel_confidence number return_position=true 文字排版方向置信度
data.texts[] array return_position=true 文本行列表（纯文本内容）；return_position=false 时该数组直接作为 data 返回；排序规则：横向排版按从上到下、从左到右；竖向排版按从右到左、从上到下
data.text_lines[] array return_position=true 每个文本行的详细信息
data.text_lines[].text string return_position=true 文本行文字内容
data.text_lines[].position array return_position=true 文本行位置坐标，从左上角开始顺时针四个顶点：[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]
data.text_lines[].layout_classes_id integer return_position=true, det_layout=true 内容属性：0 正文；1 页眉/页脚/版心等
data.text_lines[].words[] array return_position=true 文本行中每个文字的信息
data.text_lines[].words[].text string return_position=true 文字内容
data.text_lines[].words[].choices array return_position=true, return_choices=true 该字符的其它候选字
data.text_lines[].words[].confidence number return_position=true 文字置信度
data.text_lines[].words[].position array return_position=true 文字基于全图的矩形框坐标：[x1,y1,x2,y2]
data.text_lines[].words[].det_confidence number return_position=true 位置检测置信度
data.text_lines[].words[].layout_classes_id integer return_position=true, det_layout=true 内容属性：0 正文；1 页眉/页脚/版心等
data.layout[] array return_position=true, return_layout=true 版面信息
data.layout[].position array return_position=true, return_layout=true 版面区域矩形框坐标：[x1,y1,x2,y2]
data.layout[].classes integer return_position=true, return_layout=true 版面类型属性：0 正文；1 页眉/页脚/版心等

请求示例（JSON）：

{
  "token": "your_token",
  "email": "your_account",
  "image": "base64_string",
  "det_mode": "auto",
  "version": "default",
  "return_position": true,
  "det_layout": true,
  "return_layout": true
}

默认响应示例（return_position=false）：

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "message": "success",
  "data": [
    "第一行文字",
    "第二行文字",
    "第三行文字"
  ],
  "info": ""
}

完整响应示例（return_position=true）：

{
  "message": "success",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "info": "",
  "data": {
    "width": 1200,
    "height": 800,
    "text_angel": 0,
    "text_angel_confidence": 0.99,
    "texts": [
      "示例文本"
    ],
    "text_lines": [
      {
        "text": "示例文本",
        "position": [[10, 10], [100, 10], [100, 40], [10, 40]],
        "layout_classes_id": 0,
        "words": [
          {
            "text": "示",
            "choices": ["示"],
            "confidence": 0.99,
            "position": [10, 10, 30, 40],
            "det_confidence": 0.98,
            "layout_classes_id": 0
          }
        ]
      }
    ],
    "layout": [
      {
        "position": [0, 0, 1000, 600],
        "classes": 0
      }
    ]
  }
}

接口调用示例：

多语言调用看典古籍OCR API示例: 查看代码

API接口说明：

本接口实现查询API Token使用状态功能

API接口地址： https://ocr.kandianguji.com/get_token_status

API Token查看：

您可以点击此处查看您的API Token信息

请求参数：

参数名 类型 必填 默认值 说明
token string 必传 - 您所申请的 API Token，点此申请
email string 必传 - 申请 API Token 的账号（邮箱或手机号均可，即注册账号）

请求方式：

POST请求，请求体可以为 Form Data 或 JSON 两种方式均可接受

响应内容：

字段路径 类型 返回条件 说明
message string 总是 请求状态：success / error
id string 总是 请求对应的唯一 id
info string 总是 与 message 关联；成功为空，错误时返回具体错误信息
data object 总是 数据内容
data.total_count integer 总是 API 总额度
data.used_count integer 总是 API 已使用额度
data.is_active integer 总是 API 状态：0 申请中；1 已通过状态正常；2 申请不通过

请求示例（JSON）：

{
  "token": "your_token",
  "email": "your_account"
}

响应示例：

{
  "message": "success",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "info": "",
  "data": {
    "total_count": 10000,
    "used_count": 1234,
    "is_active": 1
  }
}

该接口当前暂时停用，以下内容仅作为存档参考，请勿在生产环境调用。
API接口说明：

本接口实现PDF全书识别功能，通过接口上传PDF文件，识别完成后下载识别结果。

API接口地址： https://ocr.kandianguji.com/api/pdf_ocr_api

请求参数：

参数名 类型 必填 默认值 说明
token string 必传 - 您所创建的 API Token，点此申请
email string 必传 - 创建 API Token 的账号（邮箱或手机号均可，即注册账号）
file file 必传 - PDF 文件（单个）
det_mode string 否 auto 排版样式：auto（自动识别）、sp（竖向排版）、hp（横向排版）
image_size integer 否 0 识别前图像尺寸调整；0 为不调整，按最长边等比例调整
version string 否 default 识别系统版本：default（标准识别版本）、beta（古籍语序优化版本）

请求方式：

POST请求，请求体为 Form Data

响应内容：

字段路径 类型 返回条件 说明
message string 总是 请求状态：success / error
info string 总是 与 message 关联；成功为空，错误时返回具体错误信息
data object 总是 数据内容
data.task_id string 总是 本次任务 ID，后续查询任务状态、下载识别结果需要使用该 ID

该接口当前暂时停用，以下内容仅作为存档参考，请勿在生产环境调用。
API接口说明：

本接口使用上一个接口创建任务获取到的 task_id 来查询任务识别进度。

API接口地址： https://ocr.kandianguji.com/api/pdf_ocr_api_status

请求参数：

参数名 类型 必填 默认值 说明
token string 必传 - 您所创建的 API Token，点此申请
email string 必传 - 创建 API Token 的账号（邮箱或手机号均可，即注册账号）
task_id string 必传 - PDF 识别任务 ID

请求方式：

POST请求，请求体为 Form Data

响应内容：

字段路径 类型 返回条件 说明
message string 总是 请求状态：success / error
info string 总是 与 message 关联；成功为空，错误时返回具体错误信息
data object 总是 数据内容
data.task_id string 总是 PDF 识别任务 ID
data.created_on string 总是 任务创建时间
data.pages integer 总是 总页数
data.speed number 总是 识别进度
data.is_finish boolean 总是 任务是否完成
data.finished_on string/null 总是 任务完成时间（未完成为 null）
data.code string 任务完成后 任务识别完成时返回，下载识别结果时使用

该接口当前暂时停用，以下内容仅作为存档参考，请勿在生产环境调用。
API接口说明：

本接口使用 PDF 识别任务 ID 和 code 下载识别结果压缩包。

请求方式：

GET请求

请求参数：

参数名 类型 必填 默认值 说明
code string 必传 - 任务完成时通过接口四 /api/pdf_ocr_api_status 返回的 code
file_type string 否 all 下载结果文件类型：txt（文本）、json（含坐标的 json）、all（含 json、txt、word、分页图像）、word（Word 文档）

响应内容：

通过 GET 请求下载文件即可。

在线调用测试

响应结果：

等待请求...

响应结果：

等待请求...

在线测试会在浏览器中直接请求 API。

多语言调用示例

curl -X POST "https://ocr.kandianguji.com/ocr_api" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your_token",
    "email": "your_account",
    "image": "base64_string",
    "det_mode": "auto"
  }'
import requests

url = "https://ocr.kandianguji.com/ocr_api"
payload = {
    "token": "your_token",
    "email": "your_account",
    "image": "base64_string",
    "det_mode": "auto",
}
resp = requests.post(url, json=payload)
print(resp.json())
async function runOcr() {
    const response = await fetch("https://ocr.kandianguji.com/ocr_api", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            token: "your_token",
            email: "your_account",
            image: "base64_string",
            det_mode: "auto",
        }),
    });
    const data = await response.json();
    console.log(data);
}

runOcr();
Bootstrap Check
Bootstrap