Image

Universal OCR Text Recognition

0calls
4 credits / call

Whether you need to implement automated receipt entry, or highlight text coordinates on images in web frontend, this high-precision OCR endpoint can provide you with powerful basic capabilities.

POST
uapis.cn
/api/v1/image/ocr
Body
file
file

Image file to be recognized. Supports common formats such as JPG, JPEG, PNG, BMP, GIF, WebP, etc., maximum size not exceeding 10MB. Do not submit together with url or image_base64.

Drag a file here, orclick to upload

Image file to be recognized. Supports common formats such as JPG, JPEG, PNG, BMP, GIF, WebP, etc., maximum size not exceeding 10MB. Do not submit together with url or image_base64.

url
string

Publicly accessible image address. Do not submit together with file or image_base64.

image_base64
string

Base64 string of the image. Can pass complete Data URI or only pure Base64 content. Do not submit together with file or url.

image_name
string

Custom image filename. Recommended to pass together when passing link or pure Base64, to facilitate retaining or inferring extension.

need_location
string

Whether to return text coordinate information. Please pass true or false, defaults to true when not passed.

return_markdown
string

Whether to additionally return organized Markdown text. Please pass true or false, defaults to false when not passed.

enable_cls
string

Whether to enable additional text direction correction. Please pass true or false, defaults to false when not passed.

Overview

Important

If you only care about what's written on the image (such as screenshot text extraction or content security review), it is strongly recommended to setneed_location to false. This will significantly reduce the size of returned JSON data, improving network transmission and system parsing efficiency.

In addition to regular image-to-text conversion, this endpoint has some practical designs for actual development scenarios:

  • Frontend Text Highlighting and Structured Analysis: By default returns rectangular coordinates and four vertex coordinates for each paragraph of text. This is very suitable for using Canvas to draw boxes and highlight on the original image, or extracting key-value pair information from receipts based on relative positions on the backend.
  • Anti-Distortion in Complex Shooting Environments: For rotation or tilt caused by mobile phone shooting, you can enable enable_cls=true. The server will automatically perform direction pre-correction before recognition, significantly improving recognition accuracy.
  • Flexible Input and Request Requirements: The endpoint supports three input methods: file, url or image_base64. Please ensure the request format is multipart/form-data, and the image link is directly accessible from the public internet.

Request body

Form data containing image to be recognized and optional configurations. Regardless of input method, request body must use multipart/form-data format. Please choose one of file, url or image_base64 as input source.

file
fileoptional

Image file to be recognized. Supports common formats such as JPG, JPEG, PNG, BMP, GIF, WebP, etc., maximum size not exceeding 10MB. Do not submit together with url or image_base64.

url
stringoptional

Publicly accessible image address. Do not submit together with file or image_base64.

image_base64
stringoptional

Base64 string of the image. Can pass complete Data URI or only pure Base64 content. Do not submit together with file or url.

image_name
stringoptional

Custom image filename. Recommended to pass together when passing link or pure Base64, to facilitate retaining or inferring extension.

need_location
stringoptional

Whether to return text coordinate information. Please pass true or false, defaults to true when not passed.

return_markdown
stringoptional

Whether to additionally return organized Markdown text. Please pass true or false, defaults to false when not passed.

enable_cls
stringoptional

Whether to enable additional text direction correction. Please pass true or false, defaults to false when not passed.

Response

200 / OK

Recognition successful, returns unified OCR result object. Includes coordinate information by default; when need_location=false, coordinate-related fields will be omitted.

JSON
{
  // Recognized text concatenated in reading order.
  "text": "To:Zhang San\nPhone:13800000000",
  // Plain text result, suitable for search, indexing or direct display.
  "plain_text": "To:Zhang San\nPhone:13800000000",
  // Markdown text organized based on titles, paragraphs and tables in the image. Only returned when `return_markdown=true`.
  "markdown": "# Invoice\n\nTo: Zhang San\nPhone: 13800000000\n\n| Field | Content |\n| --- | --- |\n| Address | 100 Century Avenue, Pudong New Area, Shanghai |",
  // Paragraph-by-paragraph text results. Suitable for highlighting, box selection and item-by-item parsing.
  "words_result": [
    {
      // Recognition result of current text fragment.
      "words": "To:Zhang San",
      // Rectangular coordinates of current text fragment. Only returned when `need_location=true`.
      "location": {
        "left": 56,
        "top": 128,
        "width": 240,
        "height": 32
      },
      // Vertex coordinate list of current text fragment. Only returned when `need_location=true`.
      "vertexes_location": [
        {
          "x": 56,
          "y": 128
        }
      ],
      // Confidence of current text fragment. Some results will return.
      "score": 0.992
    }
  ],
  // Number of recognized text fragments.
  "words_result_num": 2,
  // Whether this response includes coordinate information.
  "need_location": true,
  // Timing breakdown information, suitable for performance statistics or troubleshooting.
  "timing": {
    "total_ms": 324
  },
  // Statistical summary of recognition results.
  "summary": {
    "line_count": 2,
    "block_count": 1
  },
  // Basic information about the image itself.
  "image": {
    "width": 1280,
    "height": 720
  },
  // Detailed recognition results organized by line.
  "lines": [
    {}
  ],
  // Detailed recognition results organized by block.
  "blocks": [
    {}
  ],
  // Detailed recognition results organized by page.
  "pages": [
    {}
  ],
  // Supplementary recognition result object, suitable for scenarios requiring further parsing of more detailed fields.
  "raw": {}
}

400 / Bad Request

Request parameters are incorrect, such as not providing image source, submitting multiple image sources, or invalid boolean parameters and Base64 format.

Format 1Missing Image Source
JSON
{
  "code": "INVALID_PARAMETER",
  "message": "At least one of file, url, image_base64 must be provided"
}
Format 2Input Source Conflict
JSON
{
  "code": "INVALID_PARAMETER",
  "message": "Please do not submit file, url, image_base64 simultaneously, only choose one method"
}
Format 3Base64 Format Error
JSON
{
  "code": "INVALID_PARAMETER",
  "message": "image_base64 is not valid image Base64 data"
}

413 /

Image size exceeds current limit.

JSON
{
  "code": "FILE_TOO_LARGE",
  "message": "Image size cannot exceed 10485760 bytes"
}

415 /

Uploaded content is not a recognizable common image format.

JSON
{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "Currently only accepts common image formats"
}

502 / Bad Gateway

Recognition processing failed, please try again later.

JSON
{
  "code": "REQUEST_FAILED",
  "message": "Text recognition failed, please try again later"
}

503 / Service Unavailable

Text recognition service is temporarily unavailable, please try again later.

JSON
{
  "code": "SERVICE_TEMPORARILY_UNAVAILABLE",
  "message": "Text recognition service is temporarily unavailable, please try again later"
}