General OCR

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:

Method	URI
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:

Field	Type	Required	Description
`version`	String	Required	Version information `V1` \| `V2` (recommended) `V1`: Call V1 engine `V2`: Call V2 engine
`requestId`	String	Required	Random API call UUID
`timestamp`	Integer	Required	Random API call time (timestamp)
`lang`	String	Optional	OCR recognition request language information `ko` \| `ja` \| `zh-TW` `ko`: Korean `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"`
`images`	Array	Required	images details Write as JSON array Able to create 1 image array per call Image size: up to 50 MB
`enableTableDetection`	Boolean	Optional	Whether 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.

Field	Type	Required	Description
`message`	Object	Required	Request data information
`file`	File	Required	OCR recognition image file
`message.version`	String	Required	Version information `V1` \| `V2` (recommended value) `V1`: Call V1 engine `V2`: Call V2 engine
`message.requestId`	String	Required	Random API call UUID
`message.timestamp`	Integer	Required	Random API call time (timestamp)
`message.lang`	String	Optional	OCR recognition request language information `ko` \| `ja` \| `zh-TW` `ko`: Korean `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.images`	Array	Required	images details Write as JSON array Able to create 1 image array per call Image size: up to 50 MB
`message.enableTableDetection`	Boolean	Optional	Whether 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.

Field	Type	Required	Description
`format`	String	Required	Image format `jpg` \| `jpeg` \| `png` \| `pdf` \| `tif` \| `tiff` `pdf`: up to 10 pages can be recognized
`name`	String	Required	Image name Use to identify images and check response results
`url`	String	Conditional	Image 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
`data`	String	Conditional	Base64-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 V1 version, the convertedImageInfo, type, and lineBreak information is not displayed in the response result value.

Response body

The response body includes the following data:

Field	Type	Required	Description
`version`	String	-	Version information `V1` \| `V2` `V1`: Call V1 engine `V2`: Call V2 engine
`requestId`	String	-	API call UUID
`timestamp`	Integer	-	API call time (timestamp)
`images`	Array	-	images details

`images`

The following describes images.

Field	Type	Required	Description
`uid`	String	-	Image UID Use for API validity checks and request tracing
`name`	String	-	Image name Use to identify images and check response results
`inferResult`	String	-	Image recognition result `SUCCESS` \| `FAILURE` \| `ERROR` `SUCCESS`: recognition successful `FAILURE`: recognition failure `ERROR`: recognition processing exception
`message`	String	-	Result message
`validationResult`	Object	-	Validity check result information
`validationResult.result`	String	-	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.message`	String	-	Validity check result details message This value is not always returned
`convertedImageInfo`	Object	-	Converted image information If `format` is `pdf` or `tiff` Coordinate values are set relative to the called image file
`convertedImageInfo.width`	Integer	-	Converted image width
`convertedImageInfo.height`	Integer	-	Converted image height
`convertedImageInfo.pageIndex`	Integer	-	Converted image page index
`convertedImageInfo.longImage`	Boolean	-	Whether the converted image length is long `true` \| `false` `true`: long image `false`: not a long image
`combineResult`	Object	-	Image recognition result combination information
`combineResult.name`	String	-	Image combination field name
`combineResult.text`	String	-	Output value and fixed text for each image field
`tables`	Array	-	Tables details
`fields`	Array	-	Fields details

`tables`

The following describes tables.

Field	Type	Required	Description
`cells`	Array	-	Cells details
`inferText`	String	-	Recognized text
`inferConfidence`	Float	-	Confidence of recognized text 0-1 The higher the confidence value, the more accurate the text is
`boundingPoly`	Object	-	Bounding poly information Provided only if `version` is `V2`
`boundingPoly.vertices`	Array	-	Bounding poly vertices details

`fields`

The following describes fields.

Field	Type	Required	Description
`name`	String	-	Image name Use to identify images and check response results Works only for API calls
`valueType`	String	-	Input value type `ALL` \| `NUMERIC` `ALL`: text and numbers `NUMERIC`: numbers
`boundingPoly`	Object	-	Bounding poly information Provided only if `version` is `V2`
`boundingPoly.vertices`	Array	-	Bounding poly vertices details
`inferText`	String	-	Recognized text If `type` is `CHECKBOX`, replace with response value specified in settings
`inferConfidence`	Float	-	Confidence of recognized text 0-1 The higher the confidence value, the more accurate the text is
`type`	String	-	Recognized image type `NORMAL` \| `MULTI_BOX` \| `CHECKBOX` `NORMAL`: general `MULTI_BOX`: multi-box `CHECKBOX`: checkbox
`lineBreak`	Boolean	-	Indicate whether the recognized text is the last line `true` \| `false` `true`: last text `false`: not last text
`checked`	Boolean	-	Checkbox selection `true` \| `false` `true`: selected `false`: not selected

`cells`

The following describes cells.

Field	Type	Required	Description
`boundingPoly`	Object	-	Bounding poly information Provided only if `version` is `V2`
`boundingPoly.vertices`	Array	-	Bounding poly vertices details
`cellTextLines`	Array	-	Cell's line details
`inferConfidence`	Float	-	Confidence of recognized text 0-1 The higher the confidence value, the more accurate the text is
`rowSpan`	Integer	-	Number of horizontal columns occupied by cells in the table (span)
`rowIndex`	Integer	-	Position value of the corresponding horizontal column in the table
`columnSpan`	Integer	-	Number of vertical rows occupied by cells in the table (span)
`columnIndex`	Integer	-	Position value of the corresponding vertical row in the table

`cellTextLines`

The following describes cellTextLines.

Field	Type	Required	Description
`boundingPoly`	Object	-	Bounding poly information Provided only if `version` is `V2`
`boundingPoly.vertices`	Array	-	Bounding poly vertices details
`inferConfidence`	Float	-	Confidence of recognized text 0-1 The higher the confidence value, the more accurate the text is
`cellWords`	Array	-	Cell's text details

`cellWords`

The following describes cellWords.

Field	Type	Required	Description
`boundingPoly`	Object	-	Bounding poly information Provided only if `version` is `V2`
`boundingPoly.vertices`	Array	-	Bounding poly vertices details
`inferConfidence`	Float	-	Confidence of recognized text 0-1 The higher the confidence value, the more accurate the text is
`inferText`	String	-	Recognized text

`vertices`

The following describes vertices.

Field	Type	Required	Description
`x`	Float	-	Bounding poly X-axis coordinate value
`y`	Float	-	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
                }
            ]
        }
    ]
}

General OCR

Request

Request headers

Request body

For Content-Type: application/json

For Content-Type: multipart/form-data

images

Request example

For Content-Type: application/json

For Content-Type: multipart/form-data

Response

Response body

images

tables

fields

cells

cellTextLines

cellWords

vertices

Response status codes

Response example

If version is V2

If version is V1

For `Content-Type: application/json`

For `Content-Type: multipart/form-data`

`images`

For `Content-Type: application/json`

For `Content-Type: multipart/form-data`

`images`

`tables`

`fields`

`cells`

`cellTextLines`

`cellWords`

`vertices`

If `version` is `V2`

If `version` is `V1`