General OCR
    • PDF

    General OCR

    • PDF

    Article summary

    Available in Classic and VPC

    Recognize and extract text from all areas of an image.

    Request

    This section describes the request format. The method and URI are as follows:

    MethodURI
    POST/general

    Request headers

    For information about the headers common to all CLOVA OCR APIs, see CLOVA OCR request headers.

    Request body

    You can include the following data in the body of your request:

    For Content-Type: application/json

    You can include the following data in the body of your request if the request header's Content-Type is application/json:

    FieldTypeRequiredDescription
    versionStringRequiredVersion information
    • V1 | V2 (recommended)
      • V1: Call V1 engine
      • V2: Call V2 engine
    requestIdStringRequiredRandom API call UUID
    timestampIntegerRequiredRandom API call time (timestamp)
    langStringOptionalOCR recognition request language information
    • ko | en | ja | zh-TW
      • ko: Korean
      • en: English
      • ja: Japanese
      • zh-TW: Chinese (Traditional)
    • Automatically set to domain's language setting if not entered
    • Comma (,) to call multiple languages simultaneously
      • <e.g.> "ko, ja, zh-TW"
    imagesArrayRequiredimages details
    • Write as JSON array
    • Able to create 1 image array per call
    • Image size: up to 50 MB
    enableTableDetectionBooleanOptionalWhether to recognize table areas within document images and provide a structured form
    • true | false (default)
      • true: table recognition and form provided
      • false: table recognition and form not provided
    • Must enable (ON) the toggle button for "Table extraction status" in the domain created in NAVER Cloud Platform to use it

    For Content-Type: multipart/form-data

    You can include the following data in the body of your request if the request header's Content-Type is multipart/form-data.

    FieldTypeRequiredDescription
    messageObjectRequiredRequest data information
    fileFileRequiredOCR recognition image file
    message.versionStringRequiredVersion information
    • V1 | V2 (recommended value)
      • V1: Call V1 engine
      • V2: Call V2 engine
    message.requestIdStringRequiredRandom API call UUID
    message.timestampIntegerRequiredRandom API call time (timestamp)
    message.langStringOptionalOCR recognition request language information
    • ko | en | ja | zh-TW
      • ko: Korean
      • en: English
      • ja: Japanese
      • zh-TW: Chinese (Traditional)
    • Automatically set to domain's language setting if not entered
    • Comma (,) to call multiple languages simultaneously
      • <e.g.> "ko, ja, zh-TW"
    message.imagesArrayRequiredimages details
    • Write as JSON array
    • Able to create 1 image array per call
    • Image size: up to 50 MB
    message.enableTableDetectionBooleanOptionalWhether to recognize table areas within document images and provide a structured form
    • true | false (default)
      • true: table recognition and form provided
      • false: table recognition and form not provided
    • Must enable (ON) the toggle button for "Table extraction status" in the domain created in NAVER Cloud Platform to use it

    images

    The following describes images.

    FieldTypeRequiredDescription
    formatStringRequiredImage format
    • jpg | jpeg | png | pdf | tif | tiff
      • pdf: up to 10 pages can be recognized
    nameStringRequiredImage name
    • Use to identify images and check response results
    urlStringConditionalImage URL address
    • Public URL where images can be fetched
    • images.url or images.data must be entered
      • images.data is prioritized when both are entered
    dataStringConditionalBase64-encoded image data
    • images.url or images.data must be entered
      • images.data is prioritized when both are entered

    Request example

    The request example is as follows:

    For Content-Type: application/json

    The request example if the request header's Content-Type is application/json is as follows:

    curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33675/8f694ccb00dbd8001e9b0fcbac****************/general' \
    --header 'Content-Type: application/json' \
    --header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
    --data '{
        "version": "V2",
        "requestId": "1234",
        "timestamp": "1722225600000",
        "lang": "ko",
        "images": [
            {
            "format": "jpg",
            "name": "demo_2",
            "url": "https://www.ncloud.com/file-img/vol02/000/614/********/********_0001.jpg"
            }
        ],
        "enableTableDetection": false
    }'
    

    For Content-Type: multipart/form-data

    The request example if the request header's Content-Type is multipart/form-data is as follows:

    curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33675/8f694ccb00dbd8001e9b0fcbac**********************/general' \
    --header 'Content-Type: multipart/form-data' \
    --header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
    --form 'file=@"{file}.pdf"' \
    --form 'message="{\"version\": \"v1\", \"requestId\": \"1234\", \"timestamp\": 1722225600000, \"lang\": \"ko\", \"images\": [{\"format\": \"pdf\", \"name\": \"covid_sample\"}]}"'
    

    Response

    This section describes the response format.

    Note

    When requesting with the V2 version, the bounding and boundingPoly information is displayed in the response result value.

    Response body

    The response body includes the following data:

    FieldTypeRequiredDescription
    versionString-Version information
    • V1 | V2
      • V1: Call V1 engine
      • V2: Call V2 engine
    requestIdString-API call UUID
    timestampInteger-API call time (timestamp)
    imagesArray-images details

    images

    The following describes images.

    FieldTypeRequiredDescription
    uidString-Image UID
    • Use for API validity checks and request tracing
    nameString-Image name
    • Use to identify images and check response results
    inferResultString-Image recognition result
    • SUCCESS | FAILURE | ERROR
      • SUCCESS: recognition successful
      • FAILURE: recognition failure
      • ERROR: recognition processing exception
    messageString-Result message
    validationResultObject-Validity check result information
    validationResult.resultString-Validity check result code
    • NO_REQUESTED | UNCHECKED | ERROR | VALID | INVALID
      • NO_REQUESTED: validation job not requested
      • UNCHECKED: unconfirmed action response or unaccepted response
      • ERROR: validation error occurred
      • VALID: validation result valid
      • INVALID: validation result invalid
    validationResult.messageString-Validity check result details message
    • This value is not always returned
    convertedImageInfoObject-Converted image information
    • If format is pdf or tiff
    • Coordinate values are set relative to the called image file
    convertedImageInfo.widthInteger-Converted image width
    convertedImageInfo.heightInteger-Converted image height
    convertedImageInfo.pageIndexInteger-Converted image page index
    convertedImageInfo.longImageBoolean-Whether the converted image length is long
    • true | false
      • true: long image
      • false: not a long image
    combineResultObject-Image recognition result combination information
    combineResult.nameString-Image combination field name
    combineResult.textString-Output value and fixed text for each image field
    tablesArray-Tables details
    fieldsArray-Fields details

    tables

    The following describes tables.

    FieldTypeRequiredDescription
    cellsArray-Cells details
    inferTextString-Recognized text
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details

    fields

    The following describes fields.

    FieldTypeRequiredDescription
    nameString-Image name
    • Use to identify images and check response results
    • Works only for API calls
    valueTypeString-Input value type
    • ALL | NUMERIC
      • ALL: text and numbers
      • NUMERIC: numbers
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    inferTextString-Recognized text
    • If type is CHECKBOX, replace with response value specified in settings
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    typeString-Recognized image type
    • NORMAL | MULTI_BOX | CHECKBOX
      • NORMAL: general
      • MULTI_BOX: multi-box
      • CHECKBOX: checkbox
    lineBreakBoolean-Indicate whether the recognized text is the last line
    • true | false
      • true: last text
      • false: not last text
    checkedBoolean-Checkbox selection
    • true | false
      • true: selected
      • false: not selected

    cells

    The following describes cells.

    FieldTypeRequiredDescription
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    cellTextLinesArray-Cell's line details
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    rowSpanInteger-Number of horizontal columns occupied by cells in the table (span)
    rowIndexInteger-Position value of the corresponding horizontal column in the table
    columnSpanInteger-Number of vertical rows occupied by cells in the table (span)
    columnIndexInteger-Position value of the corresponding vertical row in the table

    cellTextLines

    The following describes cellTextLines.

    FieldTypeRequiredDescription
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    cellWordsArray-Cell's text details

    cellWords

    The following describes cellWords.

    FieldTypeRequiredDescription
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    inferTextString-Recognized text

    vertices

    The following describes vertices.

    FieldTypeRequiredDescription
    xFloat-Bounding poly X-axis coordinate value
    yFloat-Bounding poly Y-axis coordinate value

    Response status codes

    For information about the HTTP status codes common to all CLOVA OCR APIs, see Common CLOVA OCR response status codes.

    Response example

    The response example is as follows:

    If version is V2

    The response example when version is V2 is as follows.

    {
        "version": "V2",
        "requestId": "string",
        "timestamp": 1576569034247,
        "images": [{
            "uid": "9fd73a6aacad4025b3099a36ee55aacd",
            "name": "medium",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                    "result": "NO_REQUESTED"
                },
                "convertedImageInfo": {
                    "width": 1224,
                    "height": 1584,
                    "pageIndex": 0,
                    "longImage": false
                },
            "fields": [{
                    "valueType": "ALL",
                    "inferText": "How beautiful",
                    "inferConfidence": 0.99992156,
                    "type": "NORMAL",
                    "lineBreak": true,
                    "boundingPoly": {
                        "vertices": [{
                            "x": 2713.7295,
                            "y": 1277.0492
                        }, {
                            "x": 2713.7295,
                            "y": 977.7408
                        }, {
                            "x": 2841.4343,
                            "y": 977.7408
                        }, {
                            "x": 2841.4343,
                            "y": 1277.0492
                        }]
                    }
                },
                {
                    "valueType": "ALL",
                    "inferText": "this",
                    "inferConfidence": 0.99958915,
                    "type": "NORMAL",
                    "lineBreak": false,
                    "boundingPoly": {
                        "vertices": [{
                            "x": 2314.6516,
                            "y": 1468.6066
                        }, {
                            "x": 2314.6516,
                            "y": 1328.9293
                        }, {
                            "x": 2426.3936,
                            "y": 1328.9293
                        }, {
                            "x": 2426.3936,
                            "y": 1468.6066
                        }]
                    }
                },
                {
                    "valueType": "ALL",
                    "inferText": "world is",
                    "inferConfidence": 0.9998707,
                    "type": "NORMAL",
                    "lineBreak": false,
                    "boundingPoly": {
                        "vertices": [{
                            "x": 2314.6516,
                            "y": 1604.2931
                        }, {
                            "x": 2314.6516,
                            "y": 1460.625
                        }, {
                            "x": 2430.3843,
                            "y": 1460.625
                        }, {
                            "x": 2430.3843,
                            "y": 1604.2931
                        }]
                    }
                }
            ]
        }]
    }
    

    If version is V1

    The response example when version is V1 is as follows.

    {
        "version": "v1",
        "requestId": "1234",
        "timestamp": 1724821610657,
        "images": [
            {
                "uid": "{uid}",
                "name": "covid_demo",
                "inferResult": "SUCCESS",
                "message": "SUCCESS",
                "validationResult": {
                    "result": "NO_REQUESTED"
                },
                "fields": [
                    {
                        "valueType": "ALL",
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 581.0,
                                    "y": 123.0
                                },
                                {
                                    "x": 650.0,
                                    "y": 123.0
                                },
                                {
                                    "x": 650.0,
                                    "y": 149.0
                                },
                                {
                                    "x": 581.0,
                                    "y": 149.0
                                }
                            ]
                        },
                        "inferText": "Cultivating",
                        "inferConfidence": 0.9985
                    },
                    {
                        "valueType": "ALL",
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 399.0,
                                    "y": 1168.0
                                },
                                {
                                    "x": 790.0,
                                    "y": 1168.0
                                },
                                {
                                    "x": 790.0,
                                    "y": 1215.0
                                },
                                {
                                    "x": 399.0,
                                    "y": 1215.0
                                }
                            ]
                        },
                        "inferText": "Principal of Seoul Elementary School",
                        "inferConfidence": 0.9997
                    }
                ]
            }
        ]
    }
    

    Was this article helpful?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.