CLOVA OCR Custom API

version

Requests

• Text OCR recognition and Template OCR recognition request

Request headers

Request bodies

Content-Type : application/json

1. Image recognition request

Detailed descriptions of image recognition request fields

CURL example:

curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--data-raw '{"images":[{"format":"jpg","name":"demo","url":"your image url"}],"requestId":"guide-json-demo","version":"V2","timestamp":1584062336793}'

Content-Type : multipart/form-data

1. Image Recognition Request

Form Data Message Value Description

CURL example:

curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--form 'message={"images":[{"format":"png","name":"demo"}],"requestId":"guide-demo","version":"V2","timestamp":1584062336793}' \
--form 'file=@image.png'

Responses

V1 response bodies

Request version is 'V1'

1. Image recognition result

Detailed descriptions of image recognition result fields

2. ImageField object

Detailed descriptions of ImageField object fields

3. Bounding object

Detailed descriptions of bounding object fields

V2 response bodies

Request version is 'V2'

1. Image Recognition Results

Detailed description of the Image Recognition Results field

2. ImageField object

ImageField Object Field Details

3. boundingPoly object

boundingPoly Object Field Details

4. vertices object

vertices Object Field Details

5. SubField Object

subField Object Field Details

6. ImageTable Object

ImageTable Object Field Details

7. TableCell Object

TableCell Object Field Details

8. CellTextLine Object

CellTextLine Object Field Details

9. CellWord Object

CellWord Object Field Details

Examples

Text OCR request examples

{
  "version": "V2",
  "requestId": "string",
  "timestamp": 0,
  "lang":"ko",
  "images": [
    {
      "format": "jpg",
      "name": "test 1",
      "url": "https://www.ncloud.com/ocr-test/test.jpg"
    }
  ]
}

Text OCR response examples

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1576569034247,
    "images": [{
        "uid": "9fd73a6aacad4025b3099a36ee55aacd",
        "name": "medium",
        "inferResult": "SUCCESS",
        "message": "SUCCESS",
        "fields": [{
                "valueType": "ALL",
                "inferText": "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",
                "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
                    }]
                }
            }
        ],
        "validationResult": {
            "result": "NO_REQUESTED"
        }
    }]
}

Template OCR request examples

{
  "version": "V1",
  "requestId": "string",
  "timestamp": 0,
  "lang":"ko",
  "images": [
    {
      "format": "jpg",
      "name": "test 1",
      "url": "https://www.ncloud.com/ocr-test/test.jpg",
      "templateIds":[390]
    }
  ]
}

Template OCR response examples

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1584067653255,
    "images": [
        {
            "uid": "1b220cd049de4a7c9e0dc1942d982867",
            "name": "test 1",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "matchedTemplate": {
                "id": 390,
                "name": "template"
            },
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "title": {
                "name": "title",
                "boundingPoly": {
                    "vertices": [
                        {
                            "x": 453.7125,
                            "y": 54.1125
                        },
                        {
                            "x": 961.5375,
                            "y": 54.1125
                        },
                        {
                            "x": 961.5375,
                            "y": 108.225
                        },
                        {
                            "x": 453.7125,
                            "y": 108.225
                        }
                    ]
                },
                "inferText": "Insurance claim form (monthly personal insurance)",
                "inferConfidence": 0.94674826
            },
            "fields": [
                {
                    "name": "id",
                    "valueType": "NUMERIC",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 488.88235,
                                "y": 284.92896
                            },
                            {
                                "x": 550.3732,
                                "y": 284.93716
                            },
                            {
                                "x": 550.39166,
                                "y": 333.93698
                            },
                            {
                                "x": 488.90073,
                                "y": 333.9292
                            }
                        ]
                    },
                    "inferText": "102831",
                    "inferConfidence": 0.9319761,
                    "type": "MULTI_BOX",
                    "subFields": [
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 488.88235,
                                        "y": 284.92896
                                    },
                                    {
                                        "x": 550.3732,
                                        "y": 284.93716
                                    },
                                    {
                                        "x": 550.39166,
                                        "y": 333.93698
                                    },
                                    {
                                        "x": 488.90073,
                                        "y": 333.9292
                                    }
                                ]
                            },
                            "inferText": "1",
                            "inferConfidence": 0.9798796
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 551.37305,
                                        "y": 284.9373
                                    },
                                    {
                                        "x": 612.86285,
                                        "y": 284.9455
                                    },
                                    {
                                        "x": 612.88153,
                                        "y": 333.94495
                                    },
                                    {
                                        "x": 551.39154,
                                        "y": 333.9371
                                    }
                                ]
                            },
                            "inferText": "0",
                            "inferConfidence": 0.6391636
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 613.86273,
                                        "y": 284.94562
                                    },
                                    {
                                        "x": 675.3515,
                                        "y": 284.95383
                                    },
                                    {
                                        "x": 675.3702,
                                        "y": 333.95288
                                    },
                                    {
                                        "x": 613.8812,
                                        "y": 333.94504
                                    }
                                ]
                            },
                            "inferText": "2",
                            "inferConfidence": 0.99591047
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 676.3513,
                                        "y": 284.95395
                                    },
                                    {
                                        "x": 737.8392,
                                        "y": 284.9622
                                    },
                                    {
                                        "x": 737.8579,
                                        "y": 333.96082
                                    },
                                    {
                                        "x": 676.37006,
                                        "y": 333.953
                                    }
                                ]
                            },
                            "inferText": "8",
                            "inferConfidence": 0.99782735
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 738.83887,
                                        "y": 284.96228
                                    },
                                    {
                                        "x": 800.3257,
                                        "y": 284.97052
                                    },
                                    {
                                        "x": 800.34454,
                                        "y": 333.96872
                                    },
                                    {
                                        "x": 738.8577,
                                        "y": 333.9609
                                    }
                                ]
                            },
                            "inferText": "3",
                            "inferConfidence": 0.99916536
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 801.3255,
                                        "y": 284.97064
                                    },
                                    {
                                        "x": 862.8112,
                                        "y": 284.97882
                                    },
                                    {
                                        "x": 862.8301,
                                        "y": 333.97662
                                    },
                                    {
                                        "x": 801.3443,
                                        "y": 333.96884
                                    }
                                ]
                            },
                            "inferText": "1",
                            "inferConfidence": 0.9799099
                        }
                    ]
                },
                {
                    "name": "name",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 287.2125,
                                "y": 287.2125
                            },
                            {
                                "x": 380.86874,
                                "y": 287.2125
                            },
                            {
                                "x": 380.86874,
                                "y": 328.8375
                            },
                            {
                                "x": 287.2125,
                                "y": 328.8375
                            }
                        ]
                    },
                    "inferText": "David",
                    "inferConfidence": 0.99630755,
                    "type": "NORMAL"
                },
                {
                    "name": "fax-checkbox",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 87.08151,
                                "y": 736.90735
                            },
                            {
                                "x": 140.0801,
                                "y": 736.91125
                            },
                            {
                                "x": 140.10016,
                                "y": 791.9156
                            },
                            {
                                "x": 87.101494,
                                "y": 791.9121
                            }
                        ]
                    },
                    "inferText": "",
                    "inferConfidence": 0.99464625,
                    "type": "CHECKBOX",
                    "checked": true
                }
            ]
        }
    ]
}

API examples

The following are some examples of CLOVA OCR API implementation for each language

• Request with multipart/form-data

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;

import org.json.JSONArray;
import org.json.JSONObject;

public class OCRGeneralAPIDemo {

	public static void main(String[] args) {
		String apiURL = "YOUR_API_URL";
		String secretKey = "YOUR_SECRET_KEY";
		String imageFile = "YOUR_IMAGE_FILE";

		try {
			URL url = new URL(apiURL);
			HttpURLConnection con = (HttpURLConnection)url.openConnection();
			con.setUseCaches(false);
			con.setDoInput(true);
			con.setDoOutput(true);
			con.setReadTimeout(30000);
			con.setRequestMethod("POST");
			String boundary = "----" + UUID.randomUUID().toString().replaceAll("-", "");
			con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
			con.setRequestProperty("X-OCR-SECRET", secretKey);

			JSONObject json = new JSONObject();
			json.put("version", "V2");
			json.put("requestId", UUID.randomUUID().toString());
			json.put("timestamp", System.currentTimeMillis());
			JSONObject image = new JSONObject();
			image.put("format", "jpg");
			image.put("name", "demo");
			JSONArray images = new JSONArray();
			images.put(image);
			json.put("images", images);
			String postParams = json.toString();

			con.connect();
			DataOutputStream wr = new DataOutputStream(con.getOutputStream());
			long start = System.currentTimeMillis();
			File file = new File(imageFile);
			writeMultiPart(wr, postParams, file, boundary);
			wr.close();

			int responseCode = con.getResponseCode();
			BufferedReader br;
			if (responseCode == 200) {
				br = new BufferedReader(new InputStreamReader(con.getInputStream()));
			} else {
				br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
			}
			String inputLine;
			StringBuffer response = new StringBuffer();
			while ((inputLine = br.readLine()) != null) {
				response.append(inputLine);
			}
			br.close();

			System.out.println(response);
		} catch (Exception e) {
			System.out.println(e);
		}
	}

	private static void writeMultiPart(OutputStream out, String jsonMessage, File file, String boundary) throws
		IOException {
		StringBuilder sb = new StringBuilder();
		sb.append("--").append(boundary).append("\r\n");
		sb.append("Content-Disposition:form-data; name=\"message\"\r\n\r\n");
		sb.append(jsonMessage);
		sb.append("\r\n");

		out.write(sb.toString().getBytes("UTF-8"));
		out.flush();

		if (file != null && file.isFile()) {
			out.write(("--" + boundary + "\r\n").getBytes("UTF-8"));
			StringBuilder fileString = new StringBuilder();
			fileString
				.append("Content-Disposition:form-data; name=\"file\"; filename=");
			fileString.append("\"" + file.getName() + "\"\r\n");
			fileString.append("Content-Type: application/octet-stream\r\n\r\n");
			out.write(fileString.toString().getBytes("UTF-8"));
			out.flush();

			try (FileInputStream fis = new FileInputStream(file)) {
				byte[] buffer = new byte[8192];
				int count;
				while ((count = fis.read(buffer)) != -1) {
					out.write(buffer, 0, count);
				}
				out.write("\r\n".getBytes());
			}

			out.write(("--" + boundary + "--\r\n").getBytes("UTF-8"));
		}
		out.flush();
	}
}

import requests
import uuid
import time
import json

api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_file = 'YOUR_IMAGE_FILE'

request_json = {
    'images': [
        {
            'format': 'jpg',
            'name': 'demo'
        }
    ],
    'requestId': str(uuid.uuid4()),
    'version': 'V2',
    'timestamp': int(round(time.time() * 1000))
}

payload = {'message': json.dumps(request_json).encode('UTF-8')}
files = [
  ('file', open(image_file,'rb'))
]
headers = {
  'X-OCR-SECRET': secret_key
}

response = requests.request("POST", api_url, headers=headers, data = payload, files = files)

print(response.text.encode('utf8'))

<?php
  $client_secret = "YOUR_SECRET_KEY";
  $url = "YOUR_API_URL";
  $image_file = "YOUR_IMAGE_FILE";

  $params->version = "V2";
  $params->requestId = uniqid();
  $params->timestamp = time();
  $image->format = "jpg";
  $image->name = "demo";
  $images = array($image);
  $params->images = $images;
  $json = json_encode($params);
  
  $boundary = uniqid();
  $is_post = true;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $post_form = array("message" => $json, "file" => new CURLFILE($image_file));
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_form);
  $headers = array();
  $headers[] = "X-OCR-SECRET: ".$client_secret;
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close ($ch);

  echo $status_code;
  if($status_code == 200) {
    echo $response;
  } else {
    echo "ERROR: ".$response;
  }
?>

const FormData = require('form-data')
const axios = require('axios')

function requestWithBase64 () {
  axios
    .post(
      '', // APIGW Invoke URL
      {
        images: [
          {
            format: '', // file format
            name: '', // image name
            data: '' // image base64 string(only need part of data). Example: base64String.split(',')[1]
          }
        ],
        requestId: '', // unique string
        timestamp: 0,
        version: 'V2'
      },
      {
        headers: {
          'X-OCR-SECRET': '' // Secret Key 
        }
      }
    )
    .then(res => {
      if (res.status === 200) {
        console.log('requestWithBase64 response:', res.data)
      }
    })
    .catch(e => {
      console.warn('requestWithBase64 error', e.response)
    })
}

function requestWithFile () {
  const file = '' // image file object. Example: fs.createReadStream('./example.png')
  const message = {
    images: [
      {
        format: '', // file format
        name: '' // file name
      }
    ],
    requestId: '', // unique string
    timestamp: 0,
    version: 'V2'
  }
  const formData = new FormData()

  formData.append('file', file)
  formData.append('message', JSON.stringify(message))

  axios
    .post(
      '', // APIGW Invoke URL
      formData,
      {
        headers: {
          'X-OCR-SECRET': '', // Secret Key 
          ...formData.getHeaders()
        }
      }
    )
    .then(res => {
      if (res.status === 200) {
        console.log('requestWithFile response:', res.data)
      }
    })
    .catch(e => {
      console.warn('requestWithFile error', e.response)
    })
}

• Request with application/json

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;

import org.json.JSONArray;
import org.json.JSONObject;

public class OCRGeneralAPIDemo {

	public static void main(String[] args) {
		String apiURL = "YOUR_API_URL";
		String secretKey = "YOUR_SECRET_KEY";

		try {
			URL url = new URL(apiURL);
			HttpURLConnection con = (HttpURLConnection)url.openConnection();
			con.setUseCaches(false);
			con.setDoInput(true);
			con.setDoOutput(true);
			con.setRequestMethod("POST");
			con.setRequestProperty("Content-Type", "application/json; charset=utf-8");
			con.setRequestProperty("X-OCR-SECRET", secretKey);

			JSONObject json = new JSONObject();
			json.put("version", "V2");
			json.put("requestId", UUID.randomUUID().toString());
			json.put("timestamp", System.currentTimeMillis());
			JSONObject image = new JSONObject();
			image.put("format", "jpg");
			image.put("url", "https://kr.object.ncloudstorage.com/ocr-ci-test/sample/1.jpg"); // image should be public, otherwise, should use data
			// FileInputStream inputStream = new FileInputStream("YOUR_IMAGE_FILE");
			// byte[] buffer = new byte[inputStream.available()];
			// inputStream.read(buffer);
			// inputStream.close();
			// image.put("data", buffer);
			image.put("name", "demo");
			JSONArray images = new JSONArray();
			images.put(image);
			json.put("images", images);
			String postParams = json.toString();

			DataOutputStream wr = new DataOutputStream(con.getOutputStream());
			wr.writeBytes(postParams);
			wr.flush();
			wr.close();

			int responseCode = con.getResponseCode();
			BufferedReader br;
			if (responseCode == 200) {
				br = new BufferedReader(new InputStreamReader(con.getInputStream()));
			} else {
				br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
			}
			String inputLine;
			StringBuffer response = new StringBuffer();
			while ((inputLine = br.readLine()) != null) {
				response.append(inputLine);
			}
			br.close();

			System.out.println(response);
		} catch (Exception e) {
			System.out.println(e);
		}
	}

}

import requests
import uuid
import time
import base64
import json

api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_url = 'YOUR_IMAGE_URL'
# image_file = 'YOUR_IMAGE_FILE'
# with open(image_file,'rb') as f:
#     file_data = f.read()

request_json = {
    'images': [
        {
            'format': 'jpg',
            'name': 'demo',
#             'data': base64.b64encode(file_data).decode()
            'url': image_url
        }
    ],
    'requestId': str(uuid.uuid4()),
    'version': 'V2',
    'timestamp': int(round(time.time() * 1000))
}

payload = json.dumps(request_json).encode('UTF-8')
headers = {
  'X-OCR-SECRET': secret_key,
  'Content-Type': 'application/json'
}

response = requests.request("POST", api_url, headers=headers, data = payload)

print(response.text)

<?php
  $client_secret = "YOUR_SECRET_KEY";
  $url = "YOUR_API_URL";
  $image_url = "YOUR_IMAGE_URL";
  // $image_file = "YOUR_IMAGE_FILE";

  $params->version = "V2";
  $params->requestId = "uuid";
  $params->timestamp = time();
  $image->format = "jpg";
  $image->url = $image_url;
  // $image->data = base64_encode(file_get_contents($image_file));
  $image->name = "demo";
  $images = array($image);
  $params->images = $images;
  $json = json_encode($params);

  $is_post = true;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
  $headers = array();
  $headers[] = "X-OCR-SECRET: ".$client_secret;
  $headers[] = "Content-Type:application/json; charset=utf-8";
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close ($ch);

  echo $status_code;
  if($status_code == 200) {
    echo $response;
  } else {
    echo "ERROR: ".$response;
  }
?>

<%
Function ASPPostJSON()
    Dim objXmlHttp
    Set objXmlHttp = Server.CreateObject("Microsoft.XMLHTTP")
    url = "YOUR_INVOKE_URL"
    secret = "YOUR_SECRET_KEY"
    base64 = """"+ToBase64(getBinaryFile(Server.MapPath("test.jpg")))+""""
    body = "{""images"":[{""format"":""jpg"",""name"":""test 1"",""data"":"+base64+"}],""requestId"":""string"",""timestamp"":0,""version"":""V2"",""lang"":""ko""}"
    objXmlHttp.Open "POST", url, False
    objXmlHttp.SetRequestHeader "Content-Type", "application/json"
    objXmlHttp.SetRequestHeader "X-OCR-SECRET", secret

    objXmlHttp.Send body

    ASPPostJSON = CStr(objXmlHttp.ResponseText)

    Response.write(ASPPostJSON)
    Set objXmlHttp = Nothing

End Function

Function getBinaryFile(strFilePath)
  Dim TypeBinary, oStream

  TypeBinary = 1

  Set oStream = Server.CreateObject("ADODB.Stream")

  oStream.Open

  oStream.Type = TypeBinary
  oStream.LoadFromFile strFilePath

  getBinaryFile = oStream.read

  Set oStream = Nothing

End Function

Function ToBase64(rabyt)

     Dim xml: Set xml = CreateObject("MSXML2.DOMDocument.3.0")
     xml.LoadXml "<root />"
     xml.documentElement.dataType = "bin.base64"
     xml.documentElement.nodeTypedValue = rabyt

     ToBase64 = xml.documentElement.Text

End Function

call ASPPostJSON()
%>

Error code

Error Response Body:

{
  "code": "Error Code",
  "message": "error details message.",
  "path": "request API path",
  "timestamp": 1570776853475
}