CLOVA OCR Custom API

version

요청

TEXT OCR 인식과 Template OCR 인식 요청

요청 헤더

요청 바디

Content-Type : application/json

1. 이미지 인식 요청

이미지 인식 요청 필드 상세 설명

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'

응답

V1 응답 바디

Request version is 'V1'

1. 이미지 인식 결과

이미지 인식 결과 필드 상세 설명

2. ImageField 객체

ImageField 객체 필드 상세 설명

3. bounding객체

bounding 객체 필드 상세 설명

V2 응답 바디

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

예시

TEXT OCR 요청 예시

{
  "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 응답 예시

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1576569034247,
    "images": [{
        "uid": "9fd73a6aacad4025b3099a36ee55aacd",
        "name": "medium",
        "inferResult": "SUCCESS",
        "message": "SUCCESS",
        "fields": [{
                "valueType": "ALL",
                "inferText": "아름다운",
                "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": "이",
                "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": "세상",
                "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 요청 예시

{
  "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 응답 예시

{
    "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": "보험금 청구서 (인보험月)",
                "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 예제

다음은 각 언어별 CLOVA OCR API 구현 예제입니다

• 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
}