OCR 服务API

免费体验

通过 API 从图片和文档文件中提取文字。当前服务使用异步任务流程：创建任务、获取 task_id，再轮询查询结果。

接口返回的结果文件链接有效期为 1 小时，请及时下载存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建 OCR 任务

POST /api/tasks/document/ocr

请求参数

image_url string 可选

源文件 URL。与 image_file 二选一；如果传入此参数，另一个文件来源参数必须为空。请勿使用 80、443 以外的端口地址。

二选一必填

image_file file 可选

源文件（二进制 multipart）。与 image_url 二选一；如果传入此参数，另一个文件来源参数必须为空。

图片上传要求请参看使用规范与限制#4。

language string 可选

输入文件语言。默认为 ChinesePRC、English 和 Digits。最多不超过 10 种语言。多种语言用逗号分隔，名称区分大小写，例如 English,ChinesePRC,Digits。

password string 可选

文件密码。如果输入文件有密码，请在此参数中传入密码，密码最大长度为 32 位。

format string 可选

输出文件格式。可选值为 txt、pdf、docx、xlsx、pptx。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

接口返回消息。如果失败，可以参考此参数返回的信息，或携带此参数联系支持人员。

data.task_id string

OCR 任务 ID。创建任务成功后返回，用于后续查询结果。

查询 OCR 结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 300 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

GET /api/tasks/document/ocr/{task_id}

路径参数

task_id string 必填

创建任务后返回的 OCR 任务 ID，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

接口返回消息。如果失败，可以参考此参数返回的信息，或携带此参数联系支持人员。

data.task_id string

OCR 任务 ID。如果任务失败，请携带此 task_id 联系支持人员。

data.created_at string

任务创建时间，Unix 时间戳字符串。

data.processed_at string

任务开始处理时间，Unix 时间戳字符串。

data.completed_at string

任务完成时间，Unix 时间戳字符串。

data.file string

OCR 结果文件 URL，URL 结果有效期为 1 小时。

data.progress number

任务处理进度。100 表示处理完成。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

使用规范与限制

接口返回的结果文件链接有效期为 1 小时，请及时下载并存储。
HTTP status 为 200 表示 HTTP 请求成功，并不一定表示 OCR 任务处理成功，详见状态码说明。
使用 image_url 作为参数传递时，请遵守 URL 编码规范，且不要使用 80、443 以外的端口地址。

上传文件需符合以下格式、分辨率和大小限制。

输入格式	输出格式	分辨率	大小
pdf, ppt, pptx, xls, xlsx, doc, docx, jpeg, jpg, png, gif, bmp	pdf, docx, pptx, xlsx, txt	输入图片文件最大 32512 x 32512	不超过 200 MB (含 200MB)

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // 仅在异步轮询结果中存在。
    "processed_at": "1634884056", // 仅在异步轮询结果中存在。
    "completed_at": "1634884056", // 仅在异步轮询结果中存在。
    "file": "https://wxtechsz.oss-cn-shenzhen.aliyuncs.com/tasks/output/ocr/xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.txt", // 仅在异步轮询结果中存在。
    "progress": 100, // 仅在异步轮询结果中存在。
    "state": 1 // 仅在异步轮询结果中存在。
  }
}