OCR API

Try on PicWish

Extract text from image and document files programmatically. This API uses an async task flow: create a task, read task_id, then poll for the result.

The result file URL is valid for 1 hour. Please download and store it promptly.

Authentication

Every API request must include your API Key in the X-API-KEY request header. Send it with each request exactly as shown in the examples and parameter descriptions.

X-API-KEY: YOUR_API_KEY

Create an OCR task

POST /api/tasks/document/ocr

Body Parameters

image_url string optional

Source file URL. Use either image_url or image_file. If this parameter is present, the other file source parameter must be empty. Do not use ports other than 80 or 443.

one required

image_file file optional

Source file as binary multipart data. Use either image_file or image_url. If this parameter is present, the other file source parameter must be empty.

For image upload requirements, see Guidelines and Limits #4.

language string optional

Source file language. Default: ChinesePRC, English, and Digits. A file can contain up to 10 languages. Languages must be comma-separated and case-sensitive, for example English,ChinesePRC,Digits.

password string optional

Password of the source file if it is password protected. Passwords can be up to 32 characters.

format string optional

Result file format. Supported values: txt, pdf, docx, xlsx, and pptx.

Return Parameters

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

API response message. If the task fails, refer to this message or contact support with it.

data.task_id string

OCR task ID returned after the task is created.

Query OCR result

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

Path Parameters

task_id string required

OCR task ID returned after creating a task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

API response message. If the task fails, refer to this message or contact support with it.

data.task_id string

OCR task ID. If the task fails, contact support with this task_id.

data.created_at string

Task creation time as a Unix timestamp string.

data.processed_at string

Task processing start time as a Unix timestamp string.

data.completed_at string

Task completion time as a Unix timestamp string.

data.file string

OCR result file URL. The URL is valid for 1 hour after processing succeeds.

data.progress number

Task progress. 100 means processing is complete.

data.state number

Task status code. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.

Guidelines and Limits

The result file URL is valid for 1 hour. Please download and store it promptly.
HTTP status 200 indicates that the HTTP request succeeded, not necessarily that the OCR task succeeded. See Status Code Definitions for details.
When passing image_url, follow URL encoding standards and do not use ports other than 80 or 443.
Uploaded files must meet the following format, resolution, and file size limits.

Source format Output format Resolution Size

pdf, ppt, pptx, xls, xlsx, doc, docx, jpeg, jpg, png, gif, bmp pdf, docx, pptx, xlsx, txt Image files up to 32512 x 32512 Up to 200 MB

Source format	Output format	Resolution	Size
pdf, ppt, pptx, xls, xlsx, doc, docx, jpeg, jpg, png, gif, bmp	pdf, docx, pptx, xlsx, txt	Image files up to 32512 x 32512	Up to 200 MB

Response

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // Only present in async polling results.
    "processed_at": "1634884056", // Only present in async polling results.
    "completed_at": "1634884056", // Only present in async polling results.
    "file": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/ocr/xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.txt", // Only present in async polling results.
    "progress": 100, // Only present in async polling results.
    "state": 1 // Only present in async polling results.
  }
}