Available in Classic and VPC
Recognize and extract text based on a template that specifies the reading area of an image directly from the NAVER Cloud Platform console.
Request
This section describes the request format. The method and URI are as follows:
| Method | URI |
|---|---|
| POST | /infer |
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
|
requestId |
String | Required | Random API call UUID |
timestamp |
Integer | Required | Random API call time (timestamp) |
lang |
String | Optional | OCR recognition request language information
|
images |
Array | Required | images details
|
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 |
message.version |
String | Required | Version information
|
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
|
message.images |
Array | Required | images details
|
file |
File | Required | OCR recognition image file |
images
The following describes images.
| Field | Type | Required | Description |
|---|---|---|---|
format |
String | Required | Image format
|
name |
String | Required | Image name
|
url |
String | Conditional | Image URL address
|
data |
String | Conditional | Base64-encoded image data
|
templateIds |
Integer | Optional | Template ID
|
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/33661/f5d739754b0ed5bdaa51365b7d**********a5bbdd069e0db430d5f5adb490b/infer' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--data '{
"version": "V2",
"requestId": "string",
"timestamp": 0,
"lang":"ko",
"images": [
{
"format": "pdf",
"name": "test 1",
"url": "{url}",
"templateIds":[31677]
}
}'
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/33661/f5d739754b0ed5bdaa51365b7d**********bbdd069e0db430d5f5adb490b/infer' \
--header 'Content-Type: multipart/form-data' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--form '{file}.jpg"' \
--form 'message="{\"version\": \"V1\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"jpg\", \"name\": \"hello\"}]}"'
Response
This section describes the response format.
Note
- When requesting with the
V1version, the coordinate information is displayed inboundingof the response result value. - When requesting with the
V1version, theconvertedImageInfo,valueType,type, andsubFieldsinformation 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
|
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
|
name |
String | - | Image name
|
inferResult |
String | - | Image inference result
|
message |
String | - | Result message |
matchedTemplate |
Object | - | Template information
|
matchedTemplate.id |
Integer | - | Template ID |
matchedTemplate.name |
String | - | Template name |
validationResult |
Object | - | Validity check result information |
validationResult.result |
String | - | Validity check result code
|
validationResult.message |
String | - | Validity check result details message
|
convertedImageInfo |
Object | - | Converted image information
|
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
|
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 |
fields |
Array | - | Fields details |
title |
Object | - | Image title details |
title.name |
String | - | Template representative sample field names
|
title.boundingPoly |
Object | - | Bounding poly information
|
title.boundingPoly.vertices |
Array | - | Bounding poly vertices details |
title.inferText |
String | - | Recognized text
|
title.inferConfidence |
Float | - | Confidence of recognized text
|
title.subFields |
Array | - | subFields details |
fields
The following describes fields.
| Field | Type | Required | Description |
|---|---|---|---|
name |
String | - | Template field name
|
valueType |
String | - | Input value type
|
boundingPoly |
Object | - | Bounding poly information
|
boundingPoly.vertices |
Array | - | Bounding poly vertices details |
inferText |
String | - | Recognized text
|
inferConfidence |
Float | - | Confidence of recognized text
|
type |
String | - | Recognized image type
|
subFields |
Array | - | subFields details |
checked |
Boolean | - | Checkbox selection
|
subFields
The following describes fields.subFields.
| Field | Type | Required | Description |
|---|---|---|---|
boundingPoly |
Object | - | Bounding poly information
|
boundingPoly.vertices |
Array | - | Bounding poly vertices details |
inferText |
String | - | Recognized text
|
inferConfidence |
Float | - | Confidence of recognized text
|
lineBreak |
Boolean | - | Indicate whether the recognized text is the last line
|
vertices
The following describes boundingPoly.vertices.
| Field | Type | Required | Description |
|---|---|---|---|
x |
Float | - | Bounding poly X-axis coordinate value |
y |
Float | - | Bounding poly Y-axis coordinate value |
bounding
The following describes bounding.
| Field | Type | Required | Description |
|---|---|---|---|
top |
Float | - | Bounding Y-axis coordinate value |
left |
Float | - | Bounding X-axis coordinate value |
width |
Float | - | Bounding poly width |
height |
Float | - | Bounding poly height |
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:
Succeeded
The following is a sample response upon a successful call.
{
"version": "V2",
"requestId": "string",
"timestamp": 1724831491715,
"images": [
{
"uid": "{uid}",
"name": "test 1",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"matchedTemplate": {
"id": 31677,
"name": "Business registration certificate"
},
"validationResult": {
"result": "NO_REQUESTED"
},
"convertedImageInfo": {
"width": 1190,
"height": 1682,
"pageIndex": 0,
"longImage": false
},
"fields": [
{
"name": "Registration number",
"valueType": "ALL",
"boundingPoly": {
"vertices": [
{
"x": 551.0,
"y": 310.0
},
{
"x": 775.0,
"y": 310.0
},
{
"x": 775.0,
"y": 350.0
},
{
"x": 551.0,
"y": 350.0
}
]
},
"inferText": "***-**-*****",
"inferConfidence": 1.0,
"type": "NORMAL",
"subFields": [
{
"boundingPoly": {
"vertices": [
{
"x": 551.0,
"y": 310.0
},
{
"x": 775.0,
"y": 310.0
},
{
"x": 775.0,
"y": 350.0
},
{
"x": 551.0,
"y": 350.0
}
]
},
"inferText": "***-**-*****",
"inferConfidence": 1.0,
"lineBreak": true
}
]
},
{
"name": "Corporate name_organization name",
"valueType": "ALL",
"boundingPoly": {
"vertices": [
{
"x": 317.0,
"y": 369.0
},
{
"x": 511.0,
"y": 369.0
},
{
"x": 511.0,
"y": 402.0
},
{
"x": 317.0,
"y": 402.0
}
]
},
"inferText": "***** Inc.",
"inferConfidence": 0.9999,
"type": "NORMAL",
"subFields": [
{
"boundingPoly": {
"vertices": [
{
"x": 317.0,
"y": 369.0
},
{
"x": 451.0,
"y": 369.0
},
{
"x": 451.0,
"y": 402.0
},
{
"x": 317.0,
"y": 402.0
}
]
},
"inferText": "*****",
"inferConfidence": 0.9998,
"lineBreak": false
},
{
"boundingPoly": {
"vertices": [
{
"x": 459.0,
"y": 371.0
},
{
"x": 511.0,
"y": 371.0
},
{
"x": 511.0,
"y": 399.0
},
{
"x": 459.0,
"y": 399.0
}
]
},
"inferText": "Inc.",
"inferConfidence": 1.0,
"lineBreak": true
}
]
},
{
"name": "Business start date",
"valueType": "ALL",
"boundingPoly": {
"vertices": [
{
"x": 316.0,
"y": 493.0
},
{
"x": 564.0,
"y": 495.0
},
{
"x": 564.0,
"y": 526.0
},
{
"x": 314.0,
"y": 526.0
}
]
},
"inferText": "June 01, 1975",
"inferConfidence": 0.99796,
"type": "NORMAL",
"subFields": [
{
"boundingPoly": {
"vertices": [
{
"x": 316.0,
"y": 493.0
},
{
"x": 374.0,
"y": 496.0
},
{
"x": 373.0,
"y": 525.0
},
{
"x": 314.0,
"y": 522.0
}
]
},
"inferText": "1975",
"inferConfidence": 1.0,
"lineBreak": false
},
{
"boundingPoly": {
"vertices": [
{
"x": 380.0,
"y": 495.0
},
{
"x": 410.0,
"y": 495.0
},
{
"x": 410.0,
"y": 526.0
},
{
"x": 380.0,
"y": 526.0
}
]
},
"inferText": "Year",
"inferConfidence": 0.9999,
"lineBreak": false
},
{
"boundingPoly": {
"vertices": [
{
"x": 417.0,
"y": 495.0
},
{
"x": 451.0,
"y": 495.0
},
{
"x": 451.0,
"y": 523.0
},
{
"x": 417.0,
"y": 523.0
}
]
},
"inferText": "06",
"inferConfidence": 1.0,
"lineBreak": false
},
{
"boundingPoly": {
"vertices": [
{
"x": 457.0,
"y": 495.0
},
{
"x": 490.0,
"y": 495.0
},
{
"x": 490.0,
"y": 524.0
},
{
"x": 457.0,
"y": 524.0
}
]
},
"inferText": "Month",
"inferConfidence": 0.9997,
"lineBreak": false
},
{
"boundingPoly": {
"vertices": [
{
"x": 494.0,
"y": 495.0
},
{
"x": 564.0,
"y": 495.0
},
{
"x": 564.0,
"y": 523.0
},
{
"x": 494.0,
"y": 523.0
}
]
},
"inferText": "1st",
"inferConfidence": 0.9902,
"lineBreak": false
}
]
},
{
"name": "Business place location",
"valueType": "ALL",
"boundingPoly": {
"vertices": [
{
"x": 315.0,
"y": 534.0
},
{
"x": 852.0,
"y": 534.0
},
{
"x": 852.0,
"y": 568.0
},
{
"x": 315.0,
"y": 568.0
}
]
},
"inferText": "Gyeonggi-do ******",
"inferConfidence": 0.99223995,
"type": "NORMAL",
"subFields": [
{
"boundingPoly": {
"vertices": [
{
"x": 315.0,
"y": 535.0
},
{
"x": 397.0,
"y": 535.0
},
{
"x": 397.0,
"y": 568.0
},
{
"x": 315.0,
"y": 568.0
}
]
},
"inferText": "Gyeonggi-do",
"inferConfidence": 1.0,
"lineBreak": false
}
]
},
{
"name": "CEO",
"valueType": "ALL",
"boundingPoly": {
"vertices": [
{
"x": 300.66458,
"y": 404.66934
},
{
"x": 910.0876,
"y": 400.79553
},
{
"x": 909.6188,
"y": 478.17303
},
{
"x": 300.49875,
"y": 481.97482
}
]
},
"inferText": "",
"inferConfidence": 0.0,
"type": "NORMAL"
}
],
"title": {
"name": "Business registration certificate",
"boundingPoly": {
"vertices": [
{
"x": 330.0,
"y": 188.0
},
{
"x": 795.0,
"y": 186.0
},
{
"x": 795.0,
"y": 252.0
},
{
"x": 330.0,
"y": 253.0
}
]
},
"inferText": "Business registration certificate",
"inferConfidence": 0.9998,
"subFields": [
{
"boundingPoly": {
"vertices": [
{
"x": 330.0,
"y": 188.0
},
{
"x": 795.0,
"y": 186.0
},
{
"x": 795.0,
"y": 252.0
},
{
"x": 330.0,
"y": 253.0
}
]
},
"inferText": "Business registration certificate",
"inferConfidence": 0.9998,
"lineBreak": true
}
]
}
},
]
}
Failure
The following is a sample response upon a failed call.
{
"version": "V1",
"requestId": "1234",
"timestamp": 1724833931723,
"images": [
{
"uid": "{uid}",
"name": "hello",
"inferResult": "FAILURE",
"message": "NOT_FOUND: not found matched template",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}